mirror of
https://github.com/terraform-docs/terraform-docs.git
synced 2026-03-27 04:48:33 +07:00
5256426650
New flag, `--lockfile`, is added to control whether ignore reading .terraform.lock.hcl file in an attempt to extract the exact version of provider being used or not. Default is true. If set to true, exact version of provider available in lock file at the time of execution will be extracted. If set to false, the version in .tf file will be used (either exact, or a constrained version: >=, ~>, ...) 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 "")
--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