centersl/terraform-docs
1
0
Fork 0
mirror of https://github.com/terraform-docs/terraform-docs.git synced 2026-03-27 12:58:35 +07:00
Code Issues Packages Projects Releases Wiki Activity

Refactor docs to be published on website

Browse Source 
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
This commit is contained in:
Khosrow Moossavi
2021-02-23 14:19:14 -05:00
parent 0e2e485c15
commit 304bce9bb0
22 changed files with 598 additions and 394 deletions
Download Patch File Download Diff File Expand all files Collapse all files

465
docs/reference/asciidoc-document.md Normal file
View File

@@ -0,0 +1,465 @@
---
title: "asciidoc document"
description: "Generate AsciiDoc document of inputs and outputs."
menu:
docs:
parent: "asciidoc"
weight: 952
toc: true
---
## Synopsis
Generate AsciiDoc document of inputs and outputs.
```console
terraform-docs asciidoc document [PATH] [flags]
```
## Options
```console
-h, --help help for document
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--indent int indention level of AsciiDoc sections [1, 2, 3, 4, 5] (default 2)
--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 [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs asciidoc document ./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:
- terraform (>= 0.12)
- aws (>= 2.15.0)
- random (>= 2.2.0)
== Providers
The following providers are used by this module:
- aws (>= 2.15.0)
- aws.ident (>= 2.15.0)
- null
- tls
== Modules
The following Modules are called:
=== bar
Source: baz
Version: 4.5.6
=== baz
Source: baz
Version: 4.5.6
=== foo
Source: bar
Version: 1.2.3
== Resources
The following resources are used by this module:
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity[aws_caller_identity]
- https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource[null_resource]
- https://registry.terraform.io/providers/hashicorp/tls/latest/docs/resources/private_key[tls_private_key]
== Required Inputs
The following input variables are required:
=== input_with_underscores
Description: A variable with underscores.
Type: `any`
=== list-2
Description: It's list number two.
Type: `list`
=== map-2
Description: It's map number two.
Type: `map`
=== number-2
Description: It's number number two.
Type: `number`
=== string-2
Description: It's string number two.
Type: `string`
=== string_no_default
Description: n/a
Type: `string`
=== unquoted
Description: n/a
Type: `any`
== Optional Inputs
The following input variables are optional (have default values):
=== bool-1
Description: It's bool number one.
Type: `bool`
Default: `true`
=== bool-2
Description: It's bool number two.
Type: `bool`
Default: `false`
=== bool-3
Description: n/a
Type: `bool`
Default: `true`
=== bool_default_false
Description: n/a
Type: `bool`
Default: `false`
=== 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-with-pipe
Description: It includes v1 \| v2 \| v3
Type: `string`
Default: `"v1"`
=== list-1
Description: It's list number one.
Type: `list`
Default:
[source,json]
----
[
"a",
"b",
"c"
]
----
=== list-3
Description: n/a
Type: `list`
Default: `[]`
=== list_default_empty
Description: n/a
Type: `list(string)`
Default: `[]`
=== 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"
}
----
=== map-1
Description: It's map number one.
Type: `map`
Default:
[source,json]
----
{
"a": 1,
"b": 2,
"c": 3
}
----
=== map-3
Description: n/a
Type: `map`
Default: `{}`
=== no-escape-default-value
Description: The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'.
Type: `string`
Default: `"VALUE_WITH_UNDERSCORE"`
=== number-1
Description: It's number number one.
Type: `number`
Default: `42`
=== number-3
Description: n/a
Type: `number`
Default: `"19"`
=== number-4
Description: n/a
Type: `number`
Default: `15.75`
=== number_default_zero
Description: n/a
Type: `number`
Default: `0`
=== object_default_empty
Description: n/a
Type: `object({})`
Default: `{}`
=== string-1
Description: It's string number one.
Type: `string`
Default: `"bar"`
=== string-3
Description: n/a
Type: `string`
Default: `""`
=== string-special-chars
Description: n/a
Type: `string`
Default: `"\\.<>[]{}_-"`
=== string_default_empty
Description: n/a
Type: `string`
Default: `""`
=== string_default_null
Description: n/a
Type: `string`
Default: `null`
=== 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-0.12
Description: terraform 0.12 only
=== output-1
Description: It's output number one.
=== output-2
Description: It's output number two.
=== unquoted
Description: It's unquoted output.
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

409
docs/reference/asciidoc-table.md Normal file
View File

@@ -0,0 +1,409 @@
---
title: "asciidoc table"
description: "Generate AsciiDoc tables of inputs and outputs."
menu:
docs:
parent: "asciidoc"
weight: 953
toc: true
---
## Synopsis
Generate AsciiDoc tables of inputs and outputs.
```console
terraform-docs asciidoc table [PATH] [flags]
```
## Options
```console
-h, --help help for table
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--indent int indention level of AsciiDoc sections [1, 2, 3, 4, 5] (default 2)
--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 [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs asciidoc table ./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
[cols="a,a",options="header,autowidth"]
|===
|Name |Version
|terraform |>= 0.12
|aws |>= 2.15.0
|random |>= 2.2.0
|===
== Providers
[cols="a,a",options="header,autowidth"]
|===
|Name |Version
|aws |>= 2.15.0
|aws.ident |>= 2.15.0
|null |n/a
|tls |n/a
|===
== Modules
[cols="a,a,a",options="header,autowidth"]
|===
|Name|Source|Version|
|bar|baz|4.5.6
|baz|baz|4.5.6
|foo|bar|1.2.3
|===
== Resources
[cols="a",options="header,autowidth"]
|===
|Name
|https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity[aws_caller_identity]
|https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource[null_resource]
|https://registry.terraform.io/providers/hashicorp/tls/latest/docs/resources/private_key[tls_private_key]
|===
== Inputs
[cols="a,a,a,a,a",options="header,autowidth"]
|===
|Name |Description |Type |Default |Required
|bool-1
|It's bool number one.
|`bool`
|`true`
|no
|bool-2
|It's bool number two.
|`bool`
|`false`
|no
|bool-3
|n/a
|`bool`
|`true`
|no
|bool_default_false
|n/a
|`bool`
|`false`
|no
|input-with-code-block
|This is a complicated one. We need a newline.
And an example in a code block
[source]
----
default = [
"machine rack01:neptune"
]
----
|`list`
|
[source]
----
[
"name rack:location"
]
----
|no
|input-with-pipe
|It includes v1 \| v2 \| v3
|`string`
|`"v1"`
|no
|input_with_underscores
|A variable with underscores.
|`any`
|n/a
|yes
|list-1
|It's list number one.
|`list`
|
[source]
----
[
"a",
"b",
"c"
]
----
|no
|list-2
|It's list number two.
|`list`
|n/a
|yes
|list-3
|n/a
|`list`
|`[]`
|no
|list_default_empty
|n/a
|`list(string)`
|`[]`
|no
|long_type
|This description is itself markdown.
It spans over multiple lines.
|
[source]
----
object({
name = string,
foo = object({ foo = string, bar = string }),
bar = object({ foo = string, bar = string }),
fizz = list(string),
buzz = list(string)
})
----
|
[source]
----
{
"bar": {
"bar": "bar",
"foo": "bar"
},
"buzz": [
"fizz",
"buzz"
],
"fizz": [],
"foo": {
"bar": "foo",
"foo": "foo"
},
"name": "hello"
}
----
|no
|map-1
|It's map number one.
|`map`
|
[source]
----
{
"a": 1,
"b": 2,
"c": 3
}
----
|no
|map-2
|It's map number two.
|`map`
|n/a
|yes
|map-3
|n/a
|`map`
|`{}`
|no
|no-escape-default-value
|The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'.
|`string`
|`"VALUE_WITH_UNDERSCORE"`
|no
|number-1
|It's number number one.
|`number`
|`42`
|no
|number-2
|It's number number two.
|`number`
|n/a
|yes
|number-3
|n/a
|`number`
|`"19"`
|no
|number-4
|n/a
|`number`
|`15.75`
|no
|number_default_zero
|n/a
|`number`
|`0`
|no
|object_default_empty
|n/a
|`object({})`
|`{}`
|no
|string-1
|It's string number one.
|`string`
|`"bar"`
|no
|string-2
|It's string number two.
|`string`
|n/a
|yes
|string-3
|n/a
|`string`
|`""`
|no
|string-special-chars
|n/a
|`string`
|`"\\.<>[]{}_-"`
|no
|string_default_empty
|n/a
|`string`
|`""`
|no
|string_default_null
|n/a
|`string`
|`null`
|no
|string_no_default
|n/a
|`string`
|n/a
|yes
|unquoted
|n/a
|`any`
|n/a
|yes
|with-url
|The description contains url. https://www.domain.com/foo/bar_baz.html
|`string`
|`""`
|no
|===
== Outputs
[cols="a,a",options="header,autowidth"]
|===
|Name |Description
|output-0.12 |terraform 0.12 only
|output-1 |It's output number one.
|output-2 |It's output number two.
|unquoted |It's unquoted output.
|===
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

47
docs/reference/asciidoc.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: "asciidoc"
description: "Generate AsciiDoc of inputs and outputs."
menu:
docs:
parent: "terraform-docs"
weight: 951
toc: true
---
## Synopsis
Generate AsciiDoc of inputs and outputs.
```console
terraform-docs asciidoc [PATH] [flags]
```
## Options
```console
-h, --help help for asciidoc
--indent int indention level of AsciiDoc sections [1, 2, 3, 4, 5] (default 2)
--required show Required column or section (default true)
--sensitive show Sensitive column or section (default true)
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Subcommands
- [terraform-docs asciidoc document]({{< ref "asciidoc-document" >}})
- [terraform-docs asciidoc table]({{< ref "asciidoc-table" >}})

93
docs/reference/config-file.md Normal file
View File

@@ -0,0 +1,93 @@
---
title: "Config File"
description: "terraform-docs configuration file, i.e. .terraform-docs.yml"
menu:
docs:
parent: "reference"
weight: 900
toc: true
---
The `terraform-docs` configuration is a yaml file. Its default name is `.terraform-docs.yml`.
## Options
Below is a complete list of options that you can use with `terraform-docs`, with their
corresponding default values (if applicable).
```yaml
formatter: <FORMATTER_NAME>
header-from: main.tf
sections:
hide-all: false
hide: []
show-all: true
show: []
output-values:
enabled: false
from: ""
sort:
enabled: true
by:
- required
- type
settings:
color: true
escape: true
indent: 2
required: true
sensitive: true
```
**Note:** The following options cannot be used together:
- `sections.hide` and `sections.show`
- `sections.hide-all` and `sections.show-all`
- `sections.hide-all` and `sections.hide`
- `sections.show-all` and `sections.show`
- `sort.by.required` and `sort.by.type`
## Formatters
The following options are supported out of the box by terraform-docs and can be
used for `FORMATTER_NAME`:
- `asciidoc` - [reference]({{< ref "asciidoc" >}})
- `asciidoc document` - [reference]({{< ref "asciidoc-document" >}})
- `asciidoc table` - [reference]({{< ref "asciidoc-table" >}})
- `json` - [reference]({{< ref "json" >}})
- `markdown` - [reference]({{< ref "markdown" >}})
- `markdown document` - [reference]({{< ref "markdown-document" >}})
- `markdown table` - [reference]({{< ref "markdown-table" >}})
- `pretty` - [reference]({{< ref "pretty" >}})
- `tfvars hcl` - [reference]({{< ref "tfvars-hcl" >}})
- `tfvars json` - [reference]({{< ref "tfvars-json" >}})
- `toml` - [reference]({{< ref "toml" >}})
- `xml` - [reference]({{< ref "xml" >}})
- `yaml` - [reference]({{< ref "yaml" >}})
**Note:** You need to pass name of a plugin as `formatter` in order to be able to
use the plugin. For example, if plugin binary file is called `tfdocs-format-foo`,
formatter name must be set to `foo`.
## header-from
Relative path to a file to extract header for the generated output from. Supported
file formats are `.adoc`, `.md`, `.tf`, and `.txt`. Default value is `main.tf`.
## Sections
The following options are supported and can be used for `sections.show` and
`sections.hide`:
- `header`
- `inputs`
- `modules`
- `outputs`
- `providers`
- `requirements`
- `resources`

394
docs/reference/json.md Normal file
View File

@@ -0,0 +1,394 @@
---
title: "json"
description: "Generate JSON of inputs and outputs."
menu:
docs:
parent: "terraform-docs"
weight: 954
toc: true
---
## Synopsis
Generate JSON of inputs and outputs.
```console
terraform-docs json [PATH] [flags]
```
## Options
```console
--escape escape special characters (default true)
-h, --help help for json
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs json ./examples/
```
generates the following output:
{
"header": "Usage:\n\nExample of 'foo_bar' module in `foo_bar.tf`.\n\n- list item 1\n- list item 2\n\nEven inline **formatting** in _here_ is possible.\nand some [link](https://domain.com/)\n\n* list item 3\n* list item 4\n\n```hcl\nmodule \"foo_bar\" {\n source = \"github.com/foo/bar\"\n\n id = \"1234567890\"\n name = \"baz\"\n\n zones = [\"us-east-1\", \"us-west-1\"]\n\n tags = {\n Name = \"baz\"\n Created-By = \"first.last@email.com\"\n Date-Created = \"20180101\"\n }\n}\n```\n\nHere is some trailing text after code block,\nfollowed by another line of text.\n\n| Name | Description |\n|------|-----------------|\n| Foo | Foo description |\n| Bar | Bar description |",
"inputs": [
{
"name": "bool-1",
"type": "bool",
"description": "It's bool number one.",
"default": true,
"required": false
},
{
"name": "bool-2",
"type": "bool",
"description": "It's bool number two.",
"default": false,
"required": false
},
{
"name": "bool-3",
"type": "bool",
"description": null,
"default": true,
"required": false
},
{
"name": "bool_default_false",
"type": "bool",
"description": null,
"default": false,
"required": false
},
{
"name": "input-with-code-block",
"type": "list",
"description": "This is a complicated one. We need a newline. \nAnd an example in a code block\n```\ndefault = [\n \"machine rack01:neptune\"\n]\n```\n",
"default": [
"name rack:location"
],
"required": false
},
{
"name": "input-with-pipe",
"type": "string",
"description": "It includes v1 | v2 | v3",
"default": "v1",
"required": false
},
{
"name": "input_with_underscores",
"type": "any",
"description": "A variable with underscores.",
"default": null,
"required": true
},
{
"name": "list-1",
"type": "list",
"description": "It's list number one.",
"default": [
"a",
"b",
"c"
],
"required": false
},
{
"name": "list-2",
"type": "list",
"description": "It's list number two.",
"default": null,
"required": true
},
{
"name": "list-3",
"type": "list",
"description": null,
"default": [],
"required": false
},
{
"name": "list_default_empty",
"type": "list(string)",
"description": null,
"default": [],
"required": false
},
{
"name": "long_type",
"type": "object({\n name = string,\n foo = object({ foo = string, bar = string }),\n bar = object({ foo = string, bar = string }),\n fizz = list(string),\n buzz = list(string)\n })",
"description": "This description is itself markdown.\n\nIt spans over multiple lines.\n",
"default": {
"bar": {
"bar": "bar",
"foo": "bar"
},
"buzz": [
"fizz",
"buzz"
],
"fizz": [],
"foo": {
"bar": "foo",
"foo": "foo"
},
"name": "hello"
},
"required": false
},
{
"name": "map-1",
"type": "map",
"description": "It's map number one.",
"default": {
"a": 1,
"b": 2,
"c": 3
},
"required": false
},
{
"name": "map-2",
"type": "map",
"description": "It's map number two.",
"default": null,
"required": true
},
{
"name": "map-3",
"type": "map",
"description": null,
"default": {},
"required": false
},
{
"name": "no-escape-default-value",
"type": "string",
"description": "The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'.",
"default": "VALUE_WITH_UNDERSCORE",
"required": false
},
{
"name": "number-1",
"type": "number",
"description": "It's number number one.",
"default": 42,
"required": false
},
{
"name": "number-2",
"type": "number",
"description": "It's number number two.",
"default": null,
"required": true
},
{
"name": "number-3",
"type": "number",
"description": null,
"default": "19",
"required": false
},
{
"name": "number-4",
"type": "number",
"description": null,
"default": 15.75,
"required": false
},
{
"name": "number_default_zero",
"type": "number",
"description": null,
"default": 0,
"required": false
},
{
"name": "object_default_empty",
"type": "object({})",
"description": null,
"default": {},
"required": false
},
{
"name": "string-1",
"type": "string",
"description": "It's string number one.",
"default": "bar",
"required": false
},
{
"name": "string-2",
"type": "string",
"description": "It's string number two.",
"default": null,
"required": true
},
{
"name": "string-3",
"type": "string",
"description": null,
"default": "",
"required": false
},
{
"name": "string-special-chars",
"type": "string",
"description": null,
"default": "\\.\u003c\u003e[]{}_-",
"required": false
},
{
"name": "string_default_empty",
"type": "string",
"description": null,
"default": "",
"required": false
},
{
"name": "string_default_null",
"type": "string",
"description": null,
"default": null,
"required": false
},
{
"name": "string_no_default",
"type": "string",
"description": null,
"default": null,
"required": true
},
{
"name": "unquoted",
"type": "any",
"description": null,
"default": null,
"required": true
},
{
"name": "with-url",
"type": "string",
"description": "The description contains url. https://www.domain.com/foo/bar_baz.html",
"default": "",
"required": false
}
],
"modules": [
{
"name": "bar",
"source": "baz",
"version": "4.5.6"
},
{
"name": "baz",
"source": "baz",
"version": "4.5.6"
},
{
"name": "foo",
"source": "bar",
"version": "1.2.3"
}
],
"outputs": [
{
"name": "output-0.12",
"description": "terraform 0.12 only"
},
{
"name": "output-1",
"description": "It's output number one."
},
{
"name": "output-2",
"description": "It's output number two."
},
{
"name": "unquoted",
"description": "It's unquoted output."
}
],
"providers": [
{
"name": "aws",
"alias": null,
"version": "\u003e= 2.15.0"
},
{
"name": "aws",
"alias": "ident",
"version": "\u003e= 2.15.0"
},
{
"name": "null",
"alias": null,
"version": null
},
{
"name": "tls",
"alias": null,
"version": null
}
],
"requirements": [
{
"name": "terraform",
"version": "\u003e= 0.12"
},
{
"name": "aws",
"version": "\u003e= 2.15.0"
},
{
"name": "random",
"version": "\u003e= 2.2.0"
}
],
"resources": [
{
"type": "caller_identity",
"providerName": "aws",
"provicerSource": "hashicorp/aws",
"mode": "data",
"version": "latest"
},
{
"type": "resource",
"providerName": "null",
"provicerSource": "hashicorp/null",
"mode": "managed",
"version": "latest"
},
{
"type": "private_key",
"providerName": "tls",
"provicerSource": "hashicorp/tls",
"mode": "managed",
"version": "latest"
}
]
}
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

466
docs/reference/markdown-document.md Normal file
View File

@@ -0,0 +1,466 @@
---
title: "markdown document"
description: "Generate Markdown document of inputs and outputs."
menu:
docs:
parent: "markdown"
weight: 956
toc: true
---
## Synopsis
Generate Markdown document of inputs and outputs.
```console
terraform-docs markdown document [PATH] [flags]
```
## Options
```console
-h, --help help for document
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--escape escape special characters (default true)
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--indent int indention level of Markdown sections [1, 2, 3, 4, 5] (default 2)
--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 [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs markdown document ./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:
- terraform (>= 0.12)
- aws (>= 2.15.0)
- random (>= 2.2.0)
## Providers
The following providers are used by this module:
- aws (>= 2.15.0)
- aws.ident (>= 2.15.0)
- null
- tls
## Modules
The following Modules are called:
### bar
Source: baz
Version: 4.5.6
### baz
Source: baz
Version: 4.5.6
### foo
Source: bar
Version: 1.2.3
## Resources
The following resources are used by this module:
- [aws_caller_identity](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity)
- [null_resource](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource)
- [tls_private_key](https://registry.terraform.io/providers/hashicorp/tls/latest/docs/resources/private_key)
## Required Inputs
The following input variables are required:
### input\_with\_underscores
Description: A variable with underscores.
Type: `any`
### list-2
Description: It's list number two.
Type: `list`
### map-2
Description: It's map number two.
Type: `map`
### number-2
Description: It's number number two.
Type: `number`
### string-2
Description: It's string number two.
Type: `string`
### string\_no\_default
Description: n/a
Type: `string`
### unquoted
Description: n/a
Type: `any`
## Optional Inputs
The following input variables are optional (have default values):
### bool-1
Description: It's bool number one.
Type: `bool`
Default: `true`
### bool-2
Description: It's bool number two.
Type: `bool`
Default: `false`
### bool-3
Description: n/a
Type: `bool`
Default: `true`
### bool\_default\_false
Description: n/a
Type: `bool`
Default: `false`
### 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:
```json
[
"name rack:location"
]
```
### input-with-pipe
Description: It includes v1 \| v2 \| v3
Type: `string`
Default: `"v1"`
### list-1
Description: It's list number one.
Type: `list`
Default:
```json
[
"a",
"b",
"c"
]
```
### list-3
Description: n/a
Type: `list`
Default: `[]`
### list\_default\_empty
Description: n/a
Type: `list(string)`
Default: `[]`
### long\_type
Description: This description is itself markdown.
It spans over multiple lines.
Type:
```hcl
object({
name = string,
foo = object({ foo = string, bar = string }),
bar = object({ foo = string, bar = string }),
fizz = list(string),
buzz = list(string)
})
```
Default:
```json
{
"bar": {
"bar": "bar",
"foo": "bar"
},
"buzz": [
"fizz",
"buzz"
],
"fizz": [],
"foo": {
"bar": "foo",
"foo": "foo"
},
"name": "hello"
}
```
### map-1
Description: It's map number one.
Type: `map`
Default:
```json
{
"a": 1,
"b": 2,
"c": 3
}
```
### map-3
Description: n/a
Type: `map`
Default: `{}`
### no-escape-default-value
Description: The description contains `something_with_underscore`. Defaults to 'VALUE\_WITH\_UNDERSCORE'.
Type: `string`
Default: `"VALUE_WITH_UNDERSCORE"`
### number-1
Description: It's number number one.
Type: `number`
Default: `42`
### number-3
Description: n/a
Type: `number`
Default: `"19"`
### number-4
Description: n/a
Type: `number`
Default: `15.75`
### number\_default\_zero
Description: n/a
Type: `number`
Default: `0`
### object\_default\_empty
Description: n/a
Type: `object({})`
Default: `{}`
### string-1
Description: It's string number one.
Type: `string`
Default: `"bar"`
### string-3
Description: n/a
Type: `string`
Default: `""`
### string-special-chars
Description: n/a
Type: `string`
Default: `"\\.<>[]{}_-"`
### string\_default\_empty
Description: n/a
Type: `string`
Default: `""`
### string\_default\_null
Description: n/a
Type: `string`
Default: `null`
### 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-0.12
Description: terraform 0.12 only
### output-1
Description: It's output number one.
### output-2
Description: It's output number two.
### unquoted
Description: It's unquoted output.
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

171
docs/reference/markdown-table.md Normal file
View File

@@ -0,0 +1,171 @@
---
title: "markdown table"
description: "Generate Markdown tables of inputs and outputs."
menu:
docs:
parent: "markdown"
weight: 957
toc: true
---
## Synopsis
Generate Markdown tables of inputs and outputs.
```console
terraform-docs markdown table [PATH] [flags]
```
## Options
```console
-h, --help help for table
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--escape escape special characters (default true)
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--indent int indention level of Markdown sections [1, 2, 3, 4, 5] (default 2)
--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 [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs markdown table ./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
| Name | Version |
|------|---------|
| terraform | >= 0.12 |
| aws | >= 2.15.0 |
| random | >= 2.2.0 |
## Providers
| Name | Version |
|------|---------|
| aws | >= 2.15.0 |
| aws.ident | >= 2.15.0 |
| null | n/a |
| tls | n/a |
## Modules
| Name | Source | Version |
|------|--------|---------|
| bar | baz | 4.5.6 |
| baz | baz | 4.5.6 |
| foo | bar | 1.2.3 |
## Resources
| Name |
|------|
| [aws_caller_identity](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) |
| [null_resource](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) |
| [tls_private_key](https://registry.terraform.io/providers/hashicorp/tls/latest/docs/resources/private_key) |
## Inputs
| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| bool-1 | It's bool number one. | `bool` | `true` | no |
| bool-2 | It's bool number two. | `bool` | `false` | no |
| bool-3 | n/a | `bool` | `true` | no |
| bool\_default\_false | n/a | `bool` | `false` | no |
| input-with-code-block | This is a complicated one. We need a newline.<br>And an example in a code block<pre>default = [<br> "machine rack01:neptune"<br>]</pre> | `list` | <pre>[<br> "name rack:location"<br>]</pre> | no |
| input-with-pipe | It includes v1 \| v2 \| v3 | `string` | `"v1"` | no |
| input\_with\_underscores | A variable with underscores. | `any` | n/a | yes |
| list-1 | It's list number one. | `list` | <pre>[<br> "a",<br> "b",<br> "c"<br>]</pre> | no |
| list-2 | It's list number two. | `list` | n/a | yes |
| list-3 | n/a | `list` | `[]` | no |
| list\_default\_empty | n/a | `list(string)` | `[]` | no |
| long\_type | This description is itself markdown.<br><br>It spans over multiple lines. | <pre>object({<br> name = string,<br> foo = object({ foo = string, bar = string }),<br> bar = object({ foo = string, bar = string }),<br> fizz = list(string),<br> buzz = list(string)<br> })</pre> | <pre>{<br> "bar": {<br> "bar": "bar",<br> "foo": "bar"<br> },<br> "buzz": [<br> "fizz",<br> "buzz"<br> ],<br> "fizz": [],<br> "foo": {<br> "bar": "foo",<br> "foo": "foo"<br> },<br> "name": "hello"<br>}</pre> | no |
| map-1 | It's map number one. | `map` | <pre>{<br> "a": 1,<br> "b": 2,<br> "c": 3<br>}</pre> | no |
| map-2 | It's map number two. | `map` | n/a | yes |
| map-3 | n/a | `map` | `{}` | no |
| no-escape-default-value | The description contains `something_with_underscore`. Defaults to 'VALUE\_WITH\_UNDERSCORE'. | `string` | `"VALUE_WITH_UNDERSCORE"` | no |
| number-1 | It's number number one. | `number` | `42` | no |
| number-2 | It's number number two. | `number` | n/a | yes |
| number-3 | n/a | `number` | `"19"` | no |
| number-4 | n/a | `number` | `15.75` | no |
| number\_default\_zero | n/a | `number` | `0` | no |
| object\_default\_empty | n/a | `object({})` | `{}` | no |
| string-1 | It's string number one. | `string` | `"bar"` | no |
| string-2 | It's string number two. | `string` | n/a | yes |
| string-3 | n/a | `string` | `""` | no |
| string-special-chars | n/a | `string` | `"\\.<>[]{}_-"` | no |
| string\_default\_empty | n/a | `string` | `""` | no |
| string\_default\_null | n/a | `string` | `null` | no |
| string\_no\_default | n/a | `string` | n/a | yes |
| unquoted | n/a | `any` | n/a | yes |
| with-url | The description contains url. https://www.domain.com/foo/bar_baz.html | `string` | `""` | no |
## Outputs
| Name | Description |
|------|-------------|
| output-0.12 | terraform 0.12 only |
| output-1 | It's output number one. |
| output-2 | It's output number two. |
| unquoted | It's unquoted output. |
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

48
docs/reference/markdown.md Normal file
View File

@@ -0,0 +1,48 @@
---
title: "markdown"
description: "Generate Markdown of inputs and outputs."
menu:
docs:
parent: "terraform-docs"
weight: 955
toc: true
---
## Synopsis
Generate Markdown of inputs and outputs.
```console
terraform-docs markdown [PATH] [flags]
```
## Options
```console
--escape escape special characters (default true)
-h, --help help for markdown
--indent int indention level of Markdown sections [1, 2, 3, 4, 5] (default 2)
--required show Required column or section (default true)
--sensitive show Sensitive column or section (default true)
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Subcommands
- [terraform-docs markdown document]({{< ref "markdown-document" >}})
- [terraform-docs markdown table]({{< ref "markdown-table" >}})

251
docs/reference/pretty.md Normal file
View File

@@ -0,0 +1,251 @@
---
title: "pretty"
description: "Generate colorized pretty of inputs and outputs."
menu:
docs:
parent: "terraform-docs"
weight: 958
toc: true
---
## Synopsis
Generate colorized pretty of inputs and outputs.
```console
terraform-docs pretty [PATH] [flags]
```
## Options
```console
--color colorize printed result (default true)
-h, --help help for pretty
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs pretty --no-color ./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 |
requirement.terraform (>= 0.12)
requirement.aws (>= 2.15.0)
requirement.random (>= 2.2.0)
provider.aws (>= 2.15.0)
provider.aws.ident (>= 2.15.0)
provider.null
provider.tls
modulecall.bar (baz,4.5.6)
modulecall.baz (baz,4.5.6)
modulecall.foo (bar,1.2.3)
resource.aws_caller_identity (https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity)
resource.null_resource (https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource)
resource.tls_private_key (https://registry.terraform.io/providers/hashicorp/tls/latest/docs/resources/private_key)
input.bool-1 (true)
It's bool number one.
input.bool-2 (false)
It's bool number two.
input.bool-3 (true)
n/a
input.bool_default_false (false)
n/a
input.input-with-code-block ([
"name rack:location"
])
This is a complicated one. We need a newline.
And an example in a code block
```
default = [
"machine rack01:neptune"
]
```
input.input-with-pipe ("v1")
It includes v1 | v2 | v3
input.input_with_underscores (required)
A variable with underscores.
input.list-1 ([
"a",
"b",
"c"
])
It's list number one.
input.list-2 (required)
It's list number two.
input.list-3 ([])
n/a
input.list_default_empty ([])
n/a
input.long_type ({
"bar": {
"bar": "bar",
"foo": "bar"
},
"buzz": [
"fizz",
"buzz"
],
"fizz": [],
"foo": {
"bar": "foo",
"foo": "foo"
},
"name": "hello"
})
This description is itself markdown.
It spans over multiple lines.
input.map-1 ({
"a": 1,
"b": 2,
"c": 3
})
It's map number one.
input.map-2 (required)
It's map number two.
input.map-3 ({})
n/a
input.no-escape-default-value ("VALUE_WITH_UNDERSCORE")
The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'.
input.number-1 (42)
It's number number one.
input.number-2 (required)
It's number number two.
input.number-3 ("19")
n/a
input.number-4 (15.75)
n/a
input.number_default_zero (0)
n/a
input.object_default_empty ({})
n/a
input.string-1 ("bar")
It's string number one.
input.string-2 (required)
It's string number two.
input.string-3 ("")
n/a
input.string-special-chars ("\\.<>[]{}_-")
n/a
input.string_default_empty ("")
n/a
input.string_default_null (null)
n/a
input.string_no_default (required)
n/a
input.unquoted (required)
n/a
input.with-url ("")
The description contains url. https://www.domain.com/foo/bar_baz.html
output.output-0.12
terraform 0.12 only
output.output-1
It's output number one.
output.output-2
It's output number two.
output.unquoted
It's unquoted output.
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

51
docs/reference/terraform-docs.md Normal file
View File

@@ -0,0 +1,51 @@
---
title: "terraform-docs"
description: "A utility to generate documentation from Terraform modules in various output formats."
menu:
docs:
parent: "reference"
weight: 950
toc: true
---
## Synopsis
A utility to generate documentation from Terraform modules in various output formats.
```console
terraform-docs [PATH] [flags]
```
## Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
-h, --help help for terraform-docs
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Subcommands
- [terraform-docs asciidoc]({{< ref "asciidoc" >}})
- [terraform-docs asciidoc document]({{< ref "asciidoc-document" >}})
- [terraform-docs asciidoc table]({{< ref "asciidoc-table" >}})
- [terraform-docs json]({{< ref "json" >}})
- [terraform-docs markdown]({{< ref "markdown" >}})
- [terraform-docs markdown document]({{< ref "markdown-document" >}})
- [terraform-docs markdown table]({{< ref "markdown-table" >}})
- [terraform-docs pretty]({{< ref "pretty" >}})
- [terraform-docs tfvars]({{< ref "tfvars" >}})
- [terraform-docs tfvars hcl]({{< ref "tfvars-hcl" >}})
- [terraform-docs tfvars json]({{< ref "tfvars-json" >}})
- [terraform-docs toml]({{< ref "toml" >}})
- [terraform-docs xml]({{< ref "xml" >}})
- [terraform-docs yaml]({{< ref "yaml" >}})

108
docs/reference/tfvars-hcl.md Normal file
View File

@@ -0,0 +1,108 @@
---
title: "tfvars hcl"
description: "Generate HCL format of terraform.tfvars of inputs."
menu:
docs:
parent: "tfvars"
weight: 960
toc: true
---
## Synopsis
Generate HCL format of terraform.tfvars of inputs.
```console
terraform-docs tfvars hcl [PATH] [flags]
```
## Options
```console
-h, --help help for hcl
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs tfvars hcl ./examples/
```
generates the following output:
bool-1 = true
bool-2 = false
bool-3 = true
bool_default_false = false
input-with-code-block = [
"name rack:location"
]
input-with-pipe = "v1"
input_with_underscores = ""
list-1 = [
"a",
"b",
"c"
]
list-2 = ""
list-3 = []
list_default_empty = []
long_type = {
"bar": {
"bar": "bar",
"foo": "bar"
},
"buzz": [
"fizz",
"buzz"
],
"fizz": [],
"foo": {
"bar": "foo",
"foo": "foo"
},
"name": "hello"
}
map-1 = {
"a": 1,
"b": 2,
"c": 3
}
map-2 = ""
map-3 = {}
no-escape-default-value = "VALUE_WITH_UNDERSCORE"
number-1 = 42
number-2 = ""
number-3 = "19"
number-4 = 15.75
number_default_zero = 0
object_default_empty = {}
string-1 = "bar"
string-2 = ""
string-3 = ""
string-special-chars = "\\.<>[]{}_-"
string_default_empty = ""
string_default_null = ""
string_no_default = ""
unquoted = ""
with-url = ""
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

110
docs/reference/tfvars-json.md Normal file
View File

@@ -0,0 +1,110 @@
---
title: "tfvars json"
description: "Generate JSON format of terraform.tfvars of inputs."
menu:
docs:
parent: "tfvars"
weight: 961
toc: true
---
## Synopsis
Generate JSON format of terraform.tfvars of inputs.
```console
terraform-docs tfvars json [PATH] [flags]
```
## Options
```console
-h, --help help for json
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs tfvars json ./examples/
```
generates the following output:
{
"bool-1": true,
"bool-2": false,
"bool-3": true,
"bool_default_false": false,
"input-with-code-block": [
"name rack:location"
],
"input-with-pipe": "v1",
"input_with_underscores": null,
"list-1": [
"a",
"b",
"c"
],
"list-2": null,
"list-3": [],
"list_default_empty": [],
"long_type": {
"bar": {
"bar": "bar",
"foo": "bar"
},
"buzz": [
"fizz",
"buzz"
],
"fizz": [],
"foo": {
"bar": "foo",
"foo": "foo"
},
"name": "hello"
},
"map-1": {
"a": 1,
"b": 2,
"c": 3
},
"map-2": null,
"map-3": {},
"no-escape-default-value": "VALUE_WITH_UNDERSCORE",
"number-1": 42,
"number-2": null,
"number-3": "19",
"number-4": 15.75,
"number_default_zero": 0,
"object_default_empty": {},
"string-1": "bar",
"string-2": null,
"string-3": "",
"string-special-chars": "\\.<>[]{}_-",
"string_default_empty": "",
"string_default_null": null,
"string_no_default": null,
"unquoted": null,
"with-url": ""
}
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

40
docs/reference/tfvars.md Normal file
View File

@@ -0,0 +1,40 @@
---
title: "tfvars"
description: "Generate terraform.tfvars of inputs."
menu:
docs:
parent: "terraform-docs"
weight: 959
toc: true
---
## Synopsis
Generate terraform.tfvars of inputs.
## Options
```console
-h, --help help for tfvars
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Subcommands
- [terraform-docs tfvars hcl]({{< ref "tfvars-hcl" >}})
- [terraform-docs tfvars json]({{< ref "tfvars-json" >}})

366
docs/reference/toml.md Normal file
View File

@@ -0,0 +1,366 @@
---
title: "toml"
description: "Generate TOML of inputs and outputs."
menu:
docs:
parent: "terraform-docs"
weight: 962
toc: true
---
## Synopsis
Generate TOML of inputs and outputs.
```console
terraform-docs toml [PATH] [flags]
```
## Options
```console
-h, --help help for toml
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs toml ./examples/
```
generates the following output:
header = "Usage:\n\nExample of 'foo_bar' module in `foo_bar.tf`.\n\n- list item 1\n- list item 2\n\nEven inline **formatting** in _here_ is possible.\nand some [link](https://domain.com/)\n\n* list item 3\n* list item 4\n\n```hcl\nmodule \"foo_bar\" {\n source = \"github.com/foo/bar\"\n\n id = \"1234567890\"\n name = \"baz\"\n\n zones = [\"us-east-1\", \"us-west-1\"]\n\n tags = {\n Name = \"baz\"\n Created-By = \"first.last@email.com\"\n Date-Created = \"20180101\"\n }\n}\n```\n\nHere is some trailing text after code block,\nfollowed by another line of text.\n\n| Name | Description |\n|------|-----------------|\n| Foo | Foo description |\n| Bar | Bar description |"
[[inputs]]
name = "bool-1"
type = "bool"
description = "It's bool number one."
default = true
required = false
[[inputs]]
name = "bool-2"
type = "bool"
description = "It's bool number two."
default = false
required = false
[[inputs]]
name = "bool-3"
type = "bool"
description = ""
default = true
required = false
[[inputs]]
name = "bool_default_false"
type = "bool"
description = ""
default = false
required = false
[[inputs]]
name = "input-with-code-block"
type = "list"
description = "This is a complicated one. We need a newline. \nAnd an example in a code block\n```\ndefault = [\n \"machine rack01:neptune\"\n]\n```\n"
default = ["name rack:location"]
required = false
[[inputs]]
name = "input-with-pipe"
type = "string"
description = "It includes v1 | v2 | v3"
default = "v1"
required = false
[[inputs]]
name = "input_with_underscores"
type = "any"
description = "A variable with underscores."
required = true
[inputs.default]
[[inputs]]
name = "list-1"
type = "list"
description = "It's list number one."
default = ["a", "b", "c"]
required = false
[[inputs]]
name = "list-2"
type = "list"
description = "It's list number two."
required = true
[inputs.default]
[[inputs]]
name = "list-3"
type = "list"
description = ""
default = []
required = false
[[inputs]]
name = "list_default_empty"
type = "list(string)"
description = ""
default = []
required = false
[[inputs]]
name = "long_type"
type = "object({\n name = string,\n foo = object({ foo = string, bar = string }),\n bar = object({ foo = string, bar = string }),\n fizz = list(string),\n buzz = list(string)\n })"
description = "This description is itself markdown.\n\nIt spans over multiple lines.\n"
required = false
[inputs.default]
buzz = ["fizz", "buzz"]
fizz = []
name = "hello"
[inputs.default.bar]
bar = "bar"
foo = "bar"
[inputs.default.foo]
bar = "foo"
foo = "foo"
[[inputs]]
name = "map-1"
type = "map"
description = "It's map number one."
required = false
[inputs.default]
a = 1.0
b = 2.0
c = 3.0
[[inputs]]
name = "map-2"
type = "map"
description = "It's map number two."
required = true
[inputs.default]
[[inputs]]
name = "map-3"
type = "map"
description = ""
required = false
[inputs.default]
[[inputs]]
name = "no-escape-default-value"
type = "string"
description = "The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'."
default = "VALUE_WITH_UNDERSCORE"
required = false
[[inputs]]
name = "number-1"
type = "number"
description = "It's number number one."
default = 42.0
required = false
[[inputs]]
name = "number-2"
type = "number"
description = "It's number number two."
required = true
[inputs.default]
[[inputs]]
name = "number-3"
type = "number"
description = ""
default = "19"
required = false
[[inputs]]
name = "number-4"
type = "number"
description = ""
default = 15.75
required = false
[[inputs]]
name = "number_default_zero"
type = "number"
description = ""
default = 0.0
required = false
[[inputs]]
name = "object_default_empty"
type = "object({})"
description = ""
required = false
[inputs.default]
[[inputs]]
name = "string-1"
type = "string"
description = "It's string number one."
default = "bar"
required = false
[[inputs]]
name = "string-2"
type = "string"
description = "It's string number two."
required = true
[inputs.default]
[[inputs]]
name = "string-3"
type = "string"
description = ""
default = ""
required = false
[[inputs]]
name = "string-special-chars"
type = "string"
description = ""
default = "\\.<>[]{}_-"
required = false
[[inputs]]
name = "string_default_empty"
type = "string"
description = ""
default = ""
required = false
[[inputs]]
name = "string_default_null"
type = "string"
description = ""
required = false
[inputs.default]
[[inputs]]
name = "string_no_default"
type = "string"
description = ""
required = true
[inputs.default]
[[inputs]]
name = "unquoted"
type = "any"
description = ""
required = true
[inputs.default]
[[inputs]]
name = "with-url"
type = "string"
description = "The description contains url. https://www.domain.com/foo/bar_baz.html"
default = ""
required = false
[[modules]]
Name = "bar"
Source = "baz"
Version = "4.5.6"
[[modules]]
Name = "baz"
Source = "baz"
Version = "4.5.6"
[[modules]]
Name = "foo"
Source = "bar"
Version = "1.2.3"
[[outputs]]
name = "output-0.12"
description = "terraform 0.12 only"
[[outputs]]
name = "output-1"
description = "It's output number one."
[[outputs]]
name = "output-2"
description = "It's output number two."
[[outputs]]
name = "unquoted"
description = "It's unquoted output."
[[providers]]
name = "aws"
alias = ""
version = ">= 2.15.0"
[[providers]]
name = "aws"
alias = "ident"
version = ">= 2.15.0"
[[providers]]
name = "null"
alias = ""
version = ""
[[providers]]
name = "tls"
alias = ""
version = ""
[[requirements]]
Name = "terraform"
Version = ">= 0.12"
[[requirements]]
Name = "aws"
Version = ">= 2.15.0"
[[requirements]]
Name = "random"
Version = ">= 2.2.0"
[[resources]]
type = "caller_identity"
providerName = "aws"
providerSource = "hashicorp/aws"
mode = "data"
version = "latest"
[[resources]]
type = "resource"
providerName = "null"
providerSource = "hashicorp/null"
mode = "managed"
version = "latest"
[[resources]]
type = "private_key"
providerName = "tls"
providerSource = "hashicorp/tls"
mode = "managed"
version = "latest"
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

393
docs/reference/xml.md Normal file
View File

@@ -0,0 +1,393 @@
---
title: "xml"
description: "Generate XML of inputs and outputs."
menu:
docs:
parent: "terraform-docs"
weight: 963
toc: true
---
## Synopsis
Generate XML of inputs and outputs.
```console
terraform-docs xml [PATH] [flags]
```
## Options
```console
-h, --help help for xml
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs xml ./examples/
```
generates the following output:
<module>
<header>Usage:&#xA;&#xA;Example of &#39;foo_bar&#39; module in `foo_bar.tf`.&#xA;&#xA;- list item 1&#xA;- list item 2&#xA;&#xA;Even inline **formatting** in _here_ is possible.&#xA;and some [link](https://domain.com/)&#xA;&#xA;* list item 3&#xA;* list item 4&#xA;&#xA;```hcl&#xA;module &#34;foo_bar&#34; {&#xA; source = &#34;github.com/foo/bar&#34;&#xA;&#xA; id = &#34;1234567890&#34;&#xA; name = &#34;baz&#34;&#xA;&#xA; zones = [&#34;us-east-1&#34;, &#34;us-west-1&#34;]&#xA;&#xA; tags = {&#xA; Name = &#34;baz&#34;&#xA; Created-By = &#34;first.last@email.com&#34;&#xA; Date-Created = &#34;20180101&#34;&#xA; }&#xA;}&#xA;```&#xA;&#xA;Here is some trailing text after code block,&#xA;followed by another line of text.&#xA;&#xA;| Name | Description |&#xA;|------|-----------------|&#xA;| Foo | Foo description |&#xA;| Bar | Bar description |</header>
<inputs>
<input>
<name>bool-1</name>
<type>bool</type>
<description>It&#39;s bool number one.</description>
<default>true</default>
<required>false</required>
</input>
<input>
<name>bool-2</name>
<type>bool</type>
<description>It&#39;s bool number two.</description>
<default>false</default>
<required>false</required>
</input>
<input>
<name>bool-3</name>
<type>bool</type>
<description xsi:nil="true"></description>
<default>true</default>
<required>false</required>
</input>
<input>
<name>bool_default_false</name>
<type>bool</type>
<description xsi:nil="true"></description>
<default>false</default>
<required>false</required>
</input>
<input>
<name>input-with-code-block</name>
<type>list</type>
<description>This is a complicated one. We need a newline. &#xA;And an example in a code block&#xA;```&#xA;default = [&#xA; &#34;machine rack01:neptune&#34;&#xA;]&#xA;```&#xA;</description>
<default>
<item>name rack:location</item>
</default>
<required>false</required>
</input>
<input>
<name>input-with-pipe</name>
<type>string</type>
<description>It includes v1 | v2 | v3</description>
<default>v1</default>
<required>false</required>
</input>
<input>
<name>input_with_underscores</name>
<type>any</type>
<description>A variable with underscores.</description>
<default xsi:nil="true"></default>
<required>true</required>
</input>
<input>
<name>list-1</name>
<type>list</type>
<description>It&#39;s list number one.</description>
<default>
<item>a</item>
<item>b</item>
<item>c</item>
</default>
<required>false</required>
</input>
<input>
<name>list-2</name>
<type>list</type>
<description>It&#39;s list number two.</description>
<default xsi:nil="true"></default>
<required>true</required>
</input>
<input>
<name>list-3</name>
<type>list</type>
<description xsi:nil="true"></description>
<default></default>
<required>false</required>
</input>
<input>
<name>list_default_empty</name>
<type>list(string)</type>
<description xsi:nil="true"></description>
<default></default>
<required>false</required>
</input>
<input>
<name>long_type</name>
<type>object({&#xA; name = string,&#xA; foo = object({ foo = string, bar = string }),&#xA; bar = object({ foo = string, bar = string }),&#xA; fizz = list(string),&#xA; buzz = list(string)&#xA; })</type>
<description>This description is itself markdown.&#xA;&#xA;It spans over multiple lines.&#xA;</description>
<default>
<bar>
<bar>bar</bar>
<foo>bar</foo>
</bar>
<buzz>
<item>fizz</item>
<item>buzz</item>
</buzz>
<fizz></fizz>
<foo>
<bar>foo</bar>
<foo>foo</foo>
</foo>
<name>hello</name>
</default>
<required>false</required>
</input>
<input>
<name>map-1</name>
<type>map</type>
<description>It&#39;s map number one.</description>
<default>
<a>1</a>
<b>2</b>
<c>3</c>
</default>
<required>false</required>
</input>
<input>
<name>map-2</name>
<type>map</type>
<description>It&#39;s map number two.</description>
<default xsi:nil="true"></default>
<required>true</required>
</input>
<input>
<name>map-3</name>
<type>map</type>
<description xsi:nil="true"></description>
<default></default>
<required>false</required>
</input>
<input>
<name>no-escape-default-value</name>
<type>string</type>
<description>The description contains `something_with_underscore`. Defaults to &#39;VALUE_WITH_UNDERSCORE&#39;.</description>
<default>VALUE_WITH_UNDERSCORE</default>
<required>false</required>
</input>
<input>
<name>number-1</name>
<type>number</type>
<description>It&#39;s number number one.</description>
<default>42</default>
<required>false</required>
</input>
<input>
<name>number-2</name>
<type>number</type>
<description>It&#39;s number number two.</description>
<default xsi:nil="true"></default>
<required>true</required>
</input>
<input>
<name>number-3</name>
<type>number</type>
<description xsi:nil="true"></description>
<default>19</default>
<required>false</required>
</input>
<input>
<name>number-4</name>
<type>number</type>
<description xsi:nil="true"></description>
<default>15.75</default>
<required>false</required>
</input>
<input>
<name>number_default_zero</name>
<type>number</type>
<description xsi:nil="true"></description>
<default>0</default>
<required>false</required>
</input>
<input>
<name>object_default_empty</name>
<type>object({})</type>
<description xsi:nil="true"></description>
<default></default>
<required>false</required>
</input>
<input>
<name>string-1</name>
<type>string</type>
<description>It&#39;s string number one.</description>
<default>bar</default>
<required>false</required>
</input>
<input>
<name>string-2</name>
<type>string</type>
<description>It&#39;s string number two.</description>
<default xsi:nil="true"></default>
<required>true</required>
</input>
<input>
<name>string-3</name>
<type>string</type>
<description xsi:nil="true"></description>
<default></default>
<required>false</required>
</input>
<input>
<name>string-special-chars</name>
<type>string</type>
<description xsi:nil="true"></description>
<default>\.&lt;&gt;[]{}_-</default>
<required>false</required>
</input>
<input>
<name>string_default_empty</name>
<type>string</type>
<description xsi:nil="true"></description>
<default></default>
<required>false</required>
</input>
<input>
<name>string_default_null</name>
<type>string</type>
<description xsi:nil="true"></description>
<default xsi:nil="true"></default>
<required>false</required>
</input>
<input>
<name>string_no_default</name>
<type>string</type>
<description xsi:nil="true"></description>
<default xsi:nil="true"></default>
<required>true</required>
</input>
<input>
<name>unquoted</name>
<type>any</type>
<description xsi:nil="true"></description>
<default xsi:nil="true"></default>
<required>true</required>
</input>
<input>
<name>with-url</name>
<type>string</type>
<description>The description contains url. https://www.domain.com/foo/bar_baz.html</description>
<default></default>
<required>false</required>
</input>
</inputs>
<modules>
<module>
<Name>bar</Name>
<Source>baz</Source>
<Version>4.5.6</Version>
</module>
<module>
<Name>baz</Name>
<Source>baz</Source>
<Version>4.5.6</Version>
</module>
<module>
<Name>foo</Name>
<Source>bar</Source>
<Version>1.2.3</Version>
</module>
</modules>
<outputs>
<output>
<name>output-0.12</name>
<description>terraform 0.12 only</description>
</output>
<output>
<name>output-1</name>
<description>It&#39;s output number one.</description>
</output>
<output>
<name>output-2</name>
<description>It&#39;s output number two.</description>
</output>
<output>
<name>unquoted</name>
<description>It&#39;s unquoted output.</description>
</output>
</outputs>
<providers>
<provider>
<name>aws</name>
<alias xsi:nil="true"></alias>
<version>&gt;= 2.15.0</version>
</provider>
<provider>
<name>aws</name>
<alias>ident</alias>
<version>&gt;= 2.15.0</version>
</provider>
<provider>
<name>null</name>
<alias xsi:nil="true"></alias>
<version xsi:nil="true"></version>
</provider>
<provider>
<name>tls</name>
<alias xsi:nil="true"></alias>
<version xsi:nil="true"></version>
</provider>
</providers>
<requirements>
<requirement>
<name>terraform</name>
<version>&gt;= 0.12</version>
</requirement>
<requirement>
<name>aws</name>
<version>&gt;= 2.15.0</version>
</requirement>
<requirement>
<name>random</name>
<version>&gt;= 2.2.0</version>
</requirement>
</requirements>
<resources>
<resource>
<type>caller_identity</type>
<providerName>aws</providerName>
<providerSource>hashicorp/aws</providerSource>
<mode>data</mode>
<version>latest</version>
</resource>
<resource>
<type>resource</type>
<providerName>null</providerName>
<providerSource>hashicorp/null</providerSource>
<mode>managed</mode>
<version>latest</version>
</resource>
<resource>
<type>private_key</type>
<providerName>tls</providerName>
<providerSource>hashicorp/tls</providerSource>
<mode>managed</mode>
<version>latest</version>
</resource>
</resources>
</module>
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples

329
docs/reference/yaml.md Normal file
View File

@@ -0,0 +1,329 @@
---
title: "yaml"
description: "Generate YAML of inputs and outputs."
menu:
docs:
parent: "terraform-docs"
weight: 964
toc: true
---
## Synopsis
Generate YAML of inputs and outputs.
```console
terraform-docs yaml [PATH] [flags]
```
## Options
```console
-h, --help help for yaml
```
## Inherited Options
```console
-c, --config string config file name (default ".terraform-docs.yml")
--header-from string relative path of a file to read header from (default "main.tf")
--hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources]
--hide-all hide all sections (default false)
--output-values inject output values into outputs (default false)
--output-values-from string inject output values from file into outputs (default "")
--show strings show section [header, inputs, modules, outputs, providers, requirements, resources]
--show-all show all sections (default true)
--sort sort items (default true)
--sort-by-required sort items by name and print required ones first (default false)
--sort-by-type sort items by type of them (default false)
```
## Example
Given the [`examples`][examples] module:
```shell
terraform-docs yaml ./examples/
```
generates the following output:
header: |-
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 |
inputs:
- name: bool-1
type: bool
description: It's bool number one.
default: true
required: false
- name: bool-2
type: bool
description: It's bool number two.
default: false
required: false
- name: bool-3
type: bool
description: null
default: true
required: false
- name: bool_default_false
type: bool
description: null
default: false
required: false
- name: input-with-code-block
type: list
description: "This is a complicated one. We need a newline. \nAnd an example in a code block\n```\ndefault = [\n \"machine rack01:neptune\"\n]\n```\n"
default:
- name rack:location
required: false
- name: input-with-pipe
type: string
description: It includes v1 | v2 | v3
default: v1
required: false
- name: input_with_underscores
type: any
description: A variable with underscores.
default: null
required: true
- name: list-1
type: list
description: It's list number one.
default:
- a
- b
- c
required: false
- name: list-2
type: list
description: It's list number two.
default: null
required: true
- name: list-3
type: list
description: null
default: []
required: false
- name: list_default_empty
type: list(string)
description: null
default: []
required: false
- name: long_type
type: |-
object({
name = string,
foo = object({ foo = string, bar = string }),
bar = object({ foo = string, bar = string }),
fizz = list(string),
buzz = list(string)
})
description: |
This description is itself markdown.
It spans over multiple lines.
default:
bar:
bar: bar
foo: bar
buzz:
- fizz
- buzz
fizz: []
foo:
bar: foo
foo: foo
name: hello
required: false
- name: map-1
type: map
description: It's map number one.
default:
a: 1
b: 2
c: 3
required: false
- name: map-2
type: map
description: It's map number two.
default: null
required: true
- name: map-3
type: map
description: null
default: {}
required: false
- name: no-escape-default-value
type: string
description: The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'.
default: VALUE_WITH_UNDERSCORE
required: false
- name: number-1
type: number
description: It's number number one.
default: 42
required: false
- name: number-2
type: number
description: It's number number two.
default: null
required: true
- name: number-3
type: number
description: null
default: "19"
required: false
- name: number-4
type: number
description: null
default: 15.75
required: false
- name: number_default_zero
type: number
description: null
default: 0
required: false
- name: object_default_empty
type: object({})
description: null
default: {}
required: false
- name: string-1
type: string
description: It's string number one.
default: bar
required: false
- name: string-2
type: string
description: It's string number two.
default: null
required: true
- name: string-3
type: string
description: null
default: ""
required: false
- name: string-special-chars
type: string
description: null
default: \.<>[]{}_-
required: false
- name: string_default_empty
type: string
description: null
default: ""
required: false
- name: string_default_null
type: string
description: null
default: null
required: false
- name: string_no_default
type: string
description: null
default: null
required: true
- name: unquoted
type: any
description: null
default: null
required: true
- name: with-url
type: string
description: The description contains url. https://www.domain.com/foo/bar_baz.html
default: ""
required: false
modules:
- name: bar
source: baz
version: 4.5.6
- name: baz
source: baz
version: 4.5.6
- name: foo
source: bar
version: 1.2.3
outputs:
- name: output-0.12
description: terraform 0.12 only
- name: output-1
description: It's output number one.
- name: output-2
description: It's output number two.
- name: unquoted
description: It's unquoted output.
providers:
- name: aws
alias: null
version: '>= 2.15.0'
- name: aws
alias: ident
version: '>= 2.15.0'
- name: "null"
alias: null
version: null
- name: tls
alias: null
version: null
requirements:
- name: terraform
version: '>= 0.12'
- name: aws
version: '>= 2.15.0'
- name: random
version: '>= 2.2.0'
resources:
- type: caller_identity
providerName: aws
providerSource: hashicorp/aws
mode: data
version: latest
- type: resource
providerName: "null"
providerSource: hashicorp/null
mode: managed
version: latest
- type: private_key
providerName: tls
providerSource: hashicorp/tls
mode: managed
version: latest
[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples