Restructure how-tos docs

khos2ow · khos2ow · commit 0ad14a31202a · 2021-09-13T18:07:46.000-04:00
Signed-off-by: Khosrow Moossavi &lt;khos2ow@gmail.com&gt;
diff --git a/docs/developer-guide/contributing.md b/docs/developer-guide/contributing.md
@@ -4,8 +4,8 @@ description: "terraform-docs contributing guide."
 menu:
   docs:
     parent: "developer-guide"
-weight: 220
-toc: true
+weight: 320
+toc: false
 ---
 
 Check [CONTRIBUTING.md](https://git.io/JtEzg) file on the root of our repository
diff --git a/docs/developer-guide/plugins.md b/docs/developer-guide/plugins.md
@@ -4,8 +4,8 @@ description: "terraform-docs plugin development guide."
 menu:
   docs:
     parent: "developer-guide"
-weight: 210
-toc: true
+weight: 310
+toc: false
 ---
 
 If you want to add or change formatter, you need to write plugins. When changing
diff --git a/docs/how-to/cli-flag-false-value.md b/docs/how-to/cli-flag-false-value.md
@@ -0,0 +1,24 @@
+---
+title: "CLI Flag 'false' value"
+description: "How to use pass 'false' value to terraform-docs CLI flags."
+menu:
+  docs:
+    parent: "how-to"
+weight: 201
+toc: false
+---
+
+Boolean flags can only take arguments via `--flag=[true|false]` or for short names
+(if available) `-f=[true|false]`. You cannot use `--flag [true|false]` nor can you
+use the shorthand `-f [true|false]` as it will result in the following error:
+
+```text
+Error: accepts 1 arg(s), received 2
+```
+
+Example:
+
+```bash
+# disable reading .terraform.lock.hcl
+$ terraform-docs markdown --lockfile=false /path/to/module
+```
diff --git a/docs/how-to/configuration-file.md b/docs/how-to/configuration-file.md
@@ -0,0 +1,44 @@
+---
+title: "Configuration File"
+description: "How to use terraform-docs configuration file."
+menu:
+  docs:
+    parent: "how-to"
+weight: 202
+toc: false
+---
+
+Since `v0.10.0`
+
+Configuration can be loaded with `-c, --config string`. Take a look at [configuration]
+page for all the details.
+
+```bash
+$ pwd
+/path/to/parent/folder
+
+$ tree
+.
+├── module-a
+│   └── main.tf
+├── module-b
+│   └── main.tf
+├── ...
+└── .terraform-docs.yml
+
+# executing from parent
+$ terraform-docs -c .terraform-docs.yml module-a/
+
+# executing from child
+$ cd module-a/
+$ terraform-docs -c ../.terraform-docs.yml .
+
+# or an absolute path
+$ terraform-docs -c /path/to/parent/folder/.terraform-docs.yml .
+```
+
+{{< alert type="info" >}}
+As of `v0.13.0`, `--config` flag accepts both relative and absolute paths.
+{{< /alert >}}
+
+[configuration]: {{< ref "configuration" >}}
diff --git a/docs/how-to/generate-terraform-tfvars.md b/docs/how-to/generate-terraform-tfvars.md
@@ -0,0 +1,24 @@
+---
+title: "Generate terraform.tfvars"
+description: "How to generate terraform.tfvars file with terraform-docs."
+menu:
+  docs:
+    parent: "how-to"
+weight: 207
+toc: false
+---
+
+Since `v0.9.0`
+
+You can generate `terraform.tfvars` in both `hcl` and `json` format by executing
+the following, respectively:
+
+```bash
+terraform-docs tfvars hcl /path/to/module
+
+terraform-docs tfvars json /path/to/module
+```
+
+{{< alert type="info" >}}
+Required input variables will be `""` (empty) in HCL and `null` in JSON format.
+{{< /alert >}}
diff --git a/docs/how-to/github-action.md b/docs/how-to/github-action.md
@@ -0,0 +1,39 @@
+---
+title: "GitHub Action"
+description: "How to use terraform-docs with GitHub Actions."
+menu:
+  docs:
+    parent: "how-to"
+weight: 208
+toc: false
+---
+
+To use terraform-docs GitHub Action, configure a YAML workflow file (e.g.
+`.github/workflows/documentation.yml`) with the following:
+
+```yaml
+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.
+
+[terraform-docs GitHub Action]: https://github.com/terraform-docs/gh-actions
diff --git a/docs/how-to/include-examples.md b/docs/how-to/include-examples.md
@@ -0,0 +1,47 @@
+---
+title: "Include Examples"
+description: "How to include example in terraform-docs generated output."
+menu:
+  docs:
+    parent: "how-to"
+weight: 205
+toc: false
+---
+
+Since `v0.14.0`
+
+Example can be automatically included into README by using `content` in configuration
+file. For example:
+
+````bash
+$ tree
+.
+├── examples
+│   ├── example-1
+│   │   ├── main.tf
+│   └── example-2
+│       └── main.tf
+├── ...
+├── main.tf
+├── variables.tf
+├── ...
+└── .terraform-docs.yml
+````
+
+and
+
+````yaml
+# .terraform-docs.yml
+content: |-
+  {{ .Header }}
+
+  ## Example
+
+  ```hcl
+  {{ include "examples/example-1/main.tf" }}
+  ```
+
+  {{ .Inputs }}
+
+  {{ .Outputs }}
+````
diff --git a/docs/how-to/insert-output-to-file.md b/docs/how-to/insert-output-to-file.md
@@ -0,0 +1,43 @@
+---
+title: "Insert Output To File"
+description: "How to insert generated terraform-docs output to file."
+menu:
+  docs:
+    parent: "how-to"
+weight: 204
+toc: false
+---
+
+Since `v0.12.0`
+
+Generated output can be insterted directly into the file. There are two modes of
+insersion: `inject` (default) or `replace`. Take a look at [output] configuration
+for all the details.
+
+```bash
+terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module
+```
+
+{{< alert type="info" >}}
+`--output-file` can be relative to module path or an absolute path in filesystem.
+{{< /alert>}}
+
+```bash
+$ pwd
+/path/to/module
+
+$ tree .
+.
+├── docs
+│   └── README.md
+├── ...
+└── main.tf
+
+# this works, relative path
+$ terraform-docs markdown table --output-file ./docs/README.md .
+
+# so does this, absolute path
+$ terraform-docs markdown table --output-file /path/to/module/docs/README.md .
+```
+
+[output]: {{< ref "output" >}}
diff --git a/docs/how-to/pre-commit-hooks.md b/docs/how-to/pre-commit-hooks.md
@@ -0,0 +1,84 @@
+---
+title: "pre-commit Hooks"
+description: "How to use pre-commit hooks with terraform-docs."
+menu:
+  docs:
+    parent: "how-to"
+weight: 209
+toc: false
+---
+
+Since `v0.12.0`
+
+With [`pre-commit`], you can ensure your Terraform module documentation is kept
+up-to-date each time you make a commit.
+
+1. simply create or update a `.pre-commit-config.yaml`
+in the root of your Git repo with at least the following content:
+
+   ```yaml
+   repos:
+     - repo: https://github.com/terraform-docs/terraform-docs
+       rev: "<VERSION, TAG, OR SHA TO USE>"             # e.g. "v0.11.2"
+       hooks:
+         - id: terraform-docs-go
+           args: ["ARGS", "TO PASS", "INCLUDING PATH"]  # e.g. ["--output-file", "README.md", "./mymodule/path"]
+   ```
+
+   {{< alert type="info" >}}
+   You can also include more than one entry under `hooks:` to update multiple docs.
+   Just be sure to adjust the `args:` to pass the path you want terraform-docs to scan.
+   {{< /alert >}}
+
+1. install [`pre-commit`] and run `pre-commit` to activate the hooks.
+
+1. make a Terraform change, `git add` and `git commit`.
+pre-commit will regenerate your Terraform docs, after which you can
+rerun `git add` and `git commit` to commit the code and doc changes together.
+
+You can also regenerate the docs manually by running `pre-commit -a terraform-docs`.
+
+### pre-commit via Docker
+
+The pre-commit hook can also be run via Docker, for those who don't have Go installed.
+Just use `id: terraform-docs-docker` in the previous example.
+
+This will build the Docker image from the repo, which can be quite slow.
+To download the pre-built image instead, change your `.pre-commit-config.yaml` to:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: terraform-docs
+        name: terraform-docs
+        language: docker_image
+        entry: quay.io/terraform-docs/terraform-docs:latest  # or, change latest to pin to a specific version
+        args: ["ARGS", "TO PASS", "INCLUDING PATH"]          # e.g. ["--output-file", "README.md", "./mymodule/path"]
+        pass_filenames: false
+```
+
+## Git Hook
+
+A simple git hook (`.git/hooks/pre-commit`) added to your local terraform
+repository can keep your Terraform module documentation up to date whenever you
+make a commit. See also [git hooks] documentation.
+
+```sh
+#!/bin/sh
+
+# Keep module docs up to date
+for d in modules/*; do
+  if terraform-docs md "$d" > "$d/README.md"; then
+    git add "./$d/README.md"
+  fi
+done
+```
+
+{{< alert type="warning" >}}
+This is very basic and higly simplified version of [pre-commit-terraform](https://github.com/antonbabenko/pre-commit-terraform).
+Please refer to it for complete examples and guides.
+{{< /alert >}}
+
+[`pre-commit`]: https://pre-commit.com/
+[git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks
diff --git a/docs/how-to/recursive-submodules.md b/docs/how-to/recursive-submodules.md
@@ -0,0 +1,45 @@
+---
+title: "Recursive Submodules"
+description: "How to generate submodules documentation recursively with terraform-docs."
+menu:
+  docs:
+    parent: "how-to"
+weight: 206
+toc: false
+---
+
+Since `v0.15.0`
+
+Considering the file strucutre below of main module and its submodules, it is
+possible to generate documentation for them main and all its submodules in one
+execution, with `--recursive` flag.
+
+{{< alert type="warning" >}}
+Generating documentation recursively is allowed only with `--output-file`
+set.
+{{< /alert >}}
+
+Path to find submodules can be configured with `--recursive-path` (defaults to
+`modules`).
+
+Each submodule can also have their own `.terraform-docs.yml` config file, to
+override configuration from root module.
+
+```bash
+$ pwd
+/path/to/module
+
+$ tree .
+.
+├── README.md
+├── main.tf
+├── modules
+│   └── my-sub-module
+│       ├── README.md
+│       ├── main.tf
+│       ├── variables.tf
+│       └── versions.tf
+├── outputs.tf
+├── variables.tf
+└── versions.tf
+```
diff --git a/docs/how-to/visibility-of-sections.md b/docs/how-to/visibility-of-sections.md
diff --git a/docs/user-guide/how-to.md b/docs/user-guide/how-to.md
