Terraform Docs

This is a great utility that can generate documentation for your Terraform module code. It outputs into most formats but I use it README.md files in my GitHub repository.

Getting started

See the terraform-docs website for up to date details but it supports all the major operating systems. For Windows 11 using the chocolatey package manager the installation is as simple as:

choco install terraform-docs

Simple output

This one liner, when run in the module directory with the TF files, will create the most basic README.md file. This could be all you need.

• markdown table results in the inputs and outputs being formatted as a table.
• hide-empty hides any empty sections from the outputted file.
• > README.md directs the output to a file called README.md

terraform-docs markdown table --hide-empty . > README.md

Customized output

If using at scale or if you want to ensure others follow a strict formatting structure you can create a configuration file specificying your requirements which is loaded by terraform-docs at runtime. I find this useful for GitHub Actions as you can version your configuration file and update the repositories using it when changes are made meaning you don’t need to edit the acutaly command in the action YAML file directly.

• config specifies you want to use a config file
• .terraform-docs.yaml locates the config file in the root, you can use sub-folders.
• . means scan

terraform-docs --config .terraform-docs.yml .

This is an example terraform-docs.yml file

To take advantage of the {{ .Header }} from the main.tf being inserted into the README.md file you must format the text in the main.tf as per this example.

References

Terraform Docs