adding option to compare outputted file with generated
terraform-doc and fail if different
Signed-off-by: Ricardo Herrera <rickhl@outlook.com>
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>
Template is optional when writing to --output-file and --output-mode is
'replace'. This is useful in particular when user wants to directly
output to a known file format, for example json, yaml, in which
sourrounding comments will break linters or functionality of those
formats.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Enables a footer to be appended to the end of a generated document
sourced from tf files or documents in the same way as the header
Adds the `footer-from` field to the config yml
Adds the `--footer-from` flag to the cli
Signed-off-by: Simon Clifford <siclifford@gmail.com>
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
This is going to preserve line-ending of extracted header text as they
are provided by users. In other words we are going to always assume the
header text is formatted in the "intended" way by users. So we're never
going to modify line-endings and won't append `<SPACE><SPACE>` at the
end of paragraph lines.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
There are two modes for saving into file:
- inject: partially replace the target file with generated output
- replace: completely replace the target file with generated output
The output generated by formatters (markdown, asciidoc, etc) will be
inserted into a template before getting saved into the file. This
template can be customized with '--output-template' CLI flag or
corresponding item in '.terraform-docs.yml' config file. Its default
value is:
```
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->
```
This consists of three items, all of them are mandatory:
- begin comment
- content variable
- end comment
You may change the wording of comment as you wish, but the comment must
be present in the template.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
