diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 67fb4f6..105aa27 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -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 }} diff --git a/docs/_index.md b/docs/_index.md index ea5d7d9..a854b97 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -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" --- diff --git a/docs/developer-guide/contributing.md b/docs/developer-guide/contributing.md index a01a2ff..0451144 100644 --- a/docs/developer-guide/contributing.md +++ b/docs/developer-guide/contributing.md @@ -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 diff --git a/docs/developer-guide/plugins.md b/docs/developer-guide/plugins.md index 52edf51..ed00e4e 100644 --- a/docs/developer-guide/plugins.md +++ b/docs/developer-guide/plugins.md @@ -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 diff --git a/docs/how-to/cli-flag-false-value.md b/docs/how-to/cli-flag-false-value.md new file mode 100644 index 0000000..9415d2e --- /dev/null +++ b/docs/how-to/cli-flag-false-value.md @@ -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 +``` diff --git a/docs/how-to/configuration-file.md b/docs/how-to/configuration-file.md new file mode 100644 index 0000000..b38ab73 --- /dev/null +++ b/docs/how-to/configuration-file.md @@ -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" >}} diff --git a/docs/how-to/generate-terraform-tfvars.md b/docs/how-to/generate-terraform-tfvars.md new file mode 100644 index 0000000..fe0f126 --- /dev/null +++ b/docs/how-to/generate-terraform-tfvars.md @@ -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 >}} diff --git a/docs/how-to/github-action.md b/docs/how-to/github-action.md new file mode 100644 index 0000000..a23c168 --- /dev/null +++ b/docs/how-to/github-action.md @@ -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 diff --git a/docs/how-to/include-examples.md b/docs/how-to/include-examples.md new file mode 100644 index 0000000..fb1965e --- /dev/null +++ b/docs/how-to/include-examples.md @@ -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 }} +```` diff --git a/docs/how-to/insert-output-to-file.md b/docs/how-to/insert-output-to-file.md new file mode 100644 index 0000000..54f11a0 --- /dev/null +++ b/docs/how-to/insert-output-to-file.md @@ -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" >}} diff --git a/docs/how-to/pre-commit-hooks.md b/docs/how-to/pre-commit-hooks.md new file mode 100644 index 0000000..3bb1e67 --- /dev/null +++ b/docs/how-to/pre-commit-hooks.md @@ -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: "" # 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 diff --git a/docs/how-to/recursive-submodules.md b/docs/how-to/recursive-submodules.md new file mode 100644 index 0000000..834e8e4 --- /dev/null +++ b/docs/how-to/recursive-submodules.md @@ -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 +``` diff --git a/docs/how-to/visibility-of-sections.md b/docs/how-to/visibility-of-sections.md new file mode 100644 index 0000000..a6f4af1 --- /dev/null +++ b/docs/how-to/visibility-of-sections.md @@ -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 ` +- `--hide ` +- `--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
` is +used, only `
` 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 + +# show 'inputs' and show 'outputs' and hide everything else +$ terraform-docs --show inputs --show outputs + +# hide 'header' and show everything else +$ terraform-docs --hide header + +# hide 'header' and hide 'providers' and show everything else +$ terraform-docs --hide header --hide providers +``` + +{{< 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" >}} diff --git a/docs/reference/asciidoc-document.md b/docs/reference/asciidoc-document.md index e836bd8..4a64885 100644 --- a/docs/reference/asciidoc-document.md +++ b/docs/reference/asciidoc-document.md @@ -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" diff --git a/docs/reference/asciidoc-table.md b/docs/reference/asciidoc-table.md index 49257a6..7737ff7 100644 --- a/docs/reference/asciidoc-table.md +++ b/docs/reference/asciidoc-table.md @@ -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" diff --git a/docs/reference/asciidoc.md b/docs/reference/asciidoc.md index 5274cea..f82ef3e 100644 --- a/docs/reference/asciidoc.md +++ b/docs/reference/asciidoc.md @@ -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" diff --git a/docs/reference/json.md b/docs/reference/json.md index 4620c20..8cf020a 100644 --- a/docs/reference/json.md +++ b/docs/reference/json.md @@ -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" diff --git a/docs/reference/markdown-document.md b/docs/reference/markdown-document.md index b5e6ef3..3859beb 100644 --- a/docs/reference/markdown-document.md +++ b/docs/reference/markdown-document.md @@ -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" diff --git a/docs/reference/markdown-table.md b/docs/reference/markdown-table.md index 74ee7a6..2167b25 100644 --- a/docs/reference/markdown-table.md +++ b/docs/reference/markdown-table.md @@ -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" diff --git a/docs/reference/markdown.md b/docs/reference/markdown.md index 13e72fb..bd2d944 100644 --- a/docs/reference/markdown.md +++ b/docs/reference/markdown.md @@ -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" diff --git a/docs/reference/pretty.md b/docs/reference/pretty.md index af44604..dc4fef7 100644 --- a/docs/reference/pretty.md +++ b/docs/reference/pretty.md @@ -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" diff --git a/docs/reference/terraform-docs.md b/docs/reference/terraform-docs.md index 9176d27..97e8de3 100644 --- a/docs/reference/terraform-docs.md +++ b/docs/reference/terraform-docs.md @@ -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" diff --git a/docs/reference/tfvars-hcl.md b/docs/reference/tfvars-hcl.md index 2664a2e..e7b2354 100644 --- a/docs/reference/tfvars-hcl.md +++ b/docs/reference/tfvars-hcl.md @@ -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" diff --git a/docs/reference/tfvars-json.md b/docs/reference/tfvars-json.md index 2b1f823..e0e4184 100644 --- a/docs/reference/tfvars-json.md +++ b/docs/reference/tfvars-json.md @@ -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" diff --git a/docs/reference/tfvars.md b/docs/reference/tfvars.md index b872d0c..4721b00 100644 --- a/docs/reference/tfvars.md +++ b/docs/reference/tfvars.md @@ -1,6 +1,6 @@ --- title: "tfvars" -description: "Generate terraform.tfvars of inputs." +description: "Generate terraform.tfvars of inputs" menu: docs: parent: "terraform-docs" diff --git a/docs/reference/toml.md b/docs/reference/toml.md index 372713e..b321db8 100644 --- a/docs/reference/toml.md +++ b/docs/reference/toml.md @@ -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" diff --git a/docs/reference/xml.md b/docs/reference/xml.md index 67503b6..df98dc4 100644 --- a/docs/reference/xml.md +++ b/docs/reference/xml.md @@ -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" diff --git a/docs/reference/yaml.md b/docs/reference/yaml.md index cb7f2fd..11f9c1a 100644 --- a/docs/reference/yaml.md +++ b/docs/reference/yaml.md @@ -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" diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 1437bc5..8fe4b5f 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -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 - -{{ .Content }} - -``` - -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 and - # 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)` -- `[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 . ``` diff --git a/docs/user-guide/configuration/content.md b/docs/user-guide/configuration/content.md new file mode 100644 index 0000000..907c0a6 --- /dev/null +++ b/docs/user-guide/configuration/content.md @@ -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 }} +``` diff --git a/docs/user-guide/configuration/footer-from.md b/docs/user-guide/configuration/footer-from.md new file mode 100644 index 0000000..6a425fa --- /dev/null +++ b/docs/user-guide/configuration/footer-from.md @@ -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 `` 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" +``` diff --git a/docs/user-guide/configuration/formatter.md b/docs/user-guide/configuration/formatter.md new file mode 100644 index 0000000..eb93fdf --- /dev/null +++ b/docs/user-guide/configuration/formatter.md @@ -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` [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" >}}) + +{{< 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" +``` diff --git a/docs/user-guide/configuration/header-from.md b/docs/user-guide/configuration/header-from.md new file mode 100644 index 0000000..b5f016e --- /dev/null +++ b/docs/user-guide/configuration/header-from.md @@ -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 `` 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" +``` diff --git a/docs/user-guide/configuration/output-values.md b/docs/user-guide/configuration/output-values.md new file mode 100644 index 0000000..6eec708 --- /dev/null +++ b/docs/user-guide/configuration/output-values.md @@ -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" +``` diff --git a/docs/user-guide/configuration/output.md b/docs/user-guide/configuration/output.md new file mode 100644 index 0000000..ed92786 --- /dev/null +++ b/docs/user-guide/configuration/output.md @@ -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 + +{{ .Content }} + +``` + +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)` +- `[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: |- + + {{ .Content }} + +``` + +## Examples + +Inject the generated output into `README.md` between the sorrounding comments. + +```yaml +output: + file: README.md + mode: inject + template: |- + + {{ .Content }} + +``` + +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 and + # 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) +``` diff --git a/docs/user-guide/configuration/sections.md b/docs/user-guide/configuration/sections.md new file mode 100644 index 0000000..0187da9 --- /dev/null +++ b/docs/user-guide/configuration/sections.md @@ -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` (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) + +{{< 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 +``` diff --git a/docs/user-guide/configuration/settings.md b/docs/user-guide/configuration/settings.md new file mode 100644 index 0000000..addd64a --- /dev/null +++ b/docs/user-guide/configuration/settings.md @@ -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 diff --git a/docs/user-guide/configuration/sort.md b/docs/user-guide/configuration/sort.md new file mode 100644 index 0000000..bc27ffe --- /dev/null +++ b/docs/user-guide/configuration/sort.md @@ -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 +``` diff --git a/docs/user-guide/configuration/version.md b/docs/user-guide/configuration/version.md new file mode 100644 index 0000000..29540d1 --- /dev/null +++ b/docs/user-guide/configuration/version.md @@ -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" +``` diff --git a/docs/user-guide/how-to.md b/docs/user-guide/how-to.md deleted file mode 100644 index efe0f30..0000000 --- a/docs/user-guide/how-to.md +++ /dev/null @@ -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 ` -- `--hide ` -- `--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
` is -used, only `
` 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 - -# show 'inputs' and show 'outputs' and hide everything else -$ terraform-docs --show inputs --show outputs - -# hide 'header' and show everything else -$ terraform-docs --hide header - -# hide 'header' and hide 'providers' and show everything else -$ terraform-docs --hide header --hide providers -``` - -**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 `` 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: "" # 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 diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md index ba7d43d..f16882d 100644 --- a/docs/user-guide/installation.md +++ b/docs/user-guide/installation.md @@ -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 diff --git a/docs/user-guide/introduction.md b/docs/user-guide/introduction.md index cdebe33..a61fd84 100644 --- a/docs/user-guide/introduction.md +++ b/docs/user-guide/introduction.md @@ -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: -[Configuration]: {{< ref "configuration" >}} +[configuration]: {{< ref "configuration" >}} [markdown table]: {{< ref "markdown-table" >}} [formats]: {{< ref "terraform-docs" >}} diff --git a/internal/print/settings.go b/internal/print/settings.go index 813d7d6..49d4f35 100644 --- a/internal/print/settings.go +++ b/internal/print/settings.go @@ -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 diff --git a/netlify.toml b/netlify.toml index 18d5baa..915ff0a 100644 --- a/netlify.toml +++ b/netlify.toml @@ -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 + """ diff --git a/scripts/docs/format.tmpl b/scripts/docs/format.tmpl index 4e14c34..246f2e7 100644 --- a/scripts/docs/format.tmpl +++ b/scripts/docs/format.tmpl @@ -1,6 +1,6 @@ --- title: "{{ .Name }}" -description: "{{ .Description }}." +description: "{{ .Description }}" menu: docs: parent: "{{ .Parent }}"