terraform-docs

Sponsored by Scalr - Terraform Automation & Collaboration Software

What is terraform-docs

A utility to generate documentation from Terraform modules in various output formats.

Installation

macOS users can install using Homebrew:

brew install terraform-docs

or

brew install terraform-docs/tap/terraform-docs

Windows users can install using Scoop:

scoop bucket add terraform-docs https://github.com/terraform-docs/scoop-bucket
scoop install terraform-docs

or Chocolatey:

choco install terraform-docs

Stable binaries are also available on the releases page. To install, download the binary for your platform from "Assets" and place this into your $PATH:

curl -Lo ./terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.15.0/terraform-docs-v0.15.0-$(uname)-amd64.tar.gz
tar -xzf terraform-docs.tar.gz
chmod +x terraform-docs
mv terraform-docs /usr/local/terraform-docs

NOTE: Windows releases are in ZIP format.

The latest version can be installed using go install or go get:

# go1.17+
go install github.com/terraform-docs/terraform-docs@v0.15.0

# go1.16
GO111MODULE="on" go get github.com/terraform-docs/terraform-docs@v0.15.0

NOTE: please use the latest Go to do this, minimum go1.16 is required.

This will put terraform-docs in $(go env GOPATH)/bin. If you encounter the error terraform-docs: command not found after installation then you may need to either add that directory to your $PATH as shown here or do a manual installation by cloning the repo and run make build from the repository which will put terraform-docs in:

$(go env GOPATH)/src/github.com/terraform-docs/terraform-docs/bin/$(uname | tr '[:upper:]' '[:lower:]')-amd64/terraform-docs

Usage

Running the binary directly

To run and generate documentation into README within a directory:

terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module

Check output configuration for more details and examples.

Using docker

terraform-docs can be run as a container by mounting a directory with .tf files in it and run the following command:

docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.15.0 markdown /terraform-docs

If output.file is not enabled for this module, generated output can be redirected back to a file:

docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.15.0 markdown /terraform-docs > doc.md

NOTE: Docker tag latest refers to latest stable released version and edge refers to HEAD of master at any given point in time.

Using GitHub Actions

To use terraform-docs GitHub Action, configure a YAML workflow file (e.g. .github/workflows/documentation.yml) with the following:

name: Generate terraform docs
on:
  - pull_request

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        ref: ${{ github.event.pull_request.head.ref }}

    - name: Render terraform docs and push changes back to PR
      uses: terraform-docs/gh-actions@main
      with:
        working-dir: .
        output-file: README.md
        output-method: inject
        git-push: "true"

Read more about terraform-docs GitHub Action and its configuration and examples.

pre-commit hook

With pre-commit, you can ensure your Terraform module documentation is kept up-to-date each time you make a commit.

First install pre-commit and then create or update a .pre-commit-config.yaml in the root of your Git repo with at least the following content:

repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: "v0.15.0"
    hooks:
      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "README.md", "./mymodule/path"]

Then run:

pre-commit install
pre-commit install-hooks

Further changes to your module's .tf files will cause an update to documentation when you make a commit.

Configuration

terraform-docs can be configured with a yaml file. The default name of this file is .terraform-docs.yml and the path order for locating it 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/

formatter: "" # this is required

version: ""

header-from: main.tf
footer-from: ""

sections:
  hide: []
  show: []

content: ""

output:
  file: ""
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->

output-values:
  enabled: false
  from: ""

sort:
  enabled: true
  by: name

settings:
  anchor: true
  color: true
  default: true
  description: false
  escape: true
  hide-empty: false
  html: true
  indent: 2
  lockfile: true
  read-comments: true
  required: true
  sensitive: true
  type: true

Content Template

Generated content can be customized further away with content in configuration. If the content is empty the default order of sections is used.

Compatible formatters for customized content are asciidoc and markdown. content will be ignored for other formatters.

content is a Go template with following additional variables:

• {{ .Header }}
• {{ .Footer }}
• {{ .Inputs }}
• {{ .Modules }}
• {{ .Outputs }}
• {{ .Providers }}
• {{ .Requirements }}
• {{ .Resources }}

and following functions:

• {{ include "relative/path/to/file" }}

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.

Note that sections visibility (i.e. sections.show and sections.hide) takes precedence over the content.

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 }}

  include any relative files

  {{ include "relative/path/to/file" }}

  {{ .Inputs }}

  # Examples

  ```hcl
  {{ include "examples/foo/main.tf" }}
  ```

Documentation

• Users
  • Read the User Guide to learn how to use terraform-docs
  • Read the Formats Guide to learn about different output formats of terraform-docs
  • Refer to Config File Reference for all the available configuration options
• Developers
  • Read Contributing Guide before submitting a pull request

Visit our website for all documentation.

Community

• Discuss terraform-docs on Slack

License

MIT License - Copyright (c) 2021 The terraform-docs Authors.