Add one extra special variable the `content`:
- `{{ .Module }}`
As opposed to the other variables, which are generated sections based on
a selected formatter, the `{{ .Module }}` variable is just a `struct`
representing a Terraform module.
It can be used to build highly complex and highly customized content:
```yaml
content: |-
## Resources
{{ range .Module.Resources }}
- {{ .GetMode }}.{{ .Spec }} ({{ .Position.Filename }}#{{ .Position.Line }})
{{- end }}
```
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Up to now there was only one way to enable recursive execution and that
was with `--recursive` CLI flag. This enables the same behavior but
within config file (i.e. `.terraform-docs.yml`)
Example:
```yaml
recursive:
enabled: false
path: modules
```
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Considering the file strucutre below of main module and its submodules,
now it is possible to generate documentation for them main and all its
submodules in one execution, with `--recursive` flag.
Note that generating documentation recursively is allowed only with
`--output-file` set.
Path to find submodules can be configured with `--recursive-path`
(defaults to `modules`).
Each submodule can also have their own `.terraform-docs.yml` confi file,
to override configuration from root module.
```
.
├── README.md
├── main.tf
├── modules
│ └── my-sub-module
│ ├── README.md
│ ├── main.tf
│ ├── variables.tf
│ └── versions.tf
├── outputs.tf
├── variables.tf
└── versions.tf
```
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
The updated order of trying to look up for .terraform-docs.yml config
file, now, is:
1. root of module directory
2. `.config/` folder at root of module directory
3. current directory
4. `.config/` folder at current directory
5. `$HOME/.tfdocs.d/`
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
New flag, `--lockfile`, is added to control whether ignore reading
.terraform.lock.hcl file in an attempt to extract the exact version of
provider being used or not. Default is true.
If set to true, exact version of provider available in lock file at the
time of execution will be extracted. If set to false, the version in .tf
file will be used (either exact, or a constrained version: >=, ~>, ...)
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
New psuedo section `all` is added and can be used to show or hide _all_
sections. This can be used as a replacement for, now, deprecated and
removed `--show-all` and `--hide-all` flags.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
In v0.13.0 flags `--show-all` and `--hide-all` have been deprecated. And
they are completely being removed now (two releases after original
announcement)
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
This is to control the generated HTML tags inside markdown output. If
set to false no html tags (e.g. `<br>`, `<pre>`) will be generated. And
as a workaround the multi-line codeblock will be converted to single
line with linebreak converted to `<SPACE>`.
For example:
```
{
"bar": {
"bar": "bar",
"foo": "bar"
},
"buzz": [
"fizz",
"buzz"
],
"fizz": []
}
```
will be converted to:
```
{ "bar": { "bar": "bar", "foo": "bar" }, "buzz": [ "fizz", "buzz" ], "fizz": [] }
```
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Local relative files can be included automatically in the generated
content with `{{ include "..." }} function. This can be very useful
for:
- inject arbitrary markdown files in between sections
- automatically include example usage
````yaml
content: |-
include any relative files
{{ include "relative/path/to/file" }}
or examples
```hcl
{{ include "examples/foo/main.tf" }}
```
````
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
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 }}`
```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 }}
```
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`
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Configuration can be loaded with `-c, --config string` which accepts
both relative and absolute paths.
$ 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 .
The order for looking for config file is:
1. root of module directory
2. current directory
3. `$HOME/.tfdocs.d/`
if `.terraform-docs.yml` is found in any of the folders above, that will
take precedence and will override the other ones. Note that values passed
directly as CLI flags will override all of the above.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
The following scenarios can happen for --output-mode inject:
- file exists, comments exist: inject output between comments
- file exists, comments not found: append output at the end of file
- file exists, but empty: save the whole output into the file
- file not found: create the target file and save the ooutput into it
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
`--output-file` or corresponding `output.file` config can now support
absolute path as well as relative path to root of module foler. For
example all of the followings are valid:
$ cd /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 .
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
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.
```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.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
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 multiple
`--show` flags. The same logic is also applied to `--hide`.
# 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`. Example:
$ 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 .
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Some of the Markdown engines (e.g. Bitbucket Cloud) are not able to
process HTML comment but as a workaround they support variation of
inline comments as follow:
- `<!-- 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`
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
This deprecates sort by flags in favor of their corresponding dynamic
valued ones. Affected flags are:
- `--sort-by-required`
- `--sort-by-type`
In return new `--sort-by string` is added with following values:
- `name` (default)
- `required`
- `type`
Note that the behavior of `--sort bool` was not changed and to disable
sorting altogether you can run `--sort false`.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
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]'.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
