terraform-docs

What is terraform-docs

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

Installation

macOS users can install usingHomebrew:

brew install terraform-docs

or

brew install terraform-docs/tap/terraform-docs

Windows users can install usingScoop:

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

orChocolatey:

choco install terraform-docs

Stable binaries are also available on thereleases page. To install, download thebinary 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.20.0/terraform-docs-v0.20.0-$(uname)-amd64.tar.gztar -xzf terraform-docs.tar.gzchmod +x terraform-docsmv terraform-docs /usr/local/bin/terraform-docs

NOTE: Windows releases are inZIP format.

The latest version can be installed usinggo install orgo get:

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

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

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

This will putterraform-docs in$(go env GOPATH)/bin. If you encounter the errorterraform-docs: command not found after installation then you may need to either addthat directory to your$PATH as shownhere or do a manual installation by cloningthe repo and runmake build from the repository which will putterraform-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

Checkoutput configuration for more details and examples.

Using docker

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

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

Ifoutput.file is not enabled for this module, generated output can be redirectedback to a file:

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

NOTE: Docker taglatest refers tolatest stable released version andedgerefers to HEAD ofmaster 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 docson:  - pull_requestjobs:  docs:    runs-on: ubuntu-latest    steps:    - uses: actions/checkout@v3      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 aboutterraform-docs GitHub Action and its configuration andexamples.

pre-commit hook

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

Firstinstall pre-commit and then create or update a.pre-commit-config.yamlin the root of your Git repo with at least the following content:

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

Then run:

pre-commit installpre-commit install-hooks

Further changes to your module's.tf files will cause an update to documentationwhen 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 requiredversion: ""header-from: main.tffooter-from: ""recursive:  enabled: false  path: modules  include-main: truesections:  hide: []  show: []content: ""output:  file: ""  mode: inject  template: |-    <!-- BEGIN_TF_DOCS -->    {{ .Content }}    <!-- END_TF_DOCS -->output-values:  enabled: false  from: ""sort:  enabled: true  by: namesettings:  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 withcontent in configuration.If thecontent is empty the default order of sections is used.

Compatible formatters for customized content areasciidoc andmarkdown.contentwill 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 selectedformatter. For example{{ .Inputs }} is Markdown Table representation ofinputswhen formatter is set tomarkdown table.

Note that sections visibility (i.e.sections.show andsections.hide) takesprecedence over thecontent.

Additionally there's also one extra special variable avaialble to thecontent:

• {{ .Module }}

As opposed to the other variables mentioned above, which are generated sectionsbased on a selected formatter, the{{ .Module }} variable is just astructrepresenting aTerraform module.

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" }}  ```  ## Resources  {{ range .Module.Resources }}  - {{ .GetMode }}.{{ .Spec }} ({{ .Position.Filename }}#{{ .Position.Line }})  {{- end }}

Build on top of terraform-docs

terraform-docs primary use-case is to be utilized as a standalone binary, butsome parts of it is also available publicly and can be imported in your projectas a library.

import (    "github.com/terraform-docs/terraform-docs/format"    "github.com/terraform-docs/terraform-docs/print"    "github.com/terraform-docs/terraform-docs/terraform")// buildTerraformDocs for module root `path` and provided content `tmpl`.func buildTerraformDocs(path string, tmpl string) (string, error) {    config := print.DefaultConfig()    config.ModuleRoot = path // module root path (can be relative or absolute)    module, err := terraform.LoadWithOptions(config)    if err != nil {        return "", err    }    // Generate in Markdown Table format    formatter := format.NewMarkdownTable(config)    if err := formatter.Generate(module); err != nil {        return "", err    }    // // Note: if you don't intend to provide additional template for the generated    // // content, or the target format doesn't provide templating (e.g. json, yaml,    // // xml, or toml) you can use `Content()` function instead of `Render()`.    // // `Content()` returns all the sections combined with predefined order.    // return formatter.Content(), nil    return formatter.Render(tmpl)}

Plugin

Generated output can be heavily customized withcontent, but if using thatis not enough for your use-case, you can write your own plugin.

In order to install a plugin the following steps are needed:

• download the plugin and place it in~/.tfdocs.d/plugins (or./.tfdocs.d/plugins)
• make sure the plugin file name istfdocs-format-<NAME>
• modifyformatter of.terraform-docs.yml file to be<NAME>

Important notes:

• if the plugin file name is different than the example above, terraform-docs won'tbe able to to pick it up nor register it properly
• you can only use plugin thorough.terraform-docs.yml file and it cannot be usedwith CLI arguments

To create a new plugin create a new repository calledtfdocs-format-<NAME> withfollowingmain.go:

package mainimport (    _ "embed" //nolint    "github.com/terraform-docs/terraform-docs/plugin"    "github.com/terraform-docs/terraform-docs/print"    "github.com/terraform-docs/terraform-docs/template"    "github.com/terraform-docs/terraform-docs/terraform")func main() {    plugin.Serve(&plugin.ServeOpts{        Name:    "<NAME>",        Version: "0.1.0",        Printer: printerFunc,    })}//go:embed sections.tmplvar tplCustom []byte// printerFunc the function being executed by the plugin client.func printerFunc(config *print.Config, module *terraform.Module) (string, error) {    tpl := template.New(config,        &template.Item{Name: "custom", Text: string(tplCustom)},    )    rendered, err := tpl.Render("custom", module)    if err != nil {        return "", err    }    return rendered, nil}

Please refer totfdocs-format-template for more details. You can create a newrepository from it by clicking onUse this template button.

Documentation

• Users
  • Read theUser Guide to learn how to use terraform-docs
  • Read theFormats Guide to learn about different output formats of terraform-docs
  • Refer toConfig File Reference for all the available configuration options
• Developers
  • ReadContributing Guide before submitting a pull request

Visitour website for all documentation.

Community

• Discuss terraform-docs onSlack

License

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

There is no documentation for this package.