mirror of
https://github.com/terraform-docs/terraform-docs.git
synced 2026-03-27 12:58:35 +07:00
1450ee9a10
Considering the file strucutre below of main module and its submodules, now it is possible to generate documentation for them main and all its submodules in one execution, with `--recursive` flag. Note that generating documentation recursively is allowed only with `--output-file` set. Path to find submodules can be configured with `--recursive-path` (defaults to `modules`). Each submodule can also have their own `.terraform-docs.yml` confi file, to override configuration from root module. ``` . ├── README.md ├── main.tf ├── modules │ └── my-sub-module │ ├── README.md │ ├── main.tf │ ├── variables.tf │ └── versions.tf ├── outputs.tf ├── variables.tf └── versions.tf ``` Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
11 KiB
11 KiB
title, description, menu, weight, toc
| title | description | menu | weight | toc | ||||
|---|---|---|---|---|---|---|---|---|
| asciidoc document | Generate AsciiDoc document of inputs and outputs. |
|
952 | true |
Synopsis
Generate AsciiDoc document of inputs and outputs.
terraform-docs asciidoc document [PATH] [flags]
Options
-h, --help help for document
Inherited Options
--anchor create anchor links (default true)
-c, --config string config file name (default ".terraform-docs.yml")
--default show Default column or section (default true)
--footer-from string relative path of a file to read footer from (default "")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--indent int indention level of AsciiDoc sections [1, 2, 3, 4, 5] (default 2)
--lockfile read .terraform.lock.hcl if exist (default true)
--output-check check if content of output file is up to date (default false)
--output-file string file path to insert output into (default "")
--output-mode string output to file method [inject, replace] (default "inject")
--output-template string output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--recursive update submodules recursively (default false)
--recursive-path string submodules path to recursively update (default "modules")
--required show Required column or section (default true)
--sensitive show Sensitive column or section (default true)
--show strings show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--sort sort items (default true)
--sort-by string sort items by criteria [name, required, type] (default "name")
--type show Type column or section (default true)
Example
Given the examples module:
terraform-docs asciidoc document --footer-from footer.md ./examples/
generates the following output:
Usage:
Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1
- list item 2
Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/)
* list item 3
* list item 4
```hcl
module "foo_bar" {
source = "github.com/foo/bar"
id = "1234567890"
name = "baz"
zones = ["us-east-1", "us-west-1"]
tags = {
Name = "baz"
Created-By = "first.last@email.com"
Date-Created = "20180101"
}
}
```
Here is some trailing text after code block,
followed by another line of text.
| Name | Description |
|------|-----------------|
| Foo | Foo description |
| Bar | Bar description |
== Requirements
The following requirements are needed by this module:
- [[requirement_terraform]] <<requirement_terraform,terraform>> (>= 0.12)
- [[requirement_aws]] <<requirement_aws,aws>> (>= 2.15.0)
- [[requirement_foo]] <<requirement_foo,foo>> (>= 1.0)
- [[requirement_random]] <<requirement_random,random>> (>= 2.2.0)
== Providers
The following providers are used by this module:
- [[provider_aws]] <<provider_aws,aws>> (>= 2.15.0)
- [[provider_aws.ident]] <<provider_aws.ident,aws.ident>> (>= 2.15.0)
- [[provider_foo]] <<provider_foo,foo>> (>= 1.0)
- [[provider_null]] <<provider_null,null>>
- [[provider_tls]] <<provider_tls,tls>>
== Modules
The following Modules are called:
=== [[module_bar]] <<module_bar,bar>>
Source: baz
Version: 4.5.6
=== [[module_baz]] <<module_baz,baz>>
Source: baz
Version: 4.5.6
=== [[module_foo]] <<module_foo,foo>>
Source: bar
Version: 1.2.3
=== [[module_foobar]] <<module_foobar,foobar>>
Source: git@github.com:module/path
Version: v7.8.9
== Resources
The following resources are used by this module:
- foo_resource.baz (resource)
- https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource[null_resource.foo] (resource)
- https://registry.terraform.io/providers/hashicorp/tls/latest/docs/resources/private_key[tls_private_key.baz] (resource)
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity[aws_caller_identity.current] (data source)
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity[aws_caller_identity.ident] (data source)
== Required Inputs
The following input variables are required:
=== [[input_input_with_underscores]] <<input_input_with_underscores,input_with_underscores>>
Description: A variable with underscores.
Type: `any`
=== [[input_list-2]] <<input_list-2,list-2>>
Description: It's list number two.
Type: `list`
=== [[input_map-2]] <<input_map-2,map-2>>
Description: It's map number two.
Type: `map`
=== [[input_number-2]] <<input_number-2,number-2>>
Description: It's number number two.
Type: `number`
=== [[input_string-2]] <<input_string-2,string-2>>
Description: It's string number two.
Type: `string`
=== [[input_string_no_default]] <<input_string_no_default,string_no_default>>
Description: n/a
Type: `string`
=== [[input_unquoted]] <<input_unquoted,unquoted>>
Description: n/a
Type: `any`
== Optional Inputs
The following input variables are optional (have default values):
=== [[input_bool-1]] <<input_bool-1,bool-1>>
Description: It's bool number one.
Type: `bool`
Default: `true`
=== [[input_bool-2]] <<input_bool-2,bool-2>>
Description: It's bool number two.
Type: `bool`
Default: `false`
=== [[input_bool-3]] <<input_bool-3,bool-3>>
Description: n/a
Type: `bool`
Default: `true`
=== [[input_bool_default_false]] <<input_bool_default_false,bool_default_false>>
Description: n/a
Type: `bool`
Default: `false`
=== [[input_input-with-code-block]] <<input_input-with-code-block,input-with-code-block>>
Description: This is a complicated one. We need a newline.
And an example in a code block
```
default = [
"machine rack01:neptune"
]
```
Type: `list`
Default:
[source,json]
----
[
"name rack:location"
]
----
=== [[input_input-with-pipe]] <<input_input-with-pipe,input-with-pipe>>
Description: It includes v1 | v2 | v3
Type: `string`
Default: `"v1"`
=== [[input_list-1]] <<input_list-1,list-1>>
Description: It's list number one.
Type: `list`
Default:
[source,json]
----
[
"a",
"b",
"c"
]
----
=== [[input_list-3]] <<input_list-3,list-3>>
Description: n/a
Type: `list`
Default: `[]`
=== [[input_list_default_empty]] <<input_list_default_empty,list_default_empty>>
Description: n/a
Type: `list(string)`
Default: `[]`
=== [[input_long_type]] <<input_long_type,long_type>>
Description: This description is itself markdown.
It spans over multiple lines.
Type:
[source,hcl]
----
object({
name = string,
foo = object({ foo = string, bar = string }),
bar = object({ foo = string, bar = string }),
fizz = list(string),
buzz = list(string)
})
----
Default:
[source,json]
----
{
"bar": {
"bar": "bar",
"foo": "bar"
},
"buzz": [
"fizz",
"buzz"
],
"fizz": [],
"foo": {
"bar": "foo",
"foo": "foo"
},
"name": "hello"
}
----
=== [[input_map-1]] <<input_map-1,map-1>>
Description: It's map number one.
Type: `map`
Default:
[source,json]
----
{
"a": 1,
"b": 2,
"c": 3
}
----
=== [[input_map-3]] <<input_map-3,map-3>>
Description: n/a
Type: `map`
Default: `{}`
=== [[input_no-escape-default-value]] <<input_no-escape-default-value,no-escape-default-value>>
Description: The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'.
Type: `string`
Default: `"VALUE_WITH_UNDERSCORE"`
=== [[input_number-1]] <<input_number-1,number-1>>
Description: It's number number one.
Type: `number`
Default: `42`
=== [[input_number-3]] <<input_number-3,number-3>>
Description: n/a
Type: `number`
Default: `"19"`
=== [[input_number-4]] <<input_number-4,number-4>>
Description: n/a
Type: `number`
Default: `15.75`
=== [[input_number_default_zero]] <<input_number_default_zero,number_default_zero>>
Description: n/a
Type: `number`
Default: `0`
=== [[input_object_default_empty]] <<input_object_default_empty,object_default_empty>>
Description: n/a
Type: `object({})`
Default: `{}`
=== [[input_string-1]] <<input_string-1,string-1>>
Description: It's string number one.
Type: `string`
Default: `"bar"`
=== [[input_string-3]] <<input_string-3,string-3>>
Description: n/a
Type: `string`
Default: `""`
=== [[input_string-special-chars]] <<input_string-special-chars,string-special-chars>>
Description: n/a
Type: `string`
Default: `"\\.<>[]{}_-"`
=== [[input_string_default_empty]] <<input_string_default_empty,string_default_empty>>
Description: n/a
Type: `string`
Default: `""`
=== [[input_string_default_null]] <<input_string_default_null,string_default_null>>
Description: n/a
Type: `string`
Default: `null`
=== [[input_with-url]] <<input_with-url,with-url>>
Description: The description contains url. https://www.domain.com/foo/bar_baz.html
Type: `string`
Default: `""`
== Outputs
The following outputs are exported:
=== [[output_output-0.12]] <<output_output-0.12,output-0.12>>
Description: terraform 0.12 only
=== [[output_output-1]] <<output_output-1,output-1>>
Description: It's output number one.
=== [[output_output-2]] <<output_output-2,output-2>>
Description: It's output number two.
=== [[output_unquoted]] <<output_unquoted,unquoted>>
Description: It's unquoted output.
## This is an example of a footer
It looks exactly like a header, but is placed at the end of the document