Generate documentation from Terraform modules in various output formats
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.17.0
Very special thanks to the contributors.
f613750 Add 'HideEmpy' section bool flag 6f97f67 Add abitlity to partially override config from submodules de684ce Add public ReadConfig function 54dc0f5 Add recursive config to .terraform-docs.yml file 89648f7 Add sprig functions to built-in template functions f3c9238 Extract leading comments for resources and modules 045707b feat: Add new flag 'read-comments' to optionally process comments as description
5a1210b Skip read lines from empty file
465dd14 Make terraform.Module available in content 90942f7 Move format package from internal to public 4a9ffe7 Move plugin-sdk to in-tree in core repository d2fe2b1 Move print package from internal to public b3ff514 Move template package from internal to public ca8f833 Move template package from internal to public
f33826c Cleanup documentations bb10971 Deprecate Settings and Options in favor of Config 3d2b878 Overhaul README and docs improvements 1ae5fd9 Restructure configurations docs 0ad14a3 Restructure how-tos docs 628f2c6 Update Netlify config and build CI
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.16.0
Very special thanks to the contributors.
The most notable changes in this release are:
Generate submodules documents with --recursive flag
Considering the file structure below of main module and its submodules, now it is possible to generate documentation for them main and all its submodules in one execution.
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 config 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
Ignore extracting versions from terraform.lock.hcl
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: >=, ~>, ...)
The updated order of trying to look up for .terraform-docs.yml config file, now, is:
.config/ folder at root of module directory.config/ folder at current directory$HOME/.tfdocs.d/
add output-check option for outputs
This option can be used to compare content of target file with generated output by terraform-doc and fail if different.
Remove --show-all, --hide-all, and --sort-by-XXX flags. (which have been deprecated in v0.13.0)
d77324c Add new '--show all' and '--hide all' sections d004771 Add support for generating Packer document f46a48b Attempt looking up config file in .config folder 1450ee9 Generate submodules documents with '--recursive' flag 5256426 Ignore extracting versions from terraform.lock.hcl 25f03b4 Remove deprecated '--show-all' and '--hide-all' flags 258f460 Remove deprecated '--sort-by-XXX' flags 21eaab4 add output-check option for outputs
ab05309 Process \n as line break in --output-template flag c14edaf Properly format indented code blocks 61cc005 Render resources without URL correctly in Markdown and Asciidoc
8a288b5 Add Scalr sponsorship af68ca2 Add new example for MacOs Install docs 77bc780 Bump alpine to 3.14.0 dfd1256 Bump golang to 1.16.6-alpine bb1e21a Cosmetic cleanup asciidoc module table 490644e Increase test coverage for Config 209ed66 Upgrade go dependencies 567cfcc updating how-to doc for correct Include Examples syntax
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.15.0
Very special thanks to the contributors.
This is a small patch over v0.14.0. It fixes base template not found error on Windows. You can ignore updating to this version if you are not running terraform-docs on Windows.
30b429d Fix base template not found on Windows
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.14.1
The most notable changes in this release are:
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 }}
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
Local relative files can be included automatically in the generated content with `{{ include "..." }} function. This can be very useful for:
content: |-
include any relative files
{{ include "relative/path/to/file" }}
or examples
```hcl
{{ include "examples/foo/main.tf" }}
```
Add --html bool flag and config to Markdown 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 onverted 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": [] }
2f088f2 Add '--html bool' flag and config to Markdown
6777364 Customize content with individual sections output
ea34bce Include relative files into generated content
57cf3db Extract provider version from .terraform.lock.hcl
0284283 Separate the module version from module source when using ?ref=
90ccb84 Add missing Resource.Mode to plugin-sdk (#493) 6820b4c Normalize version to prevent malformed error
bd32f8c Bump action-homebrew-bump-formula action to v3.8.0 7327de1 Clarify deprecated settings in the docs (#499) d79abf0 Documentation cosmetic cleanup 2706df0 Enable CodeQL scanning 5df7ff2 Improve Makefile help message 23436be Update release scripts 7f63260 Update to go1.16.4 4397fac Validate license header on files on CI
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.14.0
Very special thanks to the contributors.
The most notable changes in this release are:
Add support for Terraform v0.15 and configuration_aliases (thanks to @adamjohnson01)
Add ability to show or hide data-sources (thanks to @edgarsandi)
Read .terraform-docs.yml from relative path, absolute path, or $HOME (more info)
# 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 .
Support outputing to file for absolute path (more info)
# 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 .
Version constraints configuration (more info)
# .terraform-docs.yml
version: ">= 0.13.0, < 1.0.0"
We're no longer distributing standalone binaries. Only compressed files (either tar.gz or zip) will be available to download from GitHub Release page.
--sort-by-XX flags are deprecated in favor of corresponding dynamic --sort-by XX. 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.
Note than the type of sort.by in .terraform-docs.yml has been changed from list to string
sort:
enabled: true
by: required # this now only accepts string
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 .
c8fc7ab add ability to show or hide data-sources d914ca7 Add a flag for showing description with hcl formatted tfvars a26111f Add support for configuration_aliases fcd314b Read config from relative path, absolute, or $HOME 0eea133 Support inline comments variation for Markdown and AsciiDoc 845469c Support outputing to file for absolute path dabf54f Version constraints configuration
4be2223 In output-mode inject do not fail if file not found
557d53d Deprecate '--sort-by-XX' in favor of '--sort-by XX' 8c531b6 Deprecate --show-all and --hide-all flags 40f9b9d Do not distribute standalone binaries 2ea8635 Remove unused build tools from dockerfile
b4981a1 Add 'since version' to docs for clarity 1415ac9 Add Terraform compatibility matrix documentation 6b0cf54 Add document for 'false' value for CLI flag 2784920 Update doc to indicate minimum go1.16 is needed
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.13.0
Very special thanks to the contributors.
This is a small patch over v0.12.0. It fixes missing footer-from from CLI and config (#449). You can ignore updating to this version if you are not using footer in your module output.
7a6f6c1 Fix missing footer-from if set via CLI flag or config e4a3a84 print cli errors to stderr
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.12.1
Very special thanks to the contributors.
The most notable changes in this release are:
Add support for footer (thanks to @simonc-613)
Add anchors for markdown, asciidocs items (thanks to @nitrocode)
Save generated content directly into a file (mode inject and replace)
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 -->
Remove --no-XXX flags. (in v0.10.0 --no-XXX have been deprecated in favor of their counterparts in the format of --XXX=false)
aa1e6bb Add support for footer docs 1168e12 Add support for pre-commit hooks ac5a29c Implement module sort by position (no sort) 243fb27 add mode resource or data source to generated docs a3bafd6 Save generated content directly into a file 8c05cb9 Add resource 'Name' to generated docs 3d39a94 Add option to hide Type and Default columns 02f490d --anchor to add anchors for markdown, asciidocs 25d2ff4 Completely remove deprecated '--no-XXX' flags
7e489d2 Do not modify header lines and trailing whitespaces c94b43a Template should be optional for output-mode 'replace'
10cd6de Add DCO file 5b57ea4 Disable codecov patch status 3cc4f44 Fix issues reported by golangci-lint 8faaf9f Remove authors file and corresponding scripts c246442 Remove changelog and corresponding scripts 0c25f7b Update golangci-lint configuration
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.12.0
Very special thanks to the contributors.
terraform-docs v0.12.0-beta.1 is a pre-release. It is to help gather feedback from the community as well as give users a chance to test terraform-docs in staging environments before v0.12.0 is officially released.
a3bafd6 Save generated content directly into a file 8c05cb9 Add resource 'Name' to generated docs 3d39a94 Add option to hide Type and Default columns 02f490d --anchor to add anchors for markdown, asciidocs 25d2ff4 Completely remove deprecated '--no-XXX' flags
docker pull quay.io/terraform-docs/terraform-docs:0.12.0-beta.1
09ab491 Fixed lexicographic sorting of resources fef4035 Use 'latest' as resource link if not a fixed version
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.11.2
Very special thanks to the contributors.