Skip to content

Commit 0ad14a3

Browse files
khos2owkhos2ow
committed
Restructure how-tos docs
Signed-off-by: Khosrow Moossavi <[email protected]>
1 parent 1ae5fd9 commit 0ad14a3

12 files changed

+415
-388
lines changed

‎docs/developer-guide/contributing.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ description: "terraform-docs contributing guide."
44
menu:
55
docs:
66
parent: "developer-guide"
7-
weight: 220
8-
toc: true
7+
weight: 320
8+
toc: false
99
---
1010

1111
Check [CONTRIBUTING.md](https://git.io/JtEzg) file on the root of our repository

‎docs/developer-guide/plugins.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ description: "terraform-docs plugin development guide."
44
menu:
55
docs:
66
parent: "developer-guide"
7-
weight: 210
8-
toc: true
7+
weight: 310
8+
toc: false
99
---
1010

1111
If you want to add or change formatter, you need to write plugins. When changing

‎docs/how-to/cli-flag-false-value.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: "CLI Flag 'false' value"
3+
description: "How to use pass 'false' value to terraform-docs CLI flags."
4+
menu:
5+
docs:
6+
parent: "how-to"
7+
weight: 201
8+
toc: false
9+
---
10+
11+
Boolean flags can only take arguments via `--flag=[true|false]` or for short names
12+
(if available) `-f=[true|false]`. You cannot use `--flag [true|false]` nor can you
13+
use the shorthand `-f [true|false]` as it will result in the following error:
14+
15+
```text
16+
Error: accepts 1 arg(s), received 2
17+
```
18+
19+
Example:
20+
21+
```bash
22+
# disable reading .terraform.lock.hcl
23+
$ terraform-docs markdown --lockfile=false /path/to/module
24+
```

‎docs/how-to/configuration-file.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: "Configuration File"
3+
description: "How to use terraform-docs configuration file."
4+
menu:
5+
docs:
6+
parent: "how-to"
7+
weight: 202
8+
toc: false
9+
---
10+
11+
Since `v0.10.0`
12+
13+
Configuration can be loaded with `-c, --config string`. Take a look at [configuration]
14+
page for all the details.
15+
16+
```bash
17+
$ pwd
18+
/path/to/parent/folder
19+
20+
$ tree
21+
.
22+
├── module-a
23+
│   └── main.tf
24+
├── module-b
25+
│   └── main.tf
26+
├── ...
27+
└── .terraform-docs.yml
28+
29+
# executing from parent
30+
$ terraform-docs -c .terraform-docs.yml module-a/
31+
32+
# executing from child
33+
$ cd module-a/
34+
$ terraform-docs -c ../.terraform-docs.yml .
35+
36+
# or an absolute path
37+
$ terraform-docs -c /path/to/parent/folder/.terraform-docs.yml .
38+
```
39+
40+
{{< alert type="info" >}}
41+
As of `v0.13.0`, `--config` flag accepts both relative and absolute paths.
42+
{{< /alert >}}
43+
44+
[configuration]: {{< ref "configuration" >}}

‎docs/how-to/generate-terraform-tfvars.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: "Generate terraform.tfvars"
3+
description: "How to generate terraform.tfvars file with terraform-docs."
4+
menu:
5+
docs:
6+
parent: "how-to"
7+
weight: 207
8+
toc: false
9+
---
10+
11+
Since `v0.9.0`
12+
13+
You can generate `terraform.tfvars` in both `hcl` and `json` format by executing
14+
the following, respectively:
15+
16+
```bash
17+
terraform-docs tfvars hcl /path/to/module
18+
19+
terraform-docs tfvars json /path/to/module
20+
```
21+
22+
{{< alert type="info" >}}
23+
Required input variables will be `""` (empty) in HCL and `null` in JSON format.
24+
{{< /alert >}}

‎docs/how-to/github-action.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: "GitHub Action"
3+
description: "How to use terraform-docs with GitHub Actions."
4+
menu:
5+
docs:
6+
parent: "how-to"
7+
weight: 208
8+
toc: false
9+
---
10+
11+
To use terraform-docs GitHub Action, configure a YAML workflow file (e.g.
12+
`.github/workflows/documentation.yml`) with the following:
13+
14+
```yaml
15+
name: Generate terraform docs
16+
on:
17+
- pull_request
18+
19+
jobs:
20+
docs:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@v2
24+
with:
25+
ref: ${{ github.event.pull_request.head.ref }}
26+
27+
- name: Render terraform docs and push changes back to PR
28+
uses: terraform-docs/gh-actions@main
29+
with:
30+
working-dir: .
31+
output-file: README.md
32+
output-method: inject
33+
git-push: "true"
34+
```
35+
36+
Read more about [terraform-docs GitHub Action] and its configuration and
37+
examples.
38+
39+
[terraform-docs GitHub Action]: https://github.com/terraform-docs/gh-actions

‎docs/how-to/include-examples.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: "Include Examples"
3+
description: "How to include example in terraform-docs generated output."
4+
menu:
5+
docs:
6+
parent: "how-to"
7+
weight: 205
8+
toc: false
9+
---
10+
11+
Since `v0.14.0`
12+
13+
Example can be automatically included into README by using `content` in configuration
14+
file. For example:
15+
16+
````bash
17+
$ tree
18+
.
19+
├── examples
20+
│   ├── example-1
21+
│   │   ├── main.tf
22+
│ └── example-2
23+
│ └── main.tf
24+
├── ...
25+
├── main.tf
26+
├── variables.tf
27+
├── ...
28+
└── .terraform-docs.yml
29+
````
30+
31+
and
32+
33+
````yaml
34+
# .terraform-docs.yml
35+
content: |-
36+
{{ .Header }}
37+
38+
## Example
39+
40+
```hcl
41+
{{ include "examples/example-1/main.tf" }}
42+
```
43+
44+
{{ .Inputs }}
45+
46+
{{ .Outputs }}
47+
````

‎docs/how-to/insert-output-to-file.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: "Insert Output To File"
3+
description: "How to insert generated terraform-docs output to file."
4+
menu:
5+
docs:
6+
parent: "how-to"
7+
weight: 204
8+
toc: false
9+
---
10+
11+
Since `v0.12.0`
12+
13+
Generated output can be insterted directly into the file. There are two modes of
14+
insersion: `inject` (default) or `replace`. Take a look at [output] configuration
15+
for all the details.
16+
17+
```bash
18+
terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module
19+
```
20+
21+
{{< alert type="info" >}}
22+
`--output-file` can be relative to module path or an absolute path in filesystem.
23+
{{< /alert>}}
24+
25+
```bash
26+
$ pwd
27+
/path/to/module
28+
29+
$ tree .
30+
.
31+
├── docs
32+
│   └── README.md
33+
├── ...
34+
└── main.tf
35+
36+
# this works, relative path
37+
$ terraform-docs markdown table --output-file ./docs/README.md .
38+
39+
# so does this, absolute path
40+
$ terraform-docs markdown table --output-file /path/to/module/docs/README.md .
41+
```
42+
43+
[output]: {{< ref "output" >}}

‎docs/how-to/pre-commit-hooks.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: "pre-commit Hooks"
3+
description: "How to use pre-commit hooks with terraform-docs."
4+
menu:
5+
docs:
6+
parent: "how-to"
7+
weight: 209
8+
toc: false
9+
---
10+
11+
Since `v0.12.0`
12+
13+
With [`pre-commit`], you can ensure your Terraform module documentation is kept
14+
up-to-date each time you make a commit.
15+
16+
1. simply create or update a `.pre-commit-config.yaml`
17+
in the root of your Git repo with at least the following content:
18+
19+
```yaml
20+
repos:
21+
- repo: https://github.com/terraform-docs/terraform-docs
22+
rev: "<VERSION, TAG, OR SHA TO USE>" # e.g. "v0.11.2"
23+
hooks:
24+
- id: terraform-docs-go
25+
args: ["ARGS", "TO PASS", "INCLUDING PATH"] # e.g. ["--output-file", "README.md", "./mymodule/path"]
26+
```
27+
28+
{{< alert type="info" >}}
29+
You can also include more than one entry under `hooks:` to update multiple docs.
30+
Just be sure to adjust the `args:` to pass the path you want terraform-docs to scan.
31+
{{< /alert >}}
32+
33+
1. install [`pre-commit`] and run `pre-commit` to activate the hooks.
34+
35+
1. make a Terraform change, `git add` and `git commit`.
36+
pre-commit will regenerate your Terraform docs, after which you can
37+
rerun `git add` and `git commit` to commit the code and doc changes together.
38+
39+
You can also regenerate the docs manually by running `pre-commit -a terraform-docs`.
40+
41+
### pre-commit via Docker
42+
43+
The pre-commit hook can also be run via Docker, for those who don't have Go installed.
44+
Just use `id: terraform-docs-docker` in the previous example.
45+
46+
This will build the Docker image from the repo, which can be quite slow.
47+
To download the pre-built image instead, change your `.pre-commit-config.yaml` to:
48+
49+
```yaml
50+
repos:
51+
- repo: local
52+
hooks:
53+
- id: terraform-docs
54+
name: terraform-docs
55+
language: docker_image
56+
entry: quay.io/terraform-docs/terraform-docs:latest # or, change latest to pin to a specific version
57+
args: ["ARGS", "TO PASS", "INCLUDING PATH"] # e.g. ["--output-file", "README.md", "./mymodule/path"]
58+
pass_filenames: false
59+
```
60+
61+
## Git Hook
62+
63+
A simple git hook (`.git/hooks/pre-commit`) added to your local terraform
64+
repository can keep your Terraform module documentation up to date whenever you
65+
make a commit. See also [git hooks] documentation.
66+
67+
```sh
68+
#!/bin/sh
69+
70+
# Keep module docs up to date
71+
for d in modules/*; do
72+
if terraform-docs md "$d" > "$d/README.md"; then
73+
git add "./$d/README.md"
74+
fi
75+
done
76+
```
77+
78+
{{< alert type="warning" >}}
79+
This is very basic and higly simplified version of [pre-commit-terraform](https://github.com/antonbabenko/pre-commit-terraform).
80+
Please refer to it for complete examples and guides.
81+
{{< /alert >}}
82+
83+
[`pre-commit`]: https://pre-commit.com/
84+
[git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

‎docs/how-to/recursive-submodules.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: "Recursive Submodules"
3+
description: "How to generate submodules documentation recursively with terraform-docs."
4+
menu:
5+
docs:
6+
parent: "how-to"
7+
weight: 206
8+
toc: false
9+
---
10+
11+
Since `v0.15.0`
12+
13+
Considering the file strucutre below of main module and its submodules, it is
14+
possible to generate documentation for them main and all its submodules in one
15+
execution, with `--recursive` flag.
16+
17+
{{< alert type="warning" >}}
18+
Generating documentation recursively is allowed only with `--output-file`
19+
set.
20+
{{< /alert >}}
21+
22+
Path to find submodules can be configured with `--recursive-path` (defaults to
23+
`modules`).
24+
25+
Each submodule can also have their own `.terraform-docs.yml` config file, to
26+
override configuration from root module.
27+
28+
```bash
29+
$ pwd
30+
/path/to/module
31+
32+
$ tree .
33+
.
34+
├── README.md
35+
├── main.tf
36+
├── modules
37+
│   └── my-sub-module
38+
│   ├── README.md
39+
│   ├── main.tf
40+
│   ├── variables.tf
41+
│   └── versions.tf
42+
├── outputs.tf
43+
├── variables.tf
44+
└── versions.tf
45+
```

0 commit comments

Comments
 (0)