terraform-docs/terraform-docsPublic

NotificationsYou must be signed in to change notification settings
Fork573
Star4.6k

Generate documentation from Terraform modules in various output formats

License

MIT license

4.6k stars 573 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 822 Commits
.github		.github
cmd		cmd
docs		docs
examples		examples
format		format
images		images
internal		internal
plugin		plugin
print		print
scripts		scripts
template		template
terraform		terraform
.editorconfig		.editorconfig
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
CONTRIBUTING.md		CONTRIBUTING.md
DCO		DCO
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
codecov.yml		codecov.yml
go.mod		go.mod
go.sum		go.sum
main.go		main.go
netlify.toml		netlify.toml

Repository files navigation

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

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-lateststeps:    -uses:actions/checkout@v3with:ref:${{ github.event.pull_request.head.ref }}    -name:Render terraform docs and push changes back to PRuses:terraform-docs/gh-actions@mainwith:working-dir:.output-file:README.mdoutput-method:injectgit-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-docsrev:"v0.20.0"hooks:      -id:terraform-docs-goargs:["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:

root of module directory
.config/ folder at root of module directory
current directory
.config/ folder at current directory
$HOME/.tfdocs.d/

formatter:""# this is requiredversion:""header-from:main.tffooter-from:""recursive:enabled:falsepath:modulesinclude-main:truesections:hide:[]show:[]content:""output:file:""mode:injecttemplate:|-    <!-- BEGIN_TF_DOCS -->    {{ .Content }}    <!-- END_TF_DOCS -->output-values:enabled:falsefrom:""sort:enabled:trueby:namesettings:anchor:truecolor:truedefault:truedescription:falseescape:truehide-empty:falsehtml:trueindent:2lockfile:trueread-comments:truerequired:truesensitive:truetype: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`.funcbuildTerraformDocs(pathstring,tmplstring) (string,error) {config:=print.DefaultConfig()config.ModuleRoot=path// module root path (can be relative or absolute)module,err:=terraform.LoadWithOptions(config)iferr!=nil {return"",err    }// Generate in Markdown Table formatformatter:=format.NewMarkdownTable(config)iferr:=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(), nilreturnformatter.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")funcmain() {plugin.Serve(&plugin.ServeOpts{Name:"<NAME>",Version:"0.1.0",Printer:printerFunc,    })}//go:embed sections.tmplvartplCustom []byte// printerFunc the function being executed by the plugin client.funcprinterFunc(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)iferr!=nil {return"",err    }returnrendered,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.