User Guide

Terraform Versions

Support for Terraform v0.12.x has been added in terraform-docs version v0.8.0. Note that you can still generate output of module configuration which is not compatible with Terraform v0.12 with terraform-docs v0.8.0 and future releases.

Syntax, Usage, and Output Formats

Please refer to Formats Guide for guidance on output formats, execution syntax, CLI options, etc.

Control Visibility of Sections

Output generated by terraform-docs consists of different sections (header, requirements, providers, inputs, outputs) which are visible by default. The visibility of these can be controlled by one or combination of : --show-all, --hide-all, --show <name> and --hide <name>. For example:

terraform-docs --show-all --hide header ...                # show all sections except 'header'
terraform-docs --hide-all --show inputs --show outputs ... # hide all sections except 'inputs' and 'outputs'

Generate Module Header

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. 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:

/**
 * # 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.

Generate terraform.tfvars

You can generate terraform.tfvars in both hcl and json format by executing the following:

terraform-docs tfvars hcl /path/to/module

# or

terraform-docs tfvars json /path/to/module

Note that any required input variables will be empty, "" in HCL and null in JSON format.

Integrating With Your Terraform Repository

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.

#!/bin/sh

# Keep module docs up to date
for d in $(ls -1 modules)
do
  terraform-docs md modules/$d > modules/$d/README.md
  if [ $? -eq 0 ] ; then
    git add "./modules/$d/README.md"
  fi
done

2.7 KiB Raw Blame History