Overhaul README and docs improvements

khos2ow · khos2ow · commit 3d2b8788d6fc · 2021-09-16T13:49:38.000-04:00
Signed-off-by: Khosrow Moossavi &lt;khos2ow@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -12,42 +12,31 @@ Sponsored by [Scalr - Terraform Automation & Collaboration Software](https://sca
 
 A utility to generate documentation from Terraform modules in various output formats.
 
-## 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.
-
 ## Installation
 
-The latest version can be installed using `go get`:
+macOS users can install using [Homebrew]:
 
 ```bash
-GO111MODULE="on" go get github.com/terraform-docs/terraform-docs@v0.15.0
+brew install terraform-docs
 ```
 
-**NOTE:** to download any version **before** `v0.9.1` (inclusive) you need to use to
-old module namespace (`segmentio`):
+or
 
 ```bash
-# only for v0.9.1 and before
-GO111MODULE="on" go get github.com/segmentio/terraform-docs@v0.9.1
+brew install terraform-docs/tap/terraform-docs
 ```
 
-**NOTE:** please use the latest Go to do this, minimum `go1.16` or greater.
+Windows users can install using [Scoop]:
 
-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:
+```bash
+scoop bucket add terraform-docs https://github.com/terraform-docs/scoop-bucket
+scoop install terraform-docs
+```
+
+or [Chocolatey]:
 
 ```bash
-$(go env GOPATH)/src/github.com/terraform-docs/terraform-docs/bin/$(uname | tr '[:upper:]' '[:lower:]')-amd64/terraform-docs
+choco install terraform-docs
 ```
 
 Stable binaries are also available on the [releases] page. To install, download the
@@ -57,45 +46,246 @@ binary 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.15.0/terraform-docs-v0.15.0-$(uname)-amd64.tar.gz
 tar -xzf terraform-docs.tar.gz
 chmod +x terraform-docs
-mv terraform-docs /some-dir-in-your-PATH/terraform-docs
+mv terraform-docs /usr/local/terraform-docs
 ```
 
 **NOTE:** Windows releases are in `ZIP` format.
 
-If you are a Mac OS X user, you can use [Homebrew]:
+The latest version can be installed using `go install` or `go get`:
 
 ```bash
-brew install terraform-docs
+# go1.17+
+go install github.com/terraform-docs/terraform-docs@v0.15.0
 ```
 
-or
+```bash
+# go1.16
+GO111MODULE="on" go get github.com/terraform-docs/terraform-docs@v0.15.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:
 
 ```bash
-brew install terraform-docs/tap/terraform-docs
+$(go env GOPATH)/src/github.com/terraform-docs/terraform-docs/bin/$(uname | tr '[:upper:]' '[:lower:]')-amd64/terraform-docs
 ```
 
-Windows users can install using [Scoop]:
+## Usage
+
+### Running the binary directly
+
+To run and generate documentation into README within a directory:
 
 ```bash
-scoop bucket add terraform-docs https://github.com/terraform-docs/scoop-bucket
-scoop install terraform-docs
+terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module
 ```
 
-or [Chocolatey]:
+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:
 
 ```bash
-choco install terraform-docs
+docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.15.0 markdown /terraform-docs
 ```
 
-Alternatively you also can run `terraform-docs` as a container:
+If `output.file` is not enabled for this module, generated output can be redirected
+back to a file:
 
 ```bash
-docker run quay.io/terraform-docs/terraform-docs:0.15.0
+docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.15.0 markdown /terraform-docs > doc.md
 ```
 
 **NOTE:** Docker tag `latest` refers to _latest_ stable released version and `edge`
 refers to HEAD of `master` 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:
+
+```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.
+
+### 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:
+
+```yaml
+repos:
+  - repo: https://github.com/terraform-docs/terraform-docs
+    rev: "v0.15.0"
+    hooks:
+      - id: terraform-docs-go
+        args: ["markdown", "table", "--output-file", "README.md", "./mymodule/path"]
+```
+
+Then run:
+
+```bash
+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. Default name of this file is
+`.terraform-docs.yml` and the order for lookig for it is:
+
+1. root of module directory
+1. `.config/` folder at root of module directory
+1. current directory
+1. `.config/` folder at current directory
+1. `$HOME/.tfdocs.d/`
+
+```yaml
+formatter: "" # this is required
+
+version: ""
+
+header-from: main.tf
+footer-from: ""
+
+sections:
+  hide: []
+  show: []
+
+content: ""
+
+output:
+  file: ""
+  mode: inject
+  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
+  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 }}`
+- `{{ .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`.
+
+````yaml
+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" }}
+  ```
+````
+
+## 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.
+
 ## Community
 
 - Discuss terraform-docs on [Slack]
@@ -104,14 +294,17 @@ refers to HEAD of `master` at any given point in time.
 
 MIT License - Copyright (c) 2021 The terraform-docs Authors.
 
-[User Guide]: ./docs/user-guide/introduction.md
-[Formats Guide]: ./docs/reference/terraform-docs.md
-[Config File Reference]: ./docs/user-guide/configuration.md
+[Chocolatey]: https://www.chocolatey.org
+[Config File Reference]: https://terraform-docs.io/user-guide/configuration/
 [Contributing Guide]: CONTRIBUTING.md
-[our website]: https://terraform-docs.io/
+[Formats Guide]: https://terraform-docs.io/reference/terraform-docs/
 [here]: https://golang.org/doc/code.html#GOPATH
-[releases]: https://github.com/terraform-docs/terraform-docs/releases
 [Homebrew]: https://brew.sh
+[install pre-commit]: https://pre-commit.com/#install
+[`output`]: https://terraform-docs.io/user-guide/configuration/output/
+[releases]: https://github.com/terraform-docs/terraform-docs/releases
 [Scoop]: https://scoop.sh/
-[Chocolatey]: https://www.chocolatey.org
 [Slack]: https://slack.terraform-docs.io/
+[terraform-docs GitHub Action]: https://github.com/terraform-docs/gh-actions
+[our website]: https://terraform-docs.io/
+[User Guide]: https://terraform-docs.io/user-guide/introduction/
diff --git a/docs/developer-guide/plugins.md b/docs/developer-guide/plugins.md
@@ -16,5 +16,5 @@ If you want to create a new plugin, please refer to [tfdocs-format-template]. Th
 plugin can use [plugin-sdk] to communicate with the host process. You can create a
 new repository from `Use this template`.
 
-[tfdocs-format-template]: https://github.com/terraform-docs/tfdocs-format-template
 [plugin-sdk]: https://github.com/terraform-docs/plugin-sdk
+[tfdocs-format-template]: https://github.com/terraform-docs/tfdocs-format-template
diff --git a/docs/how-to/pre-commit-hooks.md b/docs/how-to/pre-commit-hooks.md
@@ -80,5 +80,5 @@ This is very basic and higly simplified version of [pre-commit-terraform](https:
 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
+[`pre-commit`]: https://pre-commit.com/
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -42,13 +42,12 @@ $ tree
 $ terraform-docs -c .tfdocs-config.yml .
 ```
 
-As of `v0.13.0`, the order for looking for config file is *(2 and 4 were added
-in `v0.15.0`)*:
+As of `v0.13.0`, the order for looking for config file is:
 
 1. root of module directory
-1. `.config/` folder at root of module directory
+1. `.config/` folder at root of module directory <sup class="no-top">(since v0.15.0)</sup>
 1. current directory
-1. `.config/` folder at current directory
+1. `.config/` folder at current directory <sup class="no-top">(since v0.15.0)</sup>
 1. `$HOME/.tfdocs.d/`
 
 if `.terraform-docs.yml` is found in any of the folders above, that will take
@@ -66,9 +65,9 @@ Below is a complete list of options that can be used with `terraform-docs`, with
 default values.
 
 ```yaml
-version: ""
+formatter: "" # this is required
 
-formatter: <FORMATTER_NAME>
+version: ""
 
 header-from: main.tf
 footer-from: ""
@@ -114,7 +113,7 @@ settings:
 ```
 
 {{< alert type="info" >}}
-Only `formatter` is required, the rest of the options are optional.
+`formatter` is the only required option.
 {{< /alert >}}
 
 ## Usage
diff --git a/docs/user-guide/configuration/content.md b/docs/user-guide/configuration/content.md
@@ -35,7 +35,7 @@ and following functions:
 
 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` and so on.
+when formatter is set to `markdown table`.
 
 {{< alert type="info" >}}
 Sections visibility (i.e. `sections.show` and `sections.hide`) takes
diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md
diff --git a/docs/user-guide/introduction.md b/docs/user-guide/introduction.md
