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

Merge pull request #558 from khos2ow/restructure-docs

Browse Source 
Restructure documentations
This commit is contained in:
Khosrow Moossavi
2021-09-13 18:10:12 -04:00
committed by GitHub
parent 39b55d16d9 f33826c5df
commit 3d84cad448
45 changed files with 1373 additions and 730 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.github/workflows/ci.yaml vendored
View File

@@ -131,4 +131,7 @@ jobs:
destination-branch: main
git-user: terraform-docs-bot
git-user-email: bot@terraform-docs.io
git-commit-message: "Update website content"
git-commit-message: |-
Update website content
from: https://github.com/terraform-docs/terraform-docs/commit/${{ github.sha }}

4
docs/_index.md
View File

@@ -1,5 +1,5 @@
---
title : "terraform-docs"
description: "Generate Terraform modules documentation in various formats."
lead: "Generate Terraform modules documentation in various formats."
description: "Generate Terraform modules documentation in various formats"
lead: "Generate Terraform modules documentation in various formats"
---

6
docs/developer-guide/contributing.md
View File

@@ -1,11 +1,11 @@
---
title: "Contributing"
description: "terraform-docs contributing guide."
description: "terraform-docs contributing guide"
menu:
docs:
parent: "developer-guide"
weight: 220
toc: true
weight: 320
toc: false
---
Check [CONTRIBUTING.md](https://git.io/JtEzg) file on the root of our repository

6
docs/developer-guide/plugins.md
View File

@@ -1,11 +1,11 @@
---
title: "Plugins"
description: "terraform-docs plugin development guide."
description: "terraform-docs plugin development guide"
menu:
docs:
parent: "developer-guide"
weight: 210
toc: true
weight: 310
toc: false
---
If you want to add or change formatter, you need to write plugins. When changing

24
docs/how-to/cli-flag-false-value.md Normal file
View File

@@ -0,0 +1,24 @@
---
title: "CLI Flag 'false' value"
description: "How to use pass 'false' value to terraform-docs CLI flags"
menu:
docs:
parent: "how-to"
weight: 201
toc: false
---
Boolean flags can only take arguments via `--flag=[true|false]` or for short names
(if available) `-f=[true|false]`. You cannot use `--flag [true|false]` nor can you
use the shorthand `-f [true|false]` as it will result in the following error:
```text
Error: accepts 1 arg(s), received 2
```
Example:
```bash
# disable reading .terraform.lock.hcl
$ terraform-docs markdown --lockfile=false /path/to/module
```

44
docs/how-to/configuration-file.md Normal file
View File

@@ -0,0 +1,44 @@
---
title: "Configuration File"
description: "How to use terraform-docs configuration file"
menu:
docs:
parent: "how-to"
weight: 202
toc: false
---
Since `v0.10.0`
Configuration can be loaded with `-c, --config string`. Take a look at [configuration]
page for all the details.
```bash
$ pwd
/path/to/parent/folder
$ tree
.
├── module-a
│   └── main.tf
├── module-b
│   └── main.tf
├── ...
└── .terraform-docs.yml
# executing from parent
$ terraform-docs -c .terraform-docs.yml module-a/
# executing from child
$ cd module-a/
$ terraform-docs -c ../.terraform-docs.yml .
# or an absolute path
$ terraform-docs -c /path/to/parent/folder/.terraform-docs.yml .
```
{{< alert type="info" >}}
As of `v0.13.0`, `--config` flag accepts both relative and absolute paths.
{{< /alert >}}
[configuration]: {{< ref "configuration" >}}

24
docs/how-to/generate-terraform-tfvars.md Normal file
View File

@@ -0,0 +1,24 @@
---
title: "Generate terraform.tfvars"
description: "How to generate terraform.tfvars file with terraform-docs"
menu:
docs:
parent: "how-to"
weight: 207
toc: false
---
Since `v0.9.0`
You can generate `terraform.tfvars` in both `hcl` and `json` format by executing
the following, respectively:
```bash
terraform-docs tfvars hcl /path/to/module
terraform-docs tfvars json /path/to/module
```
{{< alert type="info" >}}
Required input variables will be `""` (empty) in HCL and `null` in JSON format.
{{< /alert >}}

39
docs/how-to/github-action.md Normal file
View File

@@ -0,0 +1,39 @@
---
title: "GitHub Action"
description: "How to use terraform-docs with GitHub Actions"
menu:
docs:
parent: "how-to"
weight: 208
toc: false
---
To use terraform-docs GitHub Action, configure a YAML workflow file (e.g.
`.github/workflows/documentation.yml`) with the following:
```yaml
name: Generate terraform docs
on:
- pull_request
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
ref: ${{ github.event.pull_request.head.ref }}
- name: Render terraform docs and push changes back to PR
uses: terraform-docs/gh-actions@main
with:
working-dir: .
output-file: README.md
output-method: inject
git-push: "true"
```
Read more about [terraform-docs GitHub Action] and its configuration and
examples.
[terraform-docs GitHub Action]: https://github.com/terraform-docs/gh-actions

47
docs/how-to/include-examples.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: "Include Examples"
description: "How to include example in terraform-docs generated output"
menu:
docs:
parent: "how-to"
weight: 205
toc: false
---
Since `v0.14.0`
Example can be automatically included into README by using `content` in configuration
file. For example:
````bash
$ tree
.
├── examples
│   ├── example-1
│   │   ├── main.tf
│ └── example-2
│ └── main.tf
├── ...
├── main.tf
├── variables.tf
├── ...
└── .terraform-docs.yml
````
and
````yaml
# .terraform-docs.yml
content: |-
{{ .Header }}
## Example
```hcl
{{ include "examples/example-1/main.tf" }}
```
{{ .Inputs }}
{{ .Outputs }}
````

43
docs/how-to/insert-output-to-file.md Normal file
View File

@@ -0,0 +1,43 @@
---
title: "Insert Output To File"
description: "How to insert generated terraform-docs output to file"
menu:
docs:
parent: "how-to"
weight: 204
toc: false
---
Since `v0.12.0`
Generated output can be insterted directly into the file. There are two modes of
insersion: `inject` (default) or `replace`. Take a look at [output] configuration
for all the details.
```bash
terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module
```
{{< alert type="info" >}}
`--output-file` can be relative to module path or an absolute path in filesystem.
{{< /alert>}}
```bash
$ pwd
/path/to/module
$ tree .
.
├── docs
│   └── README.md
├── ...
└── main.tf
# this works, relative path
$ terraform-docs markdown table --output-file ./docs/README.md .
# so does this, absolute path
$ terraform-docs markdown table --output-file /path/to/module/docs/README.md .
```
[output]: {{< ref "output" >}}

84
docs/how-to/pre-commit-hooks.md Normal file
View File

@@ -0,0 +1,84 @@
---
title: "pre-commit Hooks"
description: "How to use pre-commit hooks with terraform-docs"
menu:
docs:
parent: "how-to"
weight: 209
toc: false
---
Since `v0.12.0`
With [`pre-commit`], you can ensure your Terraform module documentation is kept
up-to-date each time you make a commit.
1. simply create or update a `.pre-commit-config.yaml`
in the root of your Git repo with at least the following content:
```yaml
repos:
- repo: https://github.com/terraform-docs/terraform-docs
rev: "<VERSION, TAG, OR SHA TO USE>" # e.g. "v0.11.2"
hooks:
- id: terraform-docs-go
args: ["ARGS", "TO PASS", "INCLUDING PATH"] # e.g. ["--output-file", "README.md", "./mymodule/path"]
```
{{< alert type="info" >}}
You can also include more than one entry under `hooks:` to update multiple docs.
Just be sure to adjust the `args:` to pass the path you want terraform-docs to scan.
{{< /alert >}}
1. install [`pre-commit`] and run `pre-commit` to activate the hooks.
1. make a Terraform change, `git add` and `git commit`.
pre-commit will regenerate your Terraform docs, after which you can
rerun `git add` and `git commit` to commit the code and doc changes together.
You can also regenerate the docs manually by running `pre-commit -a terraform-docs`.
### pre-commit via Docker
The pre-commit hook can also be run via Docker, for those who don't have Go installed.
Just use `id: terraform-docs-docker` in the previous example.
This will build the Docker image from the repo, which can be quite slow.
To download the pre-built image instead, change your `.pre-commit-config.yaml` to:
```yaml
repos:
- repo: local
hooks:
- id: terraform-docs
name: terraform-docs
language: docker_image
entry: quay.io/terraform-docs/terraform-docs:latest # or, change latest to pin to a specific version
args: ["ARGS", "TO PASS", "INCLUDING PATH"] # e.g. ["--output-file", "README.md", "./mymodule/path"]
pass_filenames: false
```
## Git Hook
A simple git hook (`.git/hooks/pre-commit`) added to your local terraform
repository can keep your Terraform module documentation up to date whenever you
make a commit. See also [git hooks] documentation.
```sh
#!/bin/sh
# Keep module docs up to date
for d in modules/*; do
if terraform-docs md "$d" > "$d/README.md"; then
git add "./$d/README.md"
fi
done
```
{{< alert type="warning" >}}
This is very basic and higly simplified version of [pre-commit-terraform](https://github.com/antonbabenko/pre-commit-terraform).
Please refer to it for complete examples and guides.
{{< /alert >}}
[`pre-commit`]: https://pre-commit.com/
[git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

45
docs/how-to/recursive-submodules.md Normal file
View File

@@ -0,0 +1,45 @@
---
title: "Recursive Submodules"
description: "How to generate submodules documentation recursively with terraform-docs"
menu:
docs:
parent: "how-to"
weight: 206
toc: false
---
Since `v0.15.0`
Considering the file strucutre below of main module and its submodules, it is
possible to generate documentation for them main and all its submodules in one
execution, with `--recursive` flag.
{{< alert type="warning" >}}
Generating documentation recursively is allowed only with `--output-file`
set.
{{< /alert >}}
Path to find submodules can be configured with `--recursive-path` (defaults to
`modules`).
Each submodule can also have their own `.terraform-docs.yml` config file, to
override configuration from root module.
```bash
$ pwd
/path/to/module
$ tree .
.
├── README.md
├── main.tf
├── modules
│   └── my-sub-module
│   ├── README.md
│   ├── main.tf
│   ├── variables.tf
│   └── versions.tf
├── outputs.tf
├── variables.tf
└── versions.tf
```

61
docs/how-to/visibility-of-sections.md Normal file
View File

@@ -0,0 +1,61 @@
---
title: "Visibility of Sections"
description: "How to control visibility of terraform-docs sections"
menu:
docs:
parent: "how-to"
weight: 203
toc: false
---
Since `v0.10.0`
Output generated by `terraform-docs` consists of different [sections] which are
visible by default. The visibility of these can be controlled by one of the following
options:
- `--show <name>`
- `--hide <name>`
- `--show-all` (deprecated in `v0.13.0`, removed in `v0.15.0`)
- `--hide-all` (deprecated in `v0.13.0`, removed in `v0.15.0`)
As of `v0.13.0` flags `--show-all` and `--hide-all` are deprecated in favor of
explicit use of `--show` and `--hide`. In other words when `--show <section>` is
used, only `<section>` will be shown. If you want to show multiple sections and
hide the rest you can specify `--show` flag multiple times. The same logic is also
applied to `--hide`.
```bash
# show 'inputs' and hide everything else
$ terraform-docs --show inputs <formatter>
# show 'inputs' and show 'outputs' and hide everything else
$ terraform-docs --show inputs --show outputs <formatter>
# hide 'header' and show everything else
$ terraform-docs --hide header <formatter>
# hide 'header' and hide 'providers' and show everything else
$ terraform-docs --hide header --hide providers <formatter>
```
{{< alert type="info" >}}
Using `--show` or `--hide` CLI flag will completely override the values
from `.terraform-docs.yml`.
{{< /alert >}}
```bash
$ cat .terraform-docs.yml
sections:
show:
- inputs
- outputs
# example 1: this will only show 'providers'
$ terraform-docs --show providers .
# example 2: this will hide 'inputs' and hide 'providers' and show everything else
$ terraform-docs --hide inputs --hide providers .
```
[sections]: {{< ref "sections" >}}

2
docs/reference/asciidoc-document.md
View File

@@ -1,6 +1,6 @@
---
title: "asciidoc document"
description: "Generate AsciiDoc document of inputs and outputs."
description: "Generate AsciiDoc document of inputs and outputs"
menu:
docs:
parent: "asciidoc"

2
docs/reference/asciidoc-table.md
View File

@@ -1,6 +1,6 @@
---
title: "asciidoc table"
description: "Generate AsciiDoc tables of inputs and outputs."
description: "Generate AsciiDoc tables of inputs and outputs"
menu:
docs:
parent: "asciidoc"

2
docs/reference/asciidoc.md
View File

@@ -1,6 +1,6 @@
---
title: "asciidoc"
description: "Generate AsciiDoc of inputs and outputs."
description: "Generate AsciiDoc of inputs and outputs"
menu:
docs:
parent: "terraform-docs"

2
docs/reference/json.md
View File

@@ -1,6 +1,6 @@
---
title: "json"
description: "Generate JSON of inputs and outputs."
description: "Generate JSON of inputs and outputs"
menu:
docs:
parent: "terraform-docs"

2
docs/reference/markdown-document.md
View File

@@ -1,6 +1,6 @@
---
title: "markdown document"
description: "Generate Markdown document of inputs and outputs."
description: "Generate Markdown document of inputs and outputs"
menu:
docs:
parent: "markdown"

2
docs/reference/markdown-table.md
View File

@@ -1,6 +1,6 @@
---
title: "markdown table"
description: "Generate Markdown tables of inputs and outputs."
description: "Generate Markdown tables of inputs and outputs"
menu:
docs:
parent: "markdown"

2
docs/reference/markdown.md
View File

@@ -1,6 +1,6 @@
---
title: "markdown"
description: "Generate Markdown of inputs and outputs."
description: "Generate Markdown of inputs and outputs"
menu:
docs:
parent: "terraform-docs"

2
docs/reference/pretty.md
View File

@@ -1,6 +1,6 @@
---
title: "pretty"
description: "Generate colorized pretty of inputs and outputs."
description: "Generate colorized pretty of inputs and outputs"
menu:
docs:
parent: "terraform-docs"

2
docs/reference/terraform-docs.md
View File

@@ -1,6 +1,6 @@
---
title: "terraform-docs"
description: "A utility to generate documentation from Terraform modules in various output formats."
description: "A utility to generate documentation from Terraform modules in various output formats"
menu:
docs:
parent: "reference"

2
docs/reference/tfvars-hcl.md
View File

@@ -1,6 +1,6 @@
---
title: "tfvars hcl"
description: "Generate HCL format of terraform.tfvars of inputs."
description: "Generate HCL format of terraform.tfvars of inputs"
menu:
docs:
parent: "tfvars"

2
docs/reference/tfvars-json.md
View File

@@ -1,6 +1,6 @@
---
title: "tfvars json"
description: "Generate JSON format of terraform.tfvars of inputs."
description: "Generate JSON format of terraform.tfvars of inputs"
menu:
docs:
parent: "tfvars"

2
docs/reference/tfvars.md
View File

@@ -1,6 +1,6 @@
---
title: "tfvars"
description: "Generate terraform.tfvars of inputs."
description: "Generate terraform.tfvars of inputs"
menu:
docs:
parent: "terraform-docs"

2
docs/reference/toml.md
View File

@@ -1,6 +1,6 @@
---
title: "toml"
description: "Generate TOML of inputs and outputs."
description: "Generate TOML of inputs and outputs"
menu:
docs:
parent: "terraform-docs"

2
docs/reference/xml.md
View File

@@ -1,6 +1,6 @@
---
title: "xml"
description: "Generate XML of inputs and outputs."
description: "Generate XML of inputs and outputs"
menu:
docs:
parent: "terraform-docs"

2
docs/reference/yaml.md
View File

@@ -1,6 +1,6 @@
---
title: "yaml"
description: "Generate YAML of inputs and outputs."
description: "Generate YAML of inputs and outputs"
menu:
docs:
parent: "terraform-docs"

336
docs/user-guide/configuration.md
View File

@@ -4,6 +4,9 @@ description: "terraform-docs configuration file, i.e. .terraform-docs.yml"
menu:
docs:
parent: "user-guide"
identifier: "configuration"
params:
collapse: true
weight: 120
toc: true
---
@@ -51,14 +54,16 @@ in `v0.15.0`)*:
if `.terraform-docs.yml` is found in any of the folders above, that will take
precedence and will override the other ones.
**Note:** Values passed directly as CLI flags will override all of the above.
{{< alert type="primary" >}}
Values passed directly as CLI flags will override all of the above.
{{< /alert >}}
## Options
Since `v0.10.0`
Below is a complete list of options that you can use with `terraform-docs`, with their
corresponding default values (if applicable).
Below is a complete list of options that can be used with `terraform-docs`, with their
default values.
```yaml
version: ""
@@ -108,311 +113,34 @@ settings:
type: true
```
**Note:** The following options cannot be used together:
{{< alert type="info" >}}
Only `formatter` is required, the rest of the options are optional.
{{< /alert >}}
- `sections.hide` and `sections.show`
- `sections.hide-all` and `sections.show-all`
- `sections.hide-all` and `sections.hide`
- `sections.show-all` and `sections.show`
## Usage
**Note:** As of `v0.13.0`, `sections.hide-all` and `sections.show-all` are deprecated
in favor of explicit use of `sections.hide` and `sections.show`, and they are removed
as of `v0.15.0`.
As of `v0.13.0`, `--config` flag accepts both relative and absolute paths.
## Version
```bash
$ pwd
/path/to/parent/folder
Since `v0.13.0`
$ tree
.
├── module-a
│   └── main.tf
├── module-b
│   └── main.tf
├── ...
└── .terraform-docs.yml
terraform-docs version constraints is almost identical to the syntax used by
Terraform. A version constraint is a string literal containing one or more condition,
which are separated by commas.
# executing from parent
$ terraform-docs -c .terraform-docs.yml module-a/
```yaml
version: ">= 0.13.0, < 1.0.0"
```
Each condition consists of an operator and a version number. A version number is
a series of numbers separated by dots (e.g. `0.13.0`). Note that version number
should not have leading `v` in it.
Valid operators are as follow:
- `=` (or no operator): allows for exact version number.
- `!=`: exclude an exact version number.
- `>`, `>=`, `<`, and `<=`: comparisons against a specific version.
- `~>`: only the rightmost version component to increment.
## Formatters
Since `v0.10.0`
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
Since `v0.10.0`
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`.
## Footer From
Since `v0.12.0`
Relative path to a file to extract footer for the generated output from. Supported
file formats are `.adoc`, `.md`, `.tf`, and `.txt`. Default value is `""`.
## Sections
Since `v0.10.0`
The following options are supported and can be used for `sections.show` and
`sections.hide`:
- `all` (since `v0.15.0`)
- `data-sources` (since `v0.13.0`)
- `header`
- `footer` (since `v0.12.0`)
- `inputs`
- `modules` (since `v0.11.0`)
- `outputs`
- `providers`
- `requirements`
- `resources` (since `v0.11.0`)
**Note:** As of `v0.13.0`, `sections.hide-all` and `sections.show-all` are deprecated
in favor of explicit use of `sections.hide` and `sections.show`, and they are removed
as of `v0.15.0`.
## Content
Since `v0.14.0`
Generated content can be customized further away with `content` in configuration.
If the `content` is empty the default orders of section is used. `content` is a
Go template with following additional variables:
- `{{ .Header }}`
- `{{ .Footer }}`
- `{{ .Inputs }}`
- `{{ .Modules }}`
- `{{ .Outputs }}`
- `{{ .Providers }}`
- `{{ .Requirements }}`
- `{{ .Resources }}`
and
- `{{ include "relative/path/to/file" }}`
````yaml
content: |-
Any arbitrary text can be placed anywhere in the content
{{ .Header }}
and even in between sections
{{ .Providers }}
and they don't even need to be in the default order
{{ .Outputs }}
{{ .Inputs }}
and include any relative files
{{ include "relative/path/to/file" }}
or examples
```hcl
{{ include "examples/foo/main.tf" }}
```
````
These variables are the generated output of individual sections in the selected
formatter. For example `{{ .Inputs }}` is Markdown Table representation of _inputs_
when formatter is set to `markdown table` and AsciiDoc Document representation
when formatter is set to `asciidoc document` and so on.
Compatible formats for customized content are:
- `asciidoc document`
- `asciidoc table`
- `markdown document`
- `markdown table`
**Note:** Sections visibility (i.e. `sections.show` and `sections.hide`) takes
precedence over the `content`. In the following example although `{{ .Providers }}`
is used it won't be rendered because `providers` is not set to be shown in
`sections.show`.
```yaml
sections:
show:
- header
- inputs
- outputs
content: |-
{{ .Header }}
Some more information can go here.
{{ .Providers }}
{{ .Inputs }}
{{ .Outputs }}
```
## Output
Since `v0.12.0`
Insert generated output to file if `output.file` (or `--output-file string` CLI
flag) is not empty. Insersion behavior can be controlled by `output.mode` (or
`--output-mode string` CLI flag):
- `inject` (default)
Partially replace the `output-file` with generated output. This will create
the `output-file` if it doesn't exist. It will also append to `output-file`
if it doesn't have surrounding comments.
- `replace`
Completely replace the `output-file` with generated output. This will create
the `output-file` if it doesn't exist.
The output generated by formatters (`markdown`, `asciidoc`, etc) will first be
inserted into a template, if provided, before getting saved into the file. This
template can be customized with `output.template` or `--output-template string`
CLI flag.
**Note:** `output.file` can be relative to module root or an absolute path.
**Note:** `output.template` is optional for mode `replace`.
The default template value is:
```text
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->
```
This template consists of at least three lines (all of which are mandatory):
- begin comment
- `{{ .Content }}` slug
- end comment
You may change the wording of comment as you wish, but the comment must be present
in the template. Also note that `SPACE`s inside `{{ }}` are mandatory.
You may also add as many lines as you'd like before or after `{{ .Content }}` line.
**Note:** `{{ .Content }}` is mandatory if you want to customize template for mode
`replace`. For example if you wish to output to YAML file with trailing comment, the
following can be used:
```yaml
formatter: yaml
output:
file: output.yaml
mode: replace
template: |-
# Example trailing comments block which will be placed at the top of the
# 'output.yaml' file.
#
# Note that there's no <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS -->
# which will break the integrity yaml file.
{{ .Content }}
```
### Template Comment
Markdown doesn't officially support inline commenting, there are multiple ways
to do it as a workaround, though. The following formats are supported as begin
and end comments of a template:
- `<!-- This is a comment -->`
- `[]: # (This is a comment)`
- `[]: # "This is a comment"`
- `[]: # 'This is a comment'`
- `[//]: # (This is a comment)`
- `[comment]: # (This is a comment)`
The following is also supported for AsciiDoc format:
- `// This is a comment`
The following can be used where HTML comments are not supported (e.g. Bitbucket
Cloud):
```yaml
output:
file: README.md
mode: inject
template: |-
[//]: # (BEGIN_TF_DOCS)
{{ .Content }}
[//]: # (END_TF_DOCS)
```
Note: The empty line before `[//]: # (END_TF_DOCS)` is mandatory in order for
Markdown engine to properly process the comment line after the paragraph.
## Sort
Since `v0.10.0`
To enable sorting of elements `sort.enabled` (or `--sort bool` CLI flag) can be
used. This will indicate sorting is enabled or not, but consecutively type of
sorting can also be specified with `sort.by` (or `--sort-by string` CLI flag).
The following sort types are supported:
- `name` (default): name of items
- `required`: by name of inputs AND show required ones first
- `type`: type of inputs
**Note:** As of `v0.13.0`, `sort.by` is converted from `list` to `string`.
```yaml
sort:
enabled: true
by: required # this now only accepts string
```
The following error is an indicator that `.terraform-docs.yml` still uses
list for `sort.by`.
```text
Error: unable to decode config, 1 error(s) decoding:
* 'sort.by' expected type 'string', got unconvertible type '[]interface {}'
# executing from child
$ cd module-a/
$ terraform-docs -c ../.terraform-docs.yml .
# or an absolute path
$ terraform-docs -c /path/to/parent/folder/.terraform-docs.yml .
```

115
docs/user-guide/configuration/content.md Normal file
View File

@@ -0,0 +1,115 @@
---
title: "content"
description: "content configuration"
menu:
docs:
parent: "configuration"
weight: 121
toc: true
---
Since `v0.14.0`
Generated content can be customized further away with `content` in configuration.
If the `content` is empty the default order of sections is used.
{{< alert type="info" >}}
Compatible formatters for customized content are `asciidoc` and `markdown`. `content`
will be ignored for other formatters.
{{< /alert >}}
`content` is a Go template with following additional variables:
- `{{ .Header }}`
- `{{ .Footer }}`
- `{{ .Inputs }}`
- `{{ .Modules }}`
- `{{ .Outputs }}`
- `{{ .Providers }}`
- `{{ .Requirements }}`
- `{{ .Resources }}`
and following functions:
- `{{ include "relative/path/to/file" }}`
These variables are the generated output of individual sections in the selected
formatter. For example `{{ .Inputs }}` is Markdown Table representation of _inputs_
when formatter is set to `markdown table` and so on.
{{< alert type="info" >}}
Sections visibility (i.e. `sections.show` and `sections.hide`) takes
precedence over the `content`.
{{< /alert >}}
## Options
Available options with their default values.
```yaml
content: ""
```
## Examples
Content can be customized, rearranged. It can have arbitrary text in between
sections:
```yaml
content: |-
Any arbitrary text can be placed anywhere in the content
{{ .Header }}
and even in between sections
{{ .Providers }}
and they don't even need to be in the default order
{{ .Outputs }}
{{ .Inputs }}
```
Relative files can be included in the `content`:
```yaml
content: |-
include any relative files
{{ include "relative/path/to/file" }}
```
`include` can be used to add example snippet code in the `content`:
````yaml
content: |-
# Examples
```hcl
{{ include "examples/foo/main.tf" }}
```
````
In the following example, although `{{ .Providers }}` is defined it won't be
rendered because `providers` is not set to be shown in `sections.show`.
```yaml
sections:
show:
- header
- inputs
- outputs
content: |-
{{ .Header }}
Some more information can go here.
{{ .Providers }}
{{ .Inputs }}
{{ .Outputs }}
```

70
docs/user-guide/configuration/footer-from.md Normal file
View File

@@ -0,0 +1,70 @@
---
title: "footer-from"
description: "footer-from configuration"
menu:
docs:
parent: "configuration"
weight: 122
toc: true
---
Since `v0.12.0`
Relative path to a file to extract footer for the generated output from. Supported
file formats are `.adoc`, `.md`, `.tf`, and `.txt`.
{{< alert type="info" >}}
The whole file content is being extracted as module footer when extracting from
`.adoc`, `.md`, or `.txt`.
{{< /alert >}}
To extract footer from `.tf` file you need to use following javascript, c, or java
like multi-line comment.
```tf
/**
* # Footer
*
* Everything in this comment block will get extracted.
*
* You can put simple text or complete Markdown content
* here. Subsequently if you want to render AsciiDoc format
* you can put AsciiDoc compatible content in this comment
* block.
*/
resource "foo" "bar" { ... }
```
{{< alert type="info" >}}
This comment must start at the immediate first line of the `.tf` file
before any `resource`, `variable`, `module`, etc.
{{< /alert >}}
{{< alert type="info" >}}
terraform-docs will never alter line-endings of extracted footer text and will assume
whatever extracted is intended as is. It's up to you to apply any kind of Markdown
formatting to them (i.e. adding `<SPACE><SPACE>` at the end of lines for break, etc.)
{{< /alert >}}
## Options
Available options with their default values.
```yaml
footer-from: ""
```
## Examples
Read `footer.md` to extract footer:
```yaml
footer-from: footer.md
```
Read `docs/.footer.md` to extract footer:
```yaml
footer-from: "docs/.footer.md"
```

81
docs/user-guide/configuration/formatter.md Normal file
View File

@@ -0,0 +1,81 @@
---
title: "formatter"
description: "formatter configuration"
menu:
docs:
parent: "configuration"
weight: 123
toc: true
---
Since `v0.10.0`
The following options are supported out of the box by terraform-docs and can be
used for `FORMATTER_NAME`:
- `asciidoc` <sup class="no-top">[reference]({{< ref "asciidoc" >}})</sup>
- `asciidoc document` <sup class="no-top">[reference]({{< ref "asciidoc-document" >}})</sup>
- `asciidoc table` <sup class="no-top">[reference]({{< ref "asciidoc-table" >}})</sup>
- `json` <sup class="no-top">[reference]({{< ref "json" >}})</sup>
- `markdown` <sup class="no-top">[reference]({{< ref "markdown" >}})</sup>
- `markdown document` <sup class="no-top">[reference]({{< ref "markdown-document" >}})</sup>
- `markdown table` <sup class="no-top">[reference]({{< ref "markdown-table" >}})</sup>
- `pretty` <sup class="no-top">[reference]({{< ref "pretty" >}})</sup>
- `tfvars hcl` <sup class="no-top">[reference]({{< ref "tfvars-hcl" >}})</sup>
- `tfvars json` <sup class="no-top">[reference]({{< ref "tfvars-json" >}})</sup>
- `toml` <sup class="no-top">[reference]({{< ref "toml" >}})</sup>
- `xml` <sup class="no-top">[reference]({{< ref "xml" >}})</sup>
- `yaml` <sup class="no-top">[reference]({{< ref "yaml" >}})</sup>
{{< alert type="info" >}}
Short version of formatters can also be used:
- `adoc` instead of `asciidoc`
- `md` instead of `markdown`
- `doc` instead of `document`
- `tbl` instead of `table`
{{< /alert >}}
{{< alert type="info" >}}
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`.
{{< /alert >}}
## Options
Available options with their default values.
```yaml
formatter: ""
```
{{< alert type="info" >}}
`formatter` is required and cannot be empty in `.terraform-docs.yml`.
{{< /alert >}}
## Examples
Format as Markdown table:
```yaml
formatter: "markdown table"
```
Format as Markdown document:
```yaml
formatter: "md doc"
```
Format as AsciiDoc document:
```yaml
formatter: "asciidoc document"
```
Format as `tfdocs-format-myplugin`:
```yaml
formatter: "myplugin"
```

70
docs/user-guide/configuration/header-from.md Normal file
View File

@@ -0,0 +1,70 @@
---
title: "header-from"
description: "header-from configuration"
menu:
docs:
parent: "configuration"
weight: 124
toc: true
---
Since `v0.10.0`
Relative path to a file to extract header for the generated output from. Supported
file formats are `.adoc`, `.md`, `.tf`, and `.txt`.
{{< alert type="info" >}}
The whole file content is being extracted as module header when extracting from
`.adoc`, `.md`, or `.txt`.
{{< /alert >}}
To extract header from `.tf` file you need to use following javascript, c, or java
like multi-line comment.
```tf
/**
* # Main title
*
* Everything in this comment block will get extracted.
*
* You can put simple text or complete Markdown content
* here. Subsequently if you want to render AsciiDoc format
* you can put AsciiDoc compatible content in this comment
* block.
*/
resource "foo" "bar" { ... }
```
{{< alert type="info" >}}
This comment must start at the immediate first line of the `.tf` file
before any `resource`, `variable`, `module`, etc.
{{< /alert >}}
{{< alert type="info" >}}
terraform-docs will never alter line-endings of extracted header text and will assume
whatever extracted is intended as is. It's up to you to apply any kind of Markdown
formatting to them (i.e. adding `<SPACE><SPACE>` at the end of lines for break, etc.)
{{< /alert >}}
## Options
Available options with their default values.
```yaml
header-from: main.tf
```
## Examples
Read `header.md` to extract header:
```yaml
header-from: header.md
```
Read `docs/.header.md` to extract header:
```yaml
header-from: "docs/.header.md"
```

43
docs/user-guide/configuration/output-values.md Normal file
View File

@@ -0,0 +1,43 @@
---
title: "output-values"
description: "output-values configuration"
menu:
docs:
parent: "configuration"
weight: 126
toc: true
---
Since `v0.10.0`
Optional value field can be added to Outputs section which contains the current
value of an output variable as it is found in state via `terraform output`.
## Options
Available options with their default values.
```yaml
output-values:
enabled: false
from: ""
```
## Examples
First generate output values file in JSON format:
```bash
$ pwd
/path/to/module
$ terraform output --json > output_values.json
```
and then use the following to render them in the generated output:
```yaml
output-values:
enabled: true
from: "output_values.json"
```

160
docs/user-guide/configuration/output.md Normal file
View File

@@ -0,0 +1,160 @@
---
title: "output"
description: "output configuration"
menu:
docs:
parent: "configuration"
weight: 125
toc: true
---
Since `v0.12.0`
Save generated output to a file, if `output.file` is not empty.
{{< alert type="info" >}}
`output.file` can be relative to module root or an absolute path.
{{< /alert >}}
Saving behavior can be controlled by `output.mode`:
- `inject` (default)
Partially replace the `output-file` content with generated output.
{{< alert type="info" >}}
This creates the `output-file` if it doesn't exist, otherwise it appends to
`output-file` if it doesn't have surrounding comments.
{{< /alert >}}
- `replace`
Completely replace the `output-file` with generated output.
{{< alert type="info" >}}
This creates the `output-file` if it doesn't exist.
{{< /alert >}}
The output generated by formatters (`markdown`, `asciidoc`, etc) will first be
inserted into a template before getting saved into the file. This template can be
customized with `output.template`.
{{< alert type="info" >}}
`output.template` is optional for mode `replace`.
{{< /alert >}}
The default template value is:
```text
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->
```
This template consists of at least three lines (all of which are mandatory):
- begin comment
- `{{ .Content }}` slug
- end comment
Wording of the comments may be changed as necessary, but the comment must be
present in the template. Also note that `SPACE`s inside `{{ }}` are mandatory.
You may also add as many lines as you'd like before or after `{{ .Content }}` line.
{{< alert type="info" >}}
If you want to customize template for mode `replace`, `{{ .Content }}` is mandatory.
{{< /alert >}}
## Template Comment
Markdown doesn't officially support inline commenting, there are multiple ways
to do it as a workaround, though. The following formats are supported as begin
and end comments of a template:
- `<!-- This is a comment -->`
- `[]: # (This is a comment)`
- `[]: # "This is a comment"`
- `[]: # 'This is a comment'`
- `[//]: # (This is a comment)`
- `[comment]: # (This is a comment)`
The following is also supported for AsciiDoc format:
- `// This is a comment`
## Options
Available options with their default values.
```yaml
output:
file: ""
mode: inject
template: |-
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->
```
## Examples
Inject the generated output into `README.md` between the sorrounding comments.
```yaml
output:
file: README.md
mode: inject
template: |-
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->
```
Replace the content of `USAGE.md` with generated output. Note that any manual
changes to that file will be overwritten.
```yaml
output:
file: USAGE.md
mode: replace
template: |-
{{ .Content }}
```
To output to YAML file with leading comment, the following can be used:
```yaml
formatter: yaml
output:
file: output.yaml
mode: replace
template: |-
# Example leading comments block which will be placed at the top of the
# 'output.yaml' file.
#
# Note that there's no <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS -->
# which will break the integrity yaml file.
{{ .Content }}
```
The following can be used where HTML comments are not supported (e.g. Bitbucket
Cloud):
{{< alert type="warning" >}}
The empty line before `[//]: # (END_TF_DOCS)` is mandatory in order for
Markdown engine to properly process the comment line after the paragraph.
{{< /alert >}}
```yaml
output:
file: README.md
mode: inject
template: |-
[//]: # (BEGIN_TF_DOCS)
{{ .Content }}
[//]: # (END_TF_DOCS)
```

73
docs/user-guide/configuration/sections.md Normal file
View File

@@ -0,0 +1,73 @@
---
title: "sections"
description: "sections configuration"
menu:
docs:
parent: "configuration"
weight: 127
toc: true
---
Since `v0.10.0`
The following options are supported and can be used for `sections.show` and
`sections.hide`:
- `all` <sup class="no-top">(since v0.15.0)</sup>
- `data-sources` <sup class="no-top">(since v0.13.0)</sup>
- `header`
- `footer` <sup class="no-top">(since v0.12.0)</sup>
- `inputs`
- `modules` <sup class="no-top">(since v0.11.0)</sup>
- `outputs`
- `providers`
- `requirements`
- `resources` <sup class="no-top">(since v0.11.0)</sup>
{{< alert type="warning" >}}
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`
{{< /alert >}}
{{< alert type="info" >}}
As of `v0.13.0`, `sections.hide-all` and `sections.show-all` are deprecated
in favor of explicit use of `sections.hide` and `sections.show`, and they are removed
as of `v0.15.0`.
{{< /alert >}}
## Options
Available options with their default values.
```yaml
sections:
hide: []
show: []
hide-all: false # deprecated in v0.13.0, removed in v0.15.0
show-all: true # deprecated in v0.13.0, removed in v0.15.0
```
## Examples
Show only `providrs`, `inputs`, and `outputs`.
```yaml
sections:
show:
- providers
- inputs
- outputs
```
Show everything except `providrs`.
```yaml
sections:
hide:
- providers
```

150
docs/user-guide/configuration/settings.md Normal file
View File

@@ -0,0 +1,150 @@
---
title: "settings"
description: "settings configuration"
menu:
docs:
parent: "configuration"
weight: 128
toc: true
---
Since `v0.10.0`
General settings to control the behavior and generated output items.
## Options
Available options with their default values.
```yaml
settings:
anchor: true
color: true
default: true
description: false
escape: true
hide-empty: false
html: true
indent: 2
lockfile: true
required: true
sensitive: true
type: true
```
### anchor
> since: `v0.12.0`\
> scope: `asciidoc`, `markdown`
Generate HTML anchor tag for elements.
### color
> since: `v0.10.0`\
> scope: `pretty`
Print colorized version of result in the terminal.
### default
> since: `v0.12.0`\
> scope: `asciidoc`, `markdown`
Show "Default" value as column (in table format) or section (in document format).
### description
> since: `v0.13.0`\
> scope: `tfvars hcl`
Show "Descriptions" as comment on variables.
### escape
> since: `v0.10.0`\
> scope: `asciidoc`, `json`, `markdown`
Escape special characters (such as `_`, `*` in Markdown and `>`, `<` in JSON)
### hide-empty
> since: `v0.16.0`\
> scope: `asciidoc`, `markdown`
Hide empty sections.
### html
> since: `v0.14.0`\
> scope: `markdown`
Generate HTML tags (`a`, `pre`, `br`, ...) in the output.
### indent
> since: `v0.10.0`\
> scope: `asciidoc`, `markdown`
Indentation level of headings [available: 1, 2, 3, 4, 5].
### lockfile
> since: `v0.15.0`\
> scope: `global`
Read `.terraform.lock.hcl` to extract exact version of providers.
### required
> since: `v0.10.0`\
> scope: `asciidoc`, `markdown`
Show "Required" as column (in table format) or section (in document format).
### sensitive
> since: `v0.10.0`\
> scope: `asciidoc`, `markdown`
Show "Sensitive" as column (in table format) or section (in document format).
### type
> since: `v0.12.0`\
> scope: `asciidoc`, `markdown`
Show "Type" as column (in table format) or section (in document format).
## Examples
Markdown linters rule [MD033] prohibits using raw HTML in markdown document,
the following can be used to appease it:
```yaml
settings:
anchor: false
html: false
```
If `.terraform.lock.hcl` is not checked in the repository, running terraform-docs
potentially will produce different providers version on each execution, to prevent
this you can disable it by:
```yaml
settings:
lockfile: false
```
For simple modules the generated documentation contains a lot of sections that
simply say "no outputs", "no resources", etc. It is possible to hide these empty
sections manually, but if the module changes in the future, they explicitly have
to be enabled again. The following can be used to let terraform-docs automatically
hide empty sections:
```yaml
settings:
hide-empty: true
```
[MD033]: https://github.com/markdownlint/markdownlint/blob/5329a84691ab0fbce873aa69bb5073a6f5f98bdb/docs/RULES.md#md033---inline-html

68
docs/user-guide/configuration/sort.md Normal file
View File

@@ -0,0 +1,68 @@
---
title: "sort"
description: "sort configuration"
menu:
docs:
parent: "configuration"
weight: 129
toc: true
---
Since `v0.10.0`
To enable sorting of elements `sort.enabled` can be used. This will indicate
sorting is enabled or not, but consecutively type of sorting can also be specified
with `sort.by`. The following sort types are supported:
- `name` (default): name of items
- `required`: by name of inputs AND show required ones first
- `type`: type of inputs
## Options
Available options with their default values.
```yaml
sort:
enabled: true
by: name
```
{{< alert type="warning" >}}
As of `v0.13.0`, `sort.by` is converted from `list` to `string`.
{{< /alert >}}
The following error is an indicator that `.terraform-docs.yml` still uses
list for `sort.by`.
```text
Error: unable to decode config, 1 error(s) decoding:
* 'sort.by' expected type 'string', got unconvertible type '[]interface {}'
```
## Examples
Disable sorting:
```yaml
sort:
enabled: false
```
Sort by name (terraform-docs `>= v0.13.0`):
```yaml
sort:
enabled: true
by: name
```
Sort by required (terraform-docs `< v0.13.0`):
```yaml
sort:
enabled: true
by:
- required
```

42
docs/user-guide/configuration/version.md Normal file
View File

@@ -0,0 +1,42 @@
---
title: "version"
description: "version configuration"
menu:
docs:
parent: "configuration"
weight: 130
toc: true
---
Since `v0.13.0`
terraform-docs version constraints is almost identical to the syntax used by
Terraform. A version constraint is a string literal containing one or more condition,
which are separated by commas.
Each condition consists of an operator and a version number. A version number is
a series of numbers separated by dots (e.g. `0.13.0`). Note that version number
should not have leading `v` in it.
Valid operators are as follow:
- `=` (or no operator): allows for exact version number.
- `!=`: exclude an exact version number.
- `>`, `>=`, `<`, and `<=`: comparisons against a specific version.
- `~>`: only the rightmost version component to increment.
## Options
Available options with their default values.
```yaml
version: ""
```
## Examples
Only allow terraform-docs version between `0.13.0` and `1.0.0`:
```yaml
version: ">= 0.13.0, < 1.0.0"
```

384
docs/user-guide/how-to.md
View File

@@ -1,384 +0,0 @@
---
title: "How To's"
description: "terraform-docs how to's on variety of topics."
menu:
docs:
parent: "user-guide"
weight: 130
toc: true
---
## CLI Flag 'false' value
Boolean flags can only take arguments via `--flag=[true|false]` or for short names
(if available) `-f=[true|false]`. You cannot use `--flag [true|false]` nor can you
use the shorthand `-f [true|false]` as it will result in the following error:
```text
Error: accepts 1 arg(s), received 2
```
## Configuration File
Since `v0.10.0`
Configuration can be loaded with `-c, --config string`. Take a look at [configuration]
page for all the details.
As of `v0.13.0`, `--config` flag accepts both relative and absolute paths.
```bash
$ pwd
/path/to/parent/folder
$ tree
.
├── module-a
│   └── main.tf
├── module-b
│   └── main.tf
├── ...
└── .terraform-docs.yml
# executing from parent
$ terraform-docs -c .terraform-docs.yml module-a/
# executing from child
$ cd module-a/
$ terraform-docs -c ../.terraform-docs.yml .
# or an absolute path
$ terraform-docs -c /path/to/parent/folder/.terraform-docs.yml .
```
## Visibility of Sections
Since `v0.10.0`
Output generated by `terraform-docs` consists of different [sections] which are
visible by default. The visibility of these can be controlled by one of the following
options:
- `--show <name>`
- `--hide <name>`
- `--show-all` (deprecated in `v0.13.0`, removed in `v0.15.0`)
- `--hide-all` (deprecated in `v0.13.0`, removed in `v0.15.0`)
As of `v0.13.0` flags `--show-all` and `--hide-all` are deprecated in favor of
explicit use of `--show` and `--hide`. In other words when `--show <section>` is
used, only `<section>` will be shown. If you want to show multiple sections and
hide the rest you can specify `--show` flag multiple times. The same logic is also
applied to `--hide`.
```bash
# show 'inputs' and hide everything else
$ terraform-docs --show inputs <formatter>
# show 'inputs' and show 'outputs' and hide everything else
$ terraform-docs --show inputs --show outputs <formatter>
# hide 'header' and show everything else
$ terraform-docs --hide header <formatter>
# hide 'header' and hide 'providers' and show everything else
$ terraform-docs --hide header --hide providers <formatter>
```
**Note:** Using `--show` or `--hide` CLI flag will completely override the values
from `.terraform-docs.yml`.
```bash
$ cat .terraform-docs.yml
sections:
show:
- inputs
- outputs
# example 1: this will only show 'providers'
$ terraform-docs --show providers .
# example 2: this will hide 'inputs' and hide 'providers' and show everything else
$ terraform-docs --hide inputs --hide providers .
```
## Module Header
Since `v0.10.0`
Module header can be extracted from different sources. Default file to extract
header from is `main.tf`, otherwise you can specify the file with `--header-from FILE`
or corresponding `header-from` in configuration file. Supported file formats to
read header from are:
- `.adoc`
- `.md`
- `.tf`
- `.txt`
The whole file content is being extracted as module header when extracting from
`.adoc`, `.md`, or `.txt`. But to extract header from `.tf` file you need to use
following javascript, c or java like multi-line comment:
```tf
/**
* # Main title
*
* Everything in this comment block will get extracted.
*
* You can put simple text or complete Markdown content
* here. Subsequently if you want to render AsciiDoc format
* you can put AsciiDoc compatible content in this comment
* block.
*/
resource "foo" "bar" { ... }
```
**Note:** This comment must start at the immediate first line of the `.tf` file
before any `resource`, `variable`, `module`, etc.
**Note:** we will never alter line-endings of extracted header text and will assume
whatever extracted is intended as is. It's up to you to apply any kind of Markdown
formatting to them (i.e. adding `<SPACE><SPACE>` at the end of lines for break, etc.)
## Module Footer
Since `v0.12.0`
Extracting module footer works exactly like header with one exception. There is no
default file to attempt extraction from, you need to explicitly specify desired file
to extract content from with `--footer-from FILE` or corresponding `footer-from` in
configuration file.
## Include Examples
Since `v0.14.0`
Example can be automatically included into README by using `content` in configuration
file. There are [multiple variables and function] available in `content`. As an example:
````bash
$ tree
.
├── examples
│   ├── example-1
│   │   ├── main.tf
│ └── example-2
│ └── main.tf
├── ...
├── main.tf
├── variables.tf
├── ...
└── .terraform-docs.yml
````
and
````yaml
# .terraform-docs.yml
content: |-
{{ .Header }}
## Example
```hcl
{{ include "examples/example-1/main.tf" }}
```
{{ .Inputs }}
{{ .Outputs }}
````
## Insert Output To File
Since `v0.12.0`
Generated output can be insterted directly into the file. There are two modes of
insersion: `inject` (default) or `replace`. Take a look at [output] configuration
for all the details.
```bash
terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module
```
Note that `--output-file` can be relative to module path or an absolute path in
filesystem.
```bash
$ pwd
/path/to/module
$ tree .
.
├── docs
│   └── README.md
├── ...
└── main.tf
# this works, relative path
$ terraform-docs markdown table --output-file ./docs/README.md .
# so does this, absolute path
$ terraform-docs markdown table --output-file /path/to/module/docs/README.md .
```
## Recursive Submodules
Since `v0.15.0`
Considering the file strucutre below of main module and its submodules, 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.
```bash
$ pwd
/path/to/module
$ tree .
.
├── README.md
├── main.tf
├── modules
│   └── my-sub-module
│   ├── README.md
│   ├── main.tf
│   ├── variables.tf
│   └── versions.tf
├── outputs.tf
├── variables.tf
└── versions.tf
```
## Generate terraform.tfvars
Since `v0.9.0`
You can generate `terraform.tfvars` in both `hcl` and `json` format by executing
the following, respectively:
```bash
terraform-docs tfvars hcl /path/to/module
terraform-docs tfvars json /path/to/module
```
**Note:** Required input variables will be `""` (empty) in HCL and `null` in JSON
format.
## GitHub Action
To use terraform-docs GitHub Action, configure a YAML workflow file (e.g.
`.github/workflows/documentation.yml`) with the following:
```yaml
name: Generate terraform docs
on:
- pull_request
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
ref: ${{ github.event.pull_request.head.ref }}
- name: Render terraform docs and push changes back to PR
uses: terraform-docs/gh-actions@v0.6.0
with:
working-dir: .
output-file: USAGE.md
output-method: inject
git-push: "true"
```
Read more about [terraform-docs GitHub Action] and its configuration and
examples.
## Pre-commit Hook
Since `v0.12.0`
With [`pre-commit`], you can ensure your Terraform module documentation is kept
up-to-date each time you make a commit.
First, simply create or update a `.pre-commit-config.yaml`
in the root of your Git repo with at least the following content:
```yaml
repos:
- repo: https://github.com/terraform-docs/terraform-docs
rev: "<VERSION, TAG, OR SHA TO USE>" # e.g. "v0.11.2"
hooks:
- id: terraform-docs-go
args: ["ARGS", "TO PASS", "INCLUDING PATH"] # e.g. ["--output-file", "README.md", "./mymodule/path"]
```
(You can also include more than one entry under `hooks:` to update multiple docs.
Just be sure to adjust the `args:` to pass the path you want terraform-docs to scan.)
Second, install [`pre-commit`] and run `pre-commit` to activate the hooks.
Then, make a Terraform change, `git add` and `git commit`!
Pre-commit will regenerate your Terraform docs, after which you can
rerun `git add` and `git commit` to commit the code and doc changes together.
You can also regenerate the docs manually by running `pre-commit -a terraform-docs`.
### Pre-commit via Docker
The pre-commit hook can also be run via Docker, for those who don't have Go installed.
Just use `id: terraform-docs-docker` in the previous example.
This will build the Docker image from the repo, which can be quite slow.
To download the pre-built image instead, change your `.pre-commit-config.yaml` to:
```yaml
repos:
- repo: local
hooks:
- id: terraform-docs
name: terraform-docs
language: docker_image
entry: quay.io/terraform-docs/terraform-docs:latest # or, change latest to pin to a specific version
args: ["ARGS", "TO PASS", "INCLUDING PATH"] # e.g. ["--output-file", "README.md", "./mymodule/path"]
pass_filenames: false
```
## Git Hook
A simple git hook (`.git/hooks/pre-commit`) added to your local terraform
repository can keep your Terraform module documentation up to date whenever you
make a commit. See also [git hooks] documentation.
```sh
#!/bin/sh
# Keep module docs up to date
for d in modules/*; do
if terraform-docs md "$d" > "$d/README.md"; then
git add "./$d/README.md"
fi
done
```
**Note:** This is very basic and higly simplified version of [pre-commit-terraform].
Please refer to it for complete examples and guides.
[configuration]: {{< ref "configuration/" >}}
[sections]: {{< ref "configuration/#sections" >}}
[output]: {{< ref "configuration/#output" >}}
[terraform-docs GitHub Action]: https://github.com/terraform-docs/gh-actions
[`pre-commit`]: https://pre-commit.com/
[git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks
[pre-commit-terraform]: https://github.com/antonbabenko/pre-commit-terraform

18
docs/user-guide/installation.md
View File

@@ -1,6 +1,6 @@
---
title: "Installation"
description: "terraform-docs installation guide."
description: "terraform-docs installation guide"
menu:
docs:
parent: "user-guide"
@@ -53,9 +53,11 @@ You also can run `terraform-docs` as a container:
docker run quay.io/terraform-docs/terraform-docs:0.15.0
```
Docker tag `latest` refers to _latest_ stable released version and `edge`refers
{{< alert type="primary" >}}
Docker tag `latest` refers to _latest_ stable released version and `edge` refers
to HEAD of `master` at any given point in time. And any named version tags are
identical to the official GitHub releases without leading `v`.
{{< /alert >}}
## Pre-compiled Binary
@@ -69,7 +71,9 @@ chmod +x terraform-docs
mv terraform-docs /some-dir-in-your-PATH/terraform-docs
```
**Note:** Windows releases are in `ZIP` format.
{{< alert type="primary" >}}
Windows releases are in `ZIP` format.
{{< /alert >}}
## Go Users
@@ -79,15 +83,19 @@ The latest version can be installed using `go get`:
GO111MODULE="on" go get github.com/terraform-docs/terraform-docs@v0.15.0
```
**NOTE:** to download any version **before** `v0.9.1` (inclusive) you need to use to
{{< alert type="warning" >}}
To download any version **before** `v0.9.1` (inclusive) you need to use to
old module namespace (`segmentio`):
{{< /alert >}}
```bash
# only for v0.9.1 and before
GO111MODULE="on" go get github.com/segmentio/terraform-docs@v0.9.1
```
**NOTE:** please use the latest Go to do this, minimum `go1.16` or greater.
{{< alert type="primary" >}}
Please use the latest Go to do this, minimum `go1.16` or greater.
{{< /alert >}}
This will put `terraform-docs` in `$(go env GOPATH)/bin`. If you encounter the error
`terraform-docs: command not found` after installation then you may need to either add

6
docs/user-guide/introduction.md
View File

@@ -1,6 +1,6 @@
---
title: "Introduction"
description: "Generate documentation from Terraform modules in various output formats."
description: "Generate documentation from Terraform modules in various output formats"
menu:
docs:
parent: "user-guide"
@@ -23,7 +23,7 @@ of a CI pipeline) all you need to do is run `terraform-docs /module/path`.
{{< img-simple src="config.png" >}}
Read all about [Configuration].
Read all about [configuration].
## Formats
@@ -65,6 +65,6 @@ terraform-docs compatiblity matrix with Terraform can be found below:
</tbody>
</table>
[Configuration]: {{< ref "configuration" >}}
[configuration]: {{< ref "configuration" >}}
[markdown table]: {{< ref "markdown-table" >}}
[formats]: {{< ref "terraform-docs" >}}

14
internal/print/settings.go
View File

@@ -29,7 +29,7 @@ type Settings struct {
// scope: Asciidoc, Markdown
HideEmpty bool
// IndentLevel control the indentation of headers [available: 1, 2, 3, 4, 5]
// IndentLevel control the indentation of headings [available: 1, 2, 3, 4, 5]
//
// default: 2
// scope: Asciidoc, Markdown
@@ -41,7 +41,7 @@ type Settings struct {
// scope: Global
OutputValues bool
// ShowAnchor show html anchor
// ShowAnchor generate HTML anchor tag for elements
//
// default: true
// scope: Asciidoc, Markdown
@@ -59,7 +59,7 @@ type Settings struct {
// scope: Global
ShowDataSources bool
// ShowDefault show "Default" column
// ShowDefault show "Default" as column (in table) or section (in document)
//
// default: true
// scope: Asciidoc, Markdown
@@ -83,7 +83,7 @@ type Settings struct {
// scope: Global
ShowHeader bool
// ShowHTML use HTML tags (a, pre, br, ...)
// ShowHTML generate HTML tags (a, pre, br, ...) in the output
//
// default: true
// scope: Markdown
@@ -113,13 +113,13 @@ type Settings struct {
// scope: Global
ShowProviders bool
// ShowRequired show "Required" column
// ShowRequired show "Required" as column (in table) or section (in document)
//
// default: true
// scope: Asciidoc, Markdown
ShowRequired bool
// ShowSensitivity show "Sensitive" column
// ShowSensitivity show "Sensitive" as column (in table) or section (in document)
//
// default: true
// scope: Asciidoc, Markdown
@@ -137,7 +137,7 @@ type Settings struct {
// scope: Global
ShowResources bool
// ShowType show "Type" column
// ShowType show "Type" as column (in table) or section (in document)
//
// default: true
// scope: Asciidoc, Markdown

9
netlify.toml
View File

@@ -2,9 +2,14 @@
publish = "site/public"
[build.environment]
HUGO_VERSION = "0.80.0"
HUGO_VERSION = "0.87.0"
NODE_VERSION = "15.5.1"
NPM_VERSION = "7.3.0"
[context.deploy-preview]
command = "./scripts/docs/prepare-site.sh && cd site && npm install && hugo -b ${DEPLOY_PRIME_URL} --gc"
command = """
./scripts/docs/prepare-site.sh
cd site
npm install
hugo -b ${DEPLOY_PRIME_URL} --gc
"""

2
scripts/docs/format.tmpl
View File

@@ -1,6 +1,6 @@
---
title: "{{ .Name }}"
description: "{{ .Description }}."
description: "{{ .Description }}"
menu:
docs:
parent: "{{ .Parent }}"