terraform-docs/README.

md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

terraform-docs / terraform-docs Public

Code Issues 58 Pull requests 6 Discussions Actions

master terraform-docs / README.md Go to file

khos2ow Release versio… … Latest commit 1f686b1 on Oct 6, 2021 History

16 contributors +4

435 lines (316 sloc) 12.5 KB Raw Blame

terraform-docs
ci passing go report A+ codecov 80% license MIT

release v0.16.0

Sponsored by Scalr - Terraform Automation & Collaboration Software

What is terraform-docs

A utility to generate documentation from Terraform modules in various

output formats.

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 1 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

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

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

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

# go1.16

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 2 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

GO111MODULE="on" go get github.com/terraform-docs/terraform-docs@v0.16.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/

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 /

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/terraf

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/terraf

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

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 3 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

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.16.0"
hooks:
- id: terraform-docs-go
args: ["markdown", "table", "--output-file", "README.md", "./mymodul

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 4 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

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

recursive:
enabled: false
path: modules

sections:
hide: []
show: []

content: ""

output:
file: ""
mode: inject

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 5 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

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

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 6 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

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

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

{{ .Module }}

As opposed to the other variables mentioned above, which are generated

sections based on a selected formatter, the {{ .Module }} variable is just
a struct representing a Terraform 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 }}

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 7 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

# 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,
but some parts of it is also available publicly and can be imported in your
project as 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 absolut

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
}

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 8 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

// // Note: if you don't intend to provide additional template for the g

// // content, or the target format doesn't provide templating (e.g. jso
// // xml, or toml) you can use `Content()` function instead of `Render(
// // `Content()` returns all the sections combined with predefined orde
// return formatter.Content(), nil

return formatter.Render(tmpl)
}

Plugin

Generated output can be heavily customized with content , but if using

that is 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 is tfdocs-format-<NAME>

modify formatter of .terraform-docs.yml file to be <NAME>

Important notes:

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

To create a new plugin create a new repository called tfdocs-format-

<NAME> with following main.go :

package main

import (
_ "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"
)

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 9 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

func main() {
plugin.Serve(&plugin.ServeOpts{
Name: "<NAME>",
Version: "0.1.0",
Printer: printerFunc,
})
}

//go:embed sections.tmpl
var tplCustom []byte

// printerFunc the function being executed by the plugin client.

func printerFunc(config *print.Config, module *terraform.Module) (
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 to tfdocs-format-template for more details. You can create a

new repository from it by clicking on Use this template button.

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.

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 10 of 11
terraform-docs/README.md at master · terraform-docs/terraform-docs · GitHub 12/04/22, 8:24 PM

Community
Discuss terraform-docs on Slack

License

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

https://github.com/terraform-docs/terraform-docs/blob/master/README.md Page 11 of 11