|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | 03-May-2022 | - |
| .github/ | H | 05-Oct-2021 | - | 429 | 321 |
| cmd/ | H | 05-Oct-2021 | - | 767 | 438 |
| docs/ | H | 05-Oct-2021 | - | 5,896 | 4,661 |
| examples/ | H | 03-May-2022 | - | 437 | 314 |
| format/ | H | 05-Oct-2021 | - | 19,653 | 14,953 |
| images/ | H | 03-May-2022 | - | | |
| internal/ | H | 05-Oct-2021 | - | 3,661 | 2,715 |
| plugin/ | H | 05-Oct-2021 | - | 304 | 136 |
| print/ | H | 05-Oct-2021 | - | 1,347 | 1,115 |
| scripts/ | H | 05-Oct-2021 | - | 497 | 355 |
| template/ | H | 05-Oct-2021 | - | 2,280 | 1,875 |
| terraform/ | H | 05-Oct-2021 | - | 3,916 | 3,266 |
| vendor/ | H | 03-May-2022 | - | 4,174,494 | 3,397,462 |
| .editorconfig | H A D | 05-Oct-2021 | 740 | 45 | 33 |
| .gitignore | H A D | 05-Oct-2021 | 491 | 38 | 28 |
| .golangci.yml | H A D | 05-Oct-2021 | 4.5 KiB | 150 | 122 |
| .goreleaser.yml | H A D | 05-Oct-2021 | 2.1 KiB | 84 | 74 |
| .pre-commit-hooks.yaml | H A D | 05-Oct-2021 | 969 | 32 | 29 |
| CONTRIBUTING.md | H A D | 05-Oct-2021 | 4.5 KiB | 96 | 76 |
| DCO | H A D | 05-Oct-2021 | 1.4 KiB | 37 | 27 |
| Dockerfile | H A D | 05-Oct-2021 | 612 | 29 | 19 |
| LICENSE | H A D | 05-Oct-2021 | 1.1 KiB | 22 | 17 |
| Makefile | H A D | 05-Oct-2021 | 5.3 KiB | 192 | 124 |
| README.md | H A D | 05-Oct-2021 | 12.5 KiB | 436 | 316 |
| codecov.yml | H A D | 05-Oct-2021 | 438 | 23 | 22 |
| go.mod | H A D | 05-Oct-2021 | 737 | 24 | 21 |
| go.sum | H A D | 05-Oct-2021 | 67 KiB | 698 | 697 |
| main.go | H A D | 05-Oct-2021 | 417 | 24 | 10 |
| netlify.toml | H A D | 05-Oct-2021 | 279 | 16 | 13 |
README.md
1# terraform-docs
2
3[![Build Status](https://github.com/terraform-docs/terraform-docs/workflows/ci/badge.svg)](https://github.com/terraform-docs/terraform-docs/actions) [![GoDoc](https://pkg.go.dev/badge/github.com/terraform-docs/terraform-docs)](https://pkg.go.dev/github.com/terraform-docs/terraform-docs) [![Go Report Card](https://goreportcard.com/badge/github.com/terraform-docs/terraform-docs)](https://goreportcard.com/report/github.com/terraform-docs/terraform-docs) [![Codecov Report](https://codecov.io/gh/terraform-docs/terraform-docs/branch/master/graph/badge.svg)](https://codecov.io/gh/terraform-docs/terraform-docs) [![License](https://img.shields.io/github/license/terraform-docs/terraform-docs)](https://github.com/terraform-docs/terraform-docs/blob/master/LICENSE) [![Latest release](https://img.shields.io/github/v/release/terraform-docs/terraform-docs)](https://github.com/terraform-docs/terraform-docs/releases)
4
5![terraform-docs-teaser](./images/terraform-docs-teaser.png)
6
7Sponsored by [Scalr - Terraform Automation & Collaboration Software](https://scalr.com/?utm_source=terraform-docs)
8
9<a href="https://www.scalr.com/?utm_source=terraform-docs" target="_blank"><img src="https://bit.ly/2T7Qm3U" alt="Scalr - Terraform Automation & Collaboration Software" width="175" height="40" /></a>
10
11## What is terraform-docs
12
13A utility to generate documentation from Terraform modules in various output formats.
14
15## Installation
16
17macOS users can install using [Homebrew]:
18
19```bash
20brew install terraform-docs
21```
22
23or
24
25```bash
26brew install terraform-docs/tap/terraform-docs
27```
28
29Windows users can install using [Scoop]:
30
31```bash
32scoop bucket add terraform-docs https://github.com/terraform-docs/scoop-bucket
33scoop install terraform-docs
34```
35
36or [Chocolatey]:
37
38```bash
39choco install terraform-docs
40```
41
42Stable binaries are also available on the [releases] page. To install, download the
43binary for your platform from "Assets" and place this into your `$PATH`:
44
45```bash
46curl -Lo ./terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.16.0/terraform-docs-v0.16.0-$(uname)-amd64.tar.gz
47tar -xzf terraform-docs.tar.gz
48chmod +x terraform-docs
49mv terraform-docs /usr/local/terraform-docs
50```
51
52**NOTE:** Windows releases are in `ZIP` format.
53
54The latest version can be installed using `go install` or `go get`:
55
56```bash
57# go1.17+
58go install github.com/terraform-docs/terraform-docs@v0.16.0
59```
60
61```bash
62# go1.16
63GO111MODULE="on" go get github.com/terraform-docs/terraform-docs@v0.16.0
64```
65
66**NOTE:** please use the latest Go to do this, minimum `go1.16` is required.
67
68This will put `terraform-docs` in `$(go env GOPATH)/bin`. If you encounter the error
69`terraform-docs: command not found` after installation then you may need to either add
70that directory to your `$PATH` as shown [here] or do a manual installation by cloning
71the repo and run `make build` from the repository which will put `terraform-docs` in:
72
73```bash
74$(go env GOPATH)/src/github.com/terraform-docs/terraform-docs/bin/$(uname | tr '[:upper:]' '[:lower:]')-amd64/terraform-docs
75```
76
77## Usage
78
79### Running the binary directly
80
81To run and generate documentation into README within a directory:
82
83```bash
84terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module
85```
86
87Check [`output`] configuration for more details and examples.
88
89### Using docker
90
91terraform-docs can be run as a container by mounting a directory with `.tf`
92files in it and run the following command:
93
94```bash
95docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.16.0 markdown /terraform-docs
96```
97
98If `output.file` is not enabled for this module, generated output can be redirected
99back to a file:
100
101```bash
102docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.16.0 markdown /terraform-docs > doc.md
103```
104
105**NOTE:** Docker tag `latest` refers to _latest_ stable released version and `edge`
106refers to HEAD of `master` at any given point in time.
107
108### Using GitHub Actions
109
110To use terraform-docs GitHub Action, configure a YAML workflow file (e.g.
111`.github/workflows/documentation.yml`) with the following:
112
113```yaml
114name: Generate terraform docs
115on:
116 - pull_request
117
118jobs:
119 docs:
120 runs-on: ubuntu-latest
121 steps:
122 - uses: actions/checkout@v2
123 with:
124 ref: ${{ github.event.pull_request.head.ref }}
125
126 - name: Render terraform docs and push changes back to PR
127 uses: terraform-docs/gh-actions@main
128 with:
129 working-dir: .
130 output-file: README.md
131 output-method: inject
132 git-push: "true"
133```
134
135Read more about [terraform-docs GitHub Action] and its configuration and
136examples.
137
138### pre-commit hook
139
140With pre-commit, you can ensure your Terraform module documentation is kept
141up-to-date each time you make a commit.
142
143First [install pre-commit] and then create or update a `.pre-commit-config.yaml`
144in the root of your Git repo with at least the following content:
145
146```yaml
147repos:
148 - repo: https://github.com/terraform-docs/terraform-docs
149 rev: "v0.16.0"
150 hooks:
151 - id: terraform-docs-go
152 args: ["markdown", "table", "--output-file", "README.md", "./mymodule/path"]
153```
154
155Then run:
156
157```bash
158pre-commit install
159pre-commit install-hooks
160```
161
162Further changes to your module's `.tf` files will cause an update to documentation
163when you make a commit.
164
165## Configuration
166
167terraform-docs can be configured with a yaml file. The default name of this file is
168`.terraform-docs.yml` and the path order for locating it is:
169
1701. root of module directory
1711. `.config/` folder at root of module directory
1721. current directory
1731. `.config/` folder at current directory
1741. `$HOME/.tfdocs.d/`
175
176```yaml
177formatter: "" # this is required
178
179version: ""
180
181header-from: main.tf
182footer-from: ""
183
184recursive:
185 enabled: false
186 path: modules
187
188sections:
189 hide: []
190 show: []
191
192content: ""
193
194output:
195 file: ""
196 mode: inject
197 template: |-
198 <!-- BEGIN_TF_DOCS -->
199 {{ .Content }}
200 <!-- END_TF_DOCS -->
201
202output-values:
203 enabled: false
204 from: ""
205
206sort:
207 enabled: true
208 by: name
209
210settings:
211 anchor: true
212 color: true
213 default: true
214 description: false
215 escape: true
216 hide-empty: false
217 html: true
218 indent: 2
219 lockfile: true
220 read-comments: true
221 required: true
222 sensitive: true
223 type: true
224```
225
226## Content Template
227
228Generated content can be customized further away with `content` in configuration.
229If the `content` is empty the default order of sections is used.
230
231Compatible formatters for customized content are `asciidoc` and `markdown`. `content`
232will be ignored for other formatters.
233
234`content` is a Go template with following additional variables:
235
236- `{{ .Header }}`
237- `{{ .Footer }}`
238- `{{ .Inputs }}`
239- `{{ .Modules }}`
240- `{{ .Outputs }}`
241- `{{ .Providers }}`
242- `{{ .Requirements }}`
243- `{{ .Resources }}`
244
245and following functions:
246
247- `{{ include "relative/path/to/file" }}`
248
249These variables are the generated output of individual sections in the selected
250formatter. For example `{{ .Inputs }}` is Markdown Table representation of _inputs_
251when formatter is set to `markdown table`.
252
253Note that sections visibility (i.e. `sections.show` and `sections.hide`) takes
254precedence over the `content`.
255
256Additionally there's also one extra special variable avaialble to the `content`:
257
258- `{{ .Module }}`
259
260As opposed to the other variables mentioned above, which are generated sections
261based on a selected formatter, the `{{ .Module }}` variable is just a `struct`
262representing a [Terraform module].
263
264````yaml
265content: |-
266 Any arbitrary text can be placed anywhere in the content
267
268 {{ .Header }}
269
270 and even in between sections
271
272 {{ .Providers }}
273
274 and they don't even need to be in the default order
275
276 {{ .Outputs }}
277
278 include any relative files
279
280 {{ include "relative/path/to/file" }}
281
282 {{ .Inputs }}
283
284 # Examples
285
286 ```hcl
287 {{ include "examples/foo/main.tf" }}
288 ```
289
290 ## Resources
291
292 {{ range .Module.Resources }}
293 - {{ .GetMode }}.{{ .Spec }} ({{ .Position.Filename }}#{{ .Position.Line }})
294 {{- end }}
295````
296
297## Build on top of terraform-docs
298
299terraform-docs primary use-case is to be utilized as a standalone binary, but
300some parts of it is also available publicly and can be imported in your project
301as a library.
302
303```go
304import (
305 "github.com/terraform-docs/terraform-docs/format"
306 "github.com/terraform-docs/terraform-docs/print"
307 "github.com/terraform-docs/terraform-docs/terraform"
308)
309
310// buildTerraformDocs for module root `path` and provided content `tmpl`.
311func buildTerraformDocs(path string, tmpl string) (string, error) {
312 config := print.DefaultConfig()
313 config.ModuleRoot = path // module root path (can be relative or absolute)
314
315 module, err := terraform.LoadWithOptions(config)
316 if err != nil {
317 return "", err
318 }
319
320 // Generate in Markdown Table format
321 formatter := format.NewMarkdownTable(config)
322
323 if err := formatter.Generate(module); err != nil {
324 return "", err
325 }
326
327 // // Note: if you don't intend to provide additional template for the generated
328 // // content, or the target format doesn't provide templating (e.g. json, yaml,
329 // // xml, or toml) you can use `Content()` function instead of `Render()`.
330 // // `Content()` returns all the sections combined with predefined order.
331 // return formatter.Content(), nil
332
333 return formatter.Render(tmpl)
334}
335```
336
337## Plugin
338
339Generated output can be heavily customized with [`content`], but if using that
340is not enough for your use-case, you can write your own plugin.
341
342In order to install a plugin the following steps are needed:
343
344- download the plugin and place it in `~/.tfdocs.d/plugins` (or `./.tfdocs.d/plugins`)
345- make sure the plugin file name is `tfdocs-format-<NAME>`
346- modify [`formatter`] of `.terraform-docs.yml` file to be `<NAME>`
347
348**Important notes:**
349
350- if the plugin file name is different than the example above, terraform-docs won't
351be able to to pick it up nor register it properly
352- you can only use plugin thorough `.terraform-docs.yml` file and it cannot be used
353with CLI arguments
354
355To create a new plugin create a new repository called `tfdocs-format-<NAME>` with
356following `main.go`:
357
358```go
359package main
360
361import (
362 _ "embed" //nolint
363
364 "github.com/terraform-docs/terraform-docs/plugin"
365 "github.com/terraform-docs/terraform-docs/print"
366 "github.com/terraform-docs/terraform-docs/template"
367 "github.com/terraform-docs/terraform-docs/terraform"
368)
369
370func main() {
371 plugin.Serve(&plugin.ServeOpts{
372 Name: "<NAME>",
373 Version: "0.1.0",
374 Printer: printerFunc,
375 })
376}
377
378//go:embed sections.tmpl
379var tplCustom []byte
380
381// printerFunc the function being executed by the plugin client.
382func printerFunc(config *print.Config, module *terraform.Module) (string, error) {
383 tpl := template.New(config,
384 &template.Item{Name: "custom", Text: string(tplCustom)},
385 )
386
387 rendered, err := tpl.Render("custom", module)
388 if err != nil {
389 return "", err
390 }
391
392 return rendered, nil
393}
394```
395
396Please refer to [tfdocs-format-template] for more details. You can create a new
397repository from it by clicking on `Use this template` button.
398
399## Documentation
400
401- **Users**
402 - Read the [User Guide] to learn how to use terraform-docs
403 - Read the [Formats Guide] to learn about different output formats of terraform-docs
404 - Refer to [Config File Reference] for all the available configuration options
405- **Developers**
406 - Read [Contributing Guide] before submitting a pull request
407
408Visit [our website] for all documentation.
409
410## Community
411
412- Discuss terraform-docs on [Slack]
413
414## License
415
416MIT License - Copyright (c) 2021 The terraform-docs Authors.
417
418[Chocolatey]: https://www.chocolatey.org
419[Config File Reference]: https://terraform-docs.io/user-guide/configuration/
420[`content`]: https://terraform-docs.io/user-guide/configuration/content/
421[Contributing Guide]: CONTRIBUTING.md
422[Formats Guide]: https://terraform-docs.io/reference/terraform-docs/
423[`formatter`]: https://terraform-docs.io/user-guide/configuration/formatter/
424[here]: https://golang.org/doc/code.html#GOPATH
425[Homebrew]: https://brew.sh
426[install pre-commit]: https://pre-commit.com/#install
427[`output`]: https://terraform-docs.io/user-guide/configuration/output/
428[releases]: https://github.com/terraform-docs/terraform-docs/releases
429[Scoop]: https://scoop.sh/
430[Slack]: https://slack.terraform-docs.io/
431[terraform-docs GitHub Action]: https://github.com/terraform-docs/gh-actions
432[Terraform module]: https://pkg.go.dev/github.com/terraform-docs/terraform-docs/terraform#Module
433[tfdocs-format-template]: https://github.com/terraform-docs/tfdocs-format-template
434[our website]: https://terraform-docs.io/
435[User Guide]: https://terraform-docs.io/user-guide/introduction/
436