From 304bce9bb0d03ccde094ea60fddd1fab76f07efd Mon Sep 17 00:00:00 2001 From: Khosrow Moossavi Date: Tue, 23 Feb 2021 14:19:14 -0500 Subject: [PATCH] Refactor docs to be published on website Signed-off-by: Khosrow Moossavi --- README.md | 8 +- docs/CONFIG_FILE.md | 61 ----- docs/FORMATS_GUIDE.md | 47 ---- docs/_index.md | 4 + .../asciidoc-document.md | 32 +-- docs/{formats => reference}/asciidoc-table.md | 32 +-- docs/{formats => reference}/asciidoc.md | 34 +-- docs/reference/config-file.md | 93 ++++++++ docs/{formats => reference}/json.md | 32 +-- .../markdown-document.md | 32 +-- docs/{formats => reference}/markdown-table.md | 32 +-- docs/{formats => reference}/markdown.md | 34 +-- docs/{formats => reference}/pretty.md | 32 +-- docs/reference/terraform-docs.md | 51 +++++ docs/{formats => reference}/tfvars-hcl.md | 32 +-- docs/{formats => reference}/tfvars-json.md | 32 +-- docs/{formats => reference}/tfvars.md | 32 +-- docs/{formats => reference}/toml.md | 32 +-- docs/{formats => reference}/xml.md | 32 +-- docs/{formats => reference}/yaml.md | 32 +-- scripts/docs/format.tmpl | 66 ++++++ scripts/docs/generate.go | 210 ++++++++++-------- 22 files changed, 598 insertions(+), 394 deletions(-) delete mode 100644 docs/CONFIG_FILE.md delete mode 100644 docs/FORMATS_GUIDE.md create mode 100644 docs/_index.md rename docs/{formats => reference}/asciidoc-document.md (94%) rename docs/{formats => reference}/asciidoc-table.md (94%) rename docs/{formats => reference}/asciidoc.md (72%) create mode 100644 docs/reference/config-file.md rename docs/{formats => reference}/json.md (96%) rename docs/{formats => reference}/markdown-document.md (94%) rename docs/{formats => reference}/markdown-table.md (93%) rename docs/{formats => reference}/markdown.md (73%) rename docs/{formats => reference}/pretty.md (92%) create mode 100644 docs/reference/terraform-docs.md rename docs/{formats => reference}/tfvars-hcl.md (85%) rename docs/{formats => reference}/tfvars-json.md (85%) rename docs/{formats => reference}/tfvars.md (68%) rename docs/{formats => reference}/toml.md (95%) rename docs/{formats => reference}/xml.md (97%) rename docs/{formats => reference}/yaml.md (95%) create mode 100644 scripts/docs/format.tmpl diff --git a/README.md b/README.md index f1481dd..fe8c7f4 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ terraform-docs yaml ./my-terraform-module # generate yaml - **Developers** - Read [Contributing Guide] before submitting a pull request -Visit [docs] folder for all documentation. +Visit [our webside] for all documentation. ## Installation @@ -124,10 +124,10 @@ Note that maintainers are unaffiliated with Segment. MIT License - Copyright (c) 2021 The terraform-docs Authors. [User Guide]: ./docs/USER_GUIDE.md -[Formats Guide]: ./docs/FORMATS_GUIDE.md -[Config File Reference]: ./docs/CONFIG_FILE.md +[Formats Guide]: ./docs/reference/terraform-docs.md +[Config File Reference]: ./docs/reference/config-file.md [Contributing Guide]: CONTRIBUTING.md -[docs]: ./docs/ +[our webside]: https://terraform-docs.io/ [here]: https://golang.org/doc/code.html#GOPATH [releases]: https://github.com/terraform-docs/terraform-docs/releases [Homebrew]: https://brew.sh diff --git a/docs/CONFIG_FILE.md b/docs/CONFIG_FILE.md deleted file mode 100644 index 999f89b..0000000 --- a/docs/CONFIG_FILE.md +++ /dev/null @@ -1,61 +0,0 @@ -# Config File Reference - -All available options for `.terraform-docs.yml`. Note that not all of them can be used at the same time (e.g. `sections.hide` and `sections.show`) - -```yaml -formatter: -header-from: main.tf - -sections: - hide-all: false - hide: - - header - - inputs - - modules - - outputs - - providers - - requirements - - resources - show-all: true - show: - - header - - inputs - - modules - - outputs - - providers - - requirements - - resources - -output-values: - enabled: false - from: "" - -sort: - enabled: true - by: - - required - - type - -settings: - color: true - escape: true - indent: 2 - required: true - sensitive: true -``` - -Available options for `FORMATTER_NAME` are: - -- `asciidoc` -- `asciidoc document` -- `asciidoc table` -- `json` -- `markdown` -- `markdown document` -- `markdown table` -- `pretty` -- `tfvars hcl` -- `tfvars json` -- `toml` -- `xml` -- `yaml` diff --git a/docs/FORMATS_GUIDE.md b/docs/FORMATS_GUIDE.md deleted file mode 100644 index 1331315..0000000 --- a/docs/FORMATS_GUIDE.md +++ /dev/null @@ -1,47 +0,0 @@ -## terraform-docs - -A utility to generate documentation from Terraform modules in various output formats - -### Synopsis - -A utility to generate documentation from Terraform modules in various output formats - -``` -terraform-docs [PATH] [flags] -``` - -### Options - -``` - -c, --config string config file name (default ".terraform-docs.yml") - --header-from string relative path of a file to read header from (default "main.tf") - -h, --help help for terraform-docs - --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] - --hide-all hide all sections (default false) - --output-values inject output values into outputs (default false) - --output-values-from string inject output values from file into outputs (default "") - --show strings show section [header, inputs, modules, outputs, providers, requirements, resources] - --show-all show all sections (default true) - --sort sort items (default true) - --sort-by-required sort items by name and print required ones first (default false) - --sort-by-type sort items by type of them (default false) -``` - -### SEE ALSO - -* [terraform-docs asciidoc](/docs/formats/asciidoc.md) - Generate AsciiDoc of inputs and outputs - * [terraform-docs asciidoc document](/docs/formats/asciidoc-document.md) - Generate AsciiDoc document of inputs and outputs - * [terraform-docs asciidoc table](/docs/formats/asciidoc-table.md) - Generate AsciiDoc tables of inputs and outputs -* [terraform-docs json](/docs/formats/json.md) - Generate JSON of inputs and outputs -* [terraform-docs markdown](/docs/formats/markdown.md) - Generate Markdown of inputs and outputs - * [terraform-docs markdown document](/docs/formats/markdown-document.md) - Generate Markdown document of inputs and outputs - * [terraform-docs markdown table](/docs/formats/markdown-table.md) - Generate Markdown tables of inputs and outputs -* [terraform-docs pretty](/docs/formats/pretty.md) - Generate colorized pretty of inputs and outputs -* [terraform-docs tfvars](/docs/formats/tfvars.md) - Generate terraform.tfvars of inputs - * [terraform-docs tfvars hcl](/docs/formats/tfvars-hcl.md) - Generate HCL format of terraform.tfvars of inputs - * [terraform-docs tfvars json](/docs/formats/tfvars-json.md) - Generate JSON format of terraform.tfvars of inputs -* [terraform-docs toml](/docs/formats/toml.md) - Generate TOML of inputs and outputs -* [terraform-docs xml](/docs/formats/xml.md) - Generate XML of inputs and outputs -* [terraform-docs yaml](/docs/formats/yaml.md) - Generate YAML of inputs and outputs - -###### Auto generated by spf13/cobra on 22-Feb-2021 diff --git a/docs/_index.md b/docs/_index.md new file mode 100644 index 0000000..87748e5 --- /dev/null +++ b/docs/_index.md @@ -0,0 +1,4 @@ +--- +title : "Generate Terraform module documentation" +description: "Generate documentation from Terraform modules in various output formats." +--- diff --git a/docs/formats/asciidoc-document.md b/docs/reference/asciidoc-document.md similarity index 94% rename from docs/formats/asciidoc-document.md rename to docs/reference/asciidoc-document.md index 10fccd8..2da3275 100644 --- a/docs/formats/asciidoc-document.md +++ b/docs/reference/asciidoc-document.md @@ -1,24 +1,30 @@ -## terraform-docs asciidoc document +--- +title: "asciidoc document" +description: "Generate AsciiDoc document of inputs and outputs." +menu: + docs: + parent: "asciidoc" +weight: 952 +toc: true +--- -Generate AsciiDoc document of inputs and outputs +## Synopsis -### Synopsis +Generate AsciiDoc document of inputs and outputs. -Generate AsciiDoc document of inputs and outputs - -``` +```console terraform-docs asciidoc document [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for document ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -35,9 +41,9 @@ terraform-docs asciidoc document [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs asciidoc document ./examples/ @@ -456,4 +462,4 @@ generates the following output: Description: It's unquoted output. -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/formats/asciidoc-table.md b/docs/reference/asciidoc-table.md similarity index 94% rename from docs/formats/asciidoc-table.md rename to docs/reference/asciidoc-table.md index d0cc972..1168854 100644 --- a/docs/formats/asciidoc-table.md +++ b/docs/reference/asciidoc-table.md @@ -1,24 +1,30 @@ -## terraform-docs asciidoc table +--- +title: "asciidoc table" +description: "Generate AsciiDoc tables of inputs and outputs." +menu: + docs: + parent: "asciidoc" +weight: 953 +toc: true +--- -Generate AsciiDoc tables of inputs and outputs +## Synopsis -### Synopsis +Generate AsciiDoc tables of inputs and outputs. -Generate AsciiDoc tables of inputs and outputs - -``` +```console terraform-docs asciidoc table [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for table ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -35,9 +41,9 @@ terraform-docs asciidoc table [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs asciidoc table ./examples/ @@ -400,4 +406,4 @@ generates the following output: |unquoted |It's unquoted output. |=== -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/formats/asciidoc.md b/docs/reference/asciidoc.md similarity index 72% rename from docs/formats/asciidoc.md rename to docs/reference/asciidoc.md index 9d36e30..d77a3e8 100644 --- a/docs/formats/asciidoc.md +++ b/docs/reference/asciidoc.md @@ -1,27 +1,33 @@ -## terraform-docs asciidoc +--- +title: "asciidoc" +description: "Generate AsciiDoc of inputs and outputs." +menu: + docs: + parent: "terraform-docs" +weight: 951 +toc: true +--- -Generate AsciiDoc of inputs and outputs +## Synopsis -### Synopsis +Generate AsciiDoc of inputs and outputs. -Generate AsciiDoc of inputs and outputs - -``` +```console terraform-docs asciidoc [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for asciidoc --indent int indention level of AsciiDoc sections [1, 2, 3, 4, 5] (default 2) --required show Required column or section (default true) --sensitive show Sensitive column or section (default true) ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -35,9 +41,7 @@ terraform-docs asciidoc [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### SEE ALSO +## Subcommands -* [terraform-docs asciidoc document](/docs/formats/asciidoc-document.md) - Generate AsciiDoc document of inputs and outputs -* [terraform-docs asciidoc table](/docs/formats/asciidoc-table.md) - Generate AsciiDoc tables of inputs and outputs - -###### Auto generated by spf13/cobra on 22-Feb-2021 +- [terraform-docs asciidoc document]({{< ref "asciidoc-document" >}}) +- [terraform-docs asciidoc table]({{< ref "asciidoc-table" >}}) diff --git a/docs/reference/config-file.md b/docs/reference/config-file.md new file mode 100644 index 0000000..7999f3b --- /dev/null +++ b/docs/reference/config-file.md @@ -0,0 +1,93 @@ +--- +title: "Config File" +description: "terraform-docs configuration file, i.e. .terraform-docs.yml" +menu: + docs: + parent: "reference" +weight: 900 +toc: true +--- + +The `terraform-docs` configuration is a yaml file. Its default name is `.terraform-docs.yml`. + +## Options + +Below is a complete list of options that you can use with `terraform-docs`, with their +corresponding default values (if applicable). + +```yaml +formatter: +header-from: main.tf + +sections: + hide-all: false + hide: [] + show-all: true + show: [] + +output-values: + enabled: false + from: "" + +sort: + enabled: true + by: + - required + - type + +settings: + color: true + escape: true + indent: 2 + required: true + sensitive: true +``` + +**Note:** The following options cannot be used together: + +- `sections.hide` and `sections.show` +- `sections.hide-all` and `sections.show-all` +- `sections.hide-all` and `sections.hide` +- `sections.show-all` and `sections.show` +- `sort.by.required` and `sort.by.type` + +## Formatters + +The following options are supported out of the box by terraform-docs and can be +used for `FORMATTER_NAME`: + +- `asciidoc` - [reference]({{< ref "asciidoc" >}}) +- `asciidoc document` - [reference]({{< ref "asciidoc-document" >}}) +- `asciidoc table` - [reference]({{< ref "asciidoc-table" >}}) +- `json` - [reference]({{< ref "json" >}}) +- `markdown` - [reference]({{< ref "markdown" >}}) +- `markdown document` - [reference]({{< ref "markdown-document" >}}) +- `markdown table` - [reference]({{< ref "markdown-table" >}}) +- `pretty` - [reference]({{< ref "pretty" >}}) +- `tfvars hcl` - [reference]({{< ref "tfvars-hcl" >}}) +- `tfvars json` - [reference]({{< ref "tfvars-json" >}}) +- `toml` - [reference]({{< ref "toml" >}}) +- `xml` - [reference]({{< ref "xml" >}}) +- `yaml` - [reference]({{< ref "yaml" >}}) + +**Note:** You need to pass name of a plugin as `formatter` in order to be able to +use the plugin. For example, if plugin binary file is called `tfdocs-format-foo`, +formatter name must be set to `foo`. + +## header-from + +Relative path to a file to extract header for the generated output from. Supported +file formats are `.adoc`, `.md`, `.tf`, and `.txt`. Default value is `main.tf`. + +## Sections + +The following options are supported and can be used for `sections.show` and +`sections.hide`: + +- `header` +- `inputs` +- `modules` +- `outputs` +- `providers` +- `requirements` +- `resources` diff --git a/docs/formats/json.md b/docs/reference/json.md similarity index 96% rename from docs/formats/json.md rename to docs/reference/json.md index a5526c8..c0fc5c6 100644 --- a/docs/formats/json.md +++ b/docs/reference/json.md @@ -1,25 +1,31 @@ -## terraform-docs json +--- +title: "json" +description: "Generate JSON of inputs and outputs." +menu: + docs: + parent: "terraform-docs" +weight: 954 +toc: true +--- -Generate JSON of inputs and outputs +## Synopsis -### Synopsis +Generate JSON of inputs and outputs. -Generate JSON of inputs and outputs - -``` +```console terraform-docs json [PATH] [flags] ``` -### Options +## Options -``` +```console --escape escape special characters (default true) -h, --help help for json ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -33,9 +39,9 @@ terraform-docs json [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs json ./examples/ @@ -385,4 +391,4 @@ generates the following output: ] } -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/formats/markdown-document.md b/docs/reference/markdown-document.md similarity index 94% rename from docs/formats/markdown-document.md rename to docs/reference/markdown-document.md index 2eb32c1..fc5c97e 100644 --- a/docs/formats/markdown-document.md +++ b/docs/reference/markdown-document.md @@ -1,24 +1,30 @@ -## terraform-docs markdown document +--- +title: "markdown document" +description: "Generate Markdown document of inputs and outputs." +menu: + docs: + parent: "markdown" +weight: 956 +toc: true +--- -Generate Markdown document of inputs and outputs +## Synopsis -### Synopsis +Generate Markdown document of inputs and outputs. -Generate Markdown document of inputs and outputs - -``` +```console terraform-docs markdown document [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for document ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --escape escape special characters (default true) --header-from string relative path of a file to read header from (default "main.tf") @@ -36,9 +42,9 @@ terraform-docs markdown document [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs markdown document ./examples/ @@ -457,4 +463,4 @@ generates the following output: Description: It's unquoted output. -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/formats/markdown-table.md b/docs/reference/markdown-table.md similarity index 93% rename from docs/formats/markdown-table.md rename to docs/reference/markdown-table.md index 3359eeb..f387623 100644 --- a/docs/formats/markdown-table.md +++ b/docs/reference/markdown-table.md @@ -1,24 +1,30 @@ -## terraform-docs markdown table +--- +title: "markdown table" +description: "Generate Markdown tables of inputs and outputs." +menu: + docs: + parent: "markdown" +weight: 957 +toc: true +--- -Generate Markdown tables of inputs and outputs +## Synopsis -### Synopsis +Generate Markdown tables of inputs and outputs. -Generate Markdown tables of inputs and outputs - -``` +```console terraform-docs markdown table [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for table ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --escape escape special characters (default true) --header-from string relative path of a file to read header from (default "main.tf") @@ -36,9 +42,9 @@ terraform-docs markdown table [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs markdown table ./examples/ @@ -162,4 +168,4 @@ generates the following output: | output-2 | It's output number two. | | unquoted | It's unquoted output. | -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/formats/markdown.md b/docs/reference/markdown.md similarity index 73% rename from docs/formats/markdown.md rename to docs/reference/markdown.md index 481443d..d0c7f64 100644 --- a/docs/formats/markdown.md +++ b/docs/reference/markdown.md @@ -1,18 +1,24 @@ -## terraform-docs markdown +--- +title: "markdown" +description: "Generate Markdown of inputs and outputs." +menu: + docs: + parent: "terraform-docs" +weight: 955 +toc: true +--- -Generate Markdown of inputs and outputs +## Synopsis -### Synopsis +Generate Markdown of inputs and outputs. -Generate Markdown of inputs and outputs - -``` +```console terraform-docs markdown [PATH] [flags] ``` -### Options +## Options -``` +```console --escape escape special characters (default true) -h, --help help for markdown --indent int indention level of Markdown sections [1, 2, 3, 4, 5] (default 2) @@ -20,9 +26,9 @@ terraform-docs markdown [PATH] [flags] --sensitive show Sensitive column or section (default true) ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -36,9 +42,7 @@ terraform-docs markdown [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### SEE ALSO +## Subcommands -* [terraform-docs markdown document](/docs/formats/markdown-document.md) - Generate Markdown document of inputs and outputs -* [terraform-docs markdown table](/docs/formats/markdown-table.md) - Generate Markdown tables of inputs and outputs - -###### Auto generated by spf13/cobra on 22-Feb-2021 +- [terraform-docs markdown document]({{< ref "markdown-document" >}}) +- [terraform-docs markdown table]({{< ref "markdown-table" >}}) diff --git a/docs/formats/pretty.md b/docs/reference/pretty.md similarity index 92% rename from docs/formats/pretty.md rename to docs/reference/pretty.md index 72522e7..ba575f1 100644 --- a/docs/formats/pretty.md +++ b/docs/reference/pretty.md @@ -1,25 +1,31 @@ -## terraform-docs pretty +--- +title: "pretty" +description: "Generate colorized pretty of inputs and outputs." +menu: + docs: + parent: "terraform-docs" +weight: 958 +toc: true +--- -Generate colorized pretty of inputs and outputs +## Synopsis -### Synopsis +Generate colorized pretty of inputs and outputs. -Generate colorized pretty of inputs and outputs - -``` +```console terraform-docs pretty [PATH] [flags] ``` -### Options +## Options -``` +```console --color colorize printed result (default true) -h, --help help for pretty ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -33,9 +39,9 @@ terraform-docs pretty [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs pretty --no-color ./examples/ @@ -242,4 +248,4 @@ generates the following output: output.unquoted It's unquoted output. -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/reference/terraform-docs.md b/docs/reference/terraform-docs.md new file mode 100644 index 0000000..83e4305 --- /dev/null +++ b/docs/reference/terraform-docs.md @@ -0,0 +1,51 @@ +--- +title: "terraform-docs" +description: "A utility to generate documentation from Terraform modules in various output formats." +menu: + docs: + parent: "reference" +weight: 950 +toc: true +--- + +## Synopsis + +A utility to generate documentation from Terraform modules in various output formats. + +```console +terraform-docs [PATH] [flags] +``` + +## Options + +```console + -c, --config string config file name (default ".terraform-docs.yml") + --header-from string relative path of a file to read header from (default "main.tf") + -h, --help help for terraform-docs + --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] + --hide-all hide all sections (default false) + --output-values inject output values into outputs (default false) + --output-values-from string inject output values from file into outputs (default "") + --show strings show section [header, inputs, modules, outputs, providers, requirements, resources] + --show-all show all sections (default true) + --sort sort items (default true) + --sort-by-required sort items by name and print required ones first (default false) + --sort-by-type sort items by type of them (default false) +``` + +## Subcommands + +- [terraform-docs asciidoc]({{< ref "asciidoc" >}}) + - [terraform-docs asciidoc document]({{< ref "asciidoc-document" >}}) + - [terraform-docs asciidoc table]({{< ref "asciidoc-table" >}}) +- [terraform-docs json]({{< ref "json" >}}) +- [terraform-docs markdown]({{< ref "markdown" >}}) + - [terraform-docs markdown document]({{< ref "markdown-document" >}}) + - [terraform-docs markdown table]({{< ref "markdown-table" >}}) +- [terraform-docs pretty]({{< ref "pretty" >}}) +- [terraform-docs tfvars]({{< ref "tfvars" >}}) + - [terraform-docs tfvars hcl]({{< ref "tfvars-hcl" >}}) + - [terraform-docs tfvars json]({{< ref "tfvars-json" >}}) +- [terraform-docs toml]({{< ref "toml" >}}) +- [terraform-docs xml]({{< ref "xml" >}}) +- [terraform-docs yaml]({{< ref "yaml" >}}) diff --git a/docs/formats/tfvars-hcl.md b/docs/reference/tfvars-hcl.md similarity index 85% rename from docs/formats/tfvars-hcl.md rename to docs/reference/tfvars-hcl.md index ae3e706..0db0e81 100644 --- a/docs/formats/tfvars-hcl.md +++ b/docs/reference/tfvars-hcl.md @@ -1,24 +1,30 @@ -## terraform-docs tfvars hcl +--- +title: "tfvars hcl" +description: "Generate HCL format of terraform.tfvars of inputs." +menu: + docs: + parent: "tfvars" +weight: 960 +toc: true +--- -Generate HCL format of terraform.tfvars of inputs +## Synopsis -### Synopsis +Generate HCL format of terraform.tfvars of inputs. -Generate HCL format of terraform.tfvars of inputs - -``` +```console terraform-docs tfvars hcl [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for hcl ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -32,9 +38,9 @@ terraform-docs tfvars hcl [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs tfvars hcl ./examples/ @@ -99,4 +105,4 @@ generates the following output: unquoted = "" with-url = "" -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/formats/tfvars-json.md b/docs/reference/tfvars-json.md similarity index 85% rename from docs/formats/tfvars-json.md rename to docs/reference/tfvars-json.md index aebc92e..091d77c 100644 --- a/docs/formats/tfvars-json.md +++ b/docs/reference/tfvars-json.md @@ -1,24 +1,30 @@ -## terraform-docs tfvars json +--- +title: "tfvars json" +description: "Generate JSON format of terraform.tfvars of inputs." +menu: + docs: + parent: "tfvars" +weight: 961 +toc: true +--- -Generate JSON format of terraform.tfvars of inputs +## Synopsis -### Synopsis +Generate JSON format of terraform.tfvars of inputs. -Generate JSON format of terraform.tfvars of inputs - -``` +```console terraform-docs tfvars json [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for json ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -32,9 +38,9 @@ terraform-docs tfvars json [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs tfvars json ./examples/ @@ -101,4 +107,4 @@ generates the following output: "with-url": "" } -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/formats/tfvars.md b/docs/reference/tfvars.md similarity index 68% rename from docs/formats/tfvars.md rename to docs/reference/tfvars.md index 3d3b374..ff14295 100644 --- a/docs/formats/tfvars.md +++ b/docs/reference/tfvars.md @@ -1,20 +1,26 @@ -## terraform-docs tfvars +--- +title: "tfvars" +description: "Generate terraform.tfvars of inputs." +menu: + docs: + parent: "terraform-docs" +weight: 959 +toc: true +--- -Generate terraform.tfvars of inputs +## Synopsis -### Synopsis +Generate terraform.tfvars of inputs. -Generate terraform.tfvars of inputs +## Options -### Options - -``` +```console -h, --help help for tfvars ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -28,9 +34,7 @@ Generate terraform.tfvars of inputs --sort-by-type sort items by type of them (default false) ``` -### SEE ALSO +## Subcommands -* [terraform-docs tfvars hcl](/docs/formats/tfvars-hcl.md) - Generate HCL format of terraform.tfvars of inputs -* [terraform-docs tfvars json](/docs/formats/tfvars-json.md) - Generate JSON format of terraform.tfvars of inputs - -###### Auto generated by spf13/cobra on 22-Feb-2021 +- [terraform-docs tfvars hcl]({{< ref "tfvars-hcl" >}}) +- [terraform-docs tfvars json]({{< ref "tfvars-json" >}}) diff --git a/docs/formats/toml.md b/docs/reference/toml.md similarity index 95% rename from docs/formats/toml.md rename to docs/reference/toml.md index 99ca9ee..6be1817 100644 --- a/docs/formats/toml.md +++ b/docs/reference/toml.md @@ -1,24 +1,30 @@ -## terraform-docs toml +--- +title: "toml" +description: "Generate TOML of inputs and outputs." +menu: + docs: + parent: "terraform-docs" +weight: 962 +toc: true +--- -Generate TOML of inputs and outputs +## Synopsis -### Synopsis +Generate TOML of inputs and outputs. -Generate TOML of inputs and outputs - -``` +```console terraform-docs toml [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for toml ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -32,9 +38,9 @@ terraform-docs toml [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs toml ./examples/ @@ -357,4 +363,4 @@ generates the following output: mode = "managed" version = "latest" -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/formats/xml.md b/docs/reference/xml.md similarity index 97% rename from docs/formats/xml.md rename to docs/reference/xml.md index e55b2f4..f6a04f3 100644 --- a/docs/formats/xml.md +++ b/docs/reference/xml.md @@ -1,24 +1,30 @@ -## terraform-docs xml +--- +title: "xml" +description: "Generate XML of inputs and outputs." +menu: + docs: + parent: "terraform-docs" +weight: 963 +toc: true +--- -Generate XML of inputs and outputs +## Synopsis -### Synopsis +Generate XML of inputs and outputs. -Generate XML of inputs and outputs - -``` +```console terraform-docs xml [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for xml ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -32,9 +38,9 @@ terraform-docs xml [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs xml ./examples/ @@ -384,4 +390,4 @@ generates the following output: -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/docs/formats/yaml.md b/docs/reference/yaml.md similarity index 95% rename from docs/formats/yaml.md rename to docs/reference/yaml.md index b7826a8..b0ef5aa 100644 --- a/docs/formats/yaml.md +++ b/docs/reference/yaml.md @@ -1,24 +1,30 @@ -## terraform-docs yaml +--- +title: "yaml" +description: "Generate YAML of inputs and outputs." +menu: + docs: + parent: "terraform-docs" +weight: 964 +toc: true +--- -Generate YAML of inputs and outputs +## Synopsis -### Synopsis +Generate YAML of inputs and outputs. -Generate YAML of inputs and outputs - -``` +```console terraform-docs yaml [PATH] [flags] ``` -### Options +## Options -``` +```console -h, --help help for yaml ``` -### Options inherited from parent commands +## Inherited Options -``` +```console -c, --config string config file name (default ".terraform-docs.yml") --header-from string relative path of a file to read header from (default "main.tf") --hide strings hide section [header, inputs, modules, outputs, providers, requirements, resources] @@ -32,9 +38,9 @@ terraform-docs yaml [PATH] [flags] --sort-by-type sort items by type of them (default false) ``` -### Example +## Example -Given the [`examples`](/examples/) module: +Given the [`examples`][examples] module: ```shell terraform-docs yaml ./examples/ @@ -320,4 +326,4 @@ generates the following output: mode: managed version: latest -###### Auto generated by spf13/cobra on 22-Feb-2021 +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples diff --git a/scripts/docs/format.tmpl b/scripts/docs/format.tmpl new file mode 100644 index 0000000..4e14c34 --- /dev/null +++ b/scripts/docs/format.tmpl @@ -0,0 +1,66 @@ +--- +title: "{{ .Name }}" +description: "{{ .Description }}." +menu: + docs: + parent: "{{ .Parent }}" +weight: {{ .Weight }} +toc: true +--- + +## Synopsis + +{{ .Synopsis }}. + +{{- if .Runnable -}} +{{ printf "\n" }} +```console +{{ .UseLine }} +``` +{{- end }} + +{{- if .Options -}} +{{ printf "\n" }} +## Options + +```console +{{ .Options -}} +``` +{{- end }} + +{{- if .InheritedOptions -}} +{{ printf "\n" }} +## Inherited Options + +```console +{{ .InheritedOptions -}} +``` +{{- end }} + +{{- if not .HasChildren -}} +{{ printf "\n" }} +## Example + +Given the [`examples`][examples] module: + +```shell +{{ .Usage }} +``` + +generates the following output: + +{{ .Example }} +[examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples +{{- else -}} +{{ printf "\n" }} +## Subcommands + +{{- printf "\n" -}} +{{- range .Subcommands -}} +{{- printf "\n" -}} +- [{{ .Name }}]({{"{{"}}< ref "{{ .Link }}" >{{"}}"}}) +{{- range .Children -}} +{{ printf "\n " }}- [{{ .Name }}]({{"{{"}}< ref "{{ .Link }}" >{{"}}"}}) +{{- end -}} +{{- end -}} +{{- end }} diff --git a/scripts/docs/generate.go b/scripts/docs/generate.go index aec33fe..d01cf94 100644 --- a/scripts/docs/generate.go +++ b/scripts/docs/generate.go @@ -18,7 +18,7 @@ import ( "os" "path/filepath" "strings" - "time" + "text/template" "github.com/spf13/cobra" @@ -29,35 +29,47 @@ import ( ) // These are practiaclly a copy/paste of https://github.com/spf13/cobra/blob/master/doc/md_docs.go -// The reason we've decided to bring them over and not use them directly from cobra module was -// that we wanted to inject custom "Example" section with generated output based on the "examples" -// folder. +// The reason we've decided to bring them over and not use them directly +// from cobra module was that we wanted to inject custom "Example" section +// with generated output based on the "examples" folder. -var basedir = "/docs" -var formatdir = "/formats" +var ( + baseWeight = 950 +) func main() { - err := generate(cmd.NewCommand(), "", "FORMATS_GUIDE") - if err != nil { + if err := generate(cmd.NewCommand(), baseWeight, "terraform-docs"); err != nil { log.Fatal(err) } } -func generate(cmd *cobra.Command, subdir string, basename string) error { +func ignore(cmd *cobra.Command) bool { + switch { + case !cmd.IsAvailableCommand(): + return true + case cmd.IsAdditionalHelpTopicCommand(): + return true + case cmd.Annotations["kind"] == "": + return true + case cmd.Annotations["kind"] != "formatter": + return true + } + return false +} + +func generate(cmd *cobra.Command, weight int, basename string) error { for _, c := range cmd.Commands() { - if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() { + if ignore(c) { continue } - if c.Annotations["kind"] == "" || c.Annotations["kind"] != "formatter" { - continue - } - b := strings.Replace(strings.Replace(c.CommandPath(), " ", "-", -1), "terraform-docs-", "", -1) - if err := generate(c, formatdir, b); err != nil { + b := extractFilename(c.CommandPath()) + baseWeight++ + if err := generate(c, baseWeight, b); err != nil { return err } } - filename := filepath.Join("."+basedir, subdir, basename+".md") + filename := filepath.Join("docs", "reference", basename+".md") f, err := os.Create(filename) if err != nil { return err @@ -67,94 +79,98 @@ func generate(cmd *cobra.Command, subdir string, basename string) error { if _, err := io.WriteString(f, ""); err != nil { return err } - if err := generateMarkdown(cmd, f); err != nil { + if err := generateMarkdown(cmd, weight, f); err != nil { return err } return nil } -func generateMarkdown(cmd *cobra.Command, w io.Writer) error { +type reference struct { + Name string + Command string + Description string + Parent string + Synopsis string + Runnable bool + HasChildren bool + UseLine string + Options string + InheritedOptions string + Usage string + Example string + Subcommands []command + Weight int +} + +type command struct { + Name string + Link string + Children []command +} + +func generateMarkdown(cmd *cobra.Command, weight int, w io.Writer) error { cmd.InitDefaultHelpCmd() cmd.InitDefaultHelpFlag() - buf := new(bytes.Buffer) - name := cmd.CommandPath() + command := cmd.CommandPath() + name := strings.Replace(command, "terraform-docs ", "", -1) short := cmd.Short long := cmd.Long + if len(long) == 0 { long = short } - buf.WriteString("## " + name + "\n\n") - buf.WriteString(short + "\n\n") - buf.WriteString("### Synopsis\n\n") - buf.WriteString(long + "\n\n") - - if cmd.Runnable() { - buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine())) + parent := "reference" + if cmd.Parent() != nil { + parent = cmd.Parent().Name() } - if len(cmd.Example) > 0 { - buf.WriteString("### Examples\n\n") - buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example)) + ref := &reference{ + Name: name, + Command: command, + Description: short, + Parent: parent, + Synopsis: long, + Runnable: cmd.Runnable(), + HasChildren: len(cmd.Commands()) > 0, + UseLine: cmd.UseLine(), + Weight: weight, } - if err := printOptions(buf, cmd, name); err != nil { - return err + // Options + if f := cmd.NonInheritedFlags(); f.HasAvailableFlags() { + ref.Options = f.FlagUsages() } - if len(cmd.Commands()) == 0 { - if err := printExample(buf, name); err != nil { - return err - } + // Inherited Options + if f := cmd.InheritedFlags(); f.HasAvailableFlags() { + ref.InheritedOptions = f.FlagUsages() + } + + if ref.HasChildren { + subcommands(ref, cmd.Commands()) } else { - if err := printSeeAlso(buf, cmd.Commands()); err != nil { - return err - } + example(ref) //nolint:errcheck } - if !cmd.DisableAutoGenTag { - buf.WriteString("###### Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "\n") - } - _, err := buf.WriteTo(w) - return err + file := "format.tmpl" + paths := []string{filepath.Join("scripts", "docs", file)} + + t := template.Must(template.New(file).ParseFiles(paths...)) + + return t.Execute(w, ref) } -func printOptions(buf *bytes.Buffer, cmd *cobra.Command, name string) error { - flags := cmd.NonInheritedFlags() - flags.SetOutput(buf) - if flags.HasAvailableFlags() { - buf.WriteString("### Options\n\n```\n") - flags.PrintDefaults() - buf.WriteString("```\n\n") - } - - parentFlags := cmd.InheritedFlags() - parentFlags.SetOutput(buf) - if parentFlags.HasAvailableFlags() { - buf.WriteString("### Options inherited from parent commands\n\n```\n") - parentFlags.PrintDefaults() - buf.WriteString("```\n\n") - } - return nil -} - -func getFlags(name string) string { - switch strings.Replace(name, "terraform-docs ", "", -1) { +func example(ref *reference) error { + flag := "" + switch ref.Name { case "pretty": - return " --no-color" + flag = " --no-color" } - return "" -} -func printExample(buf *bytes.Buffer, name string) error { - buf.WriteString("### Example\n\n") - buf.WriteString("Given the [`examples`](/examples/) module:\n\n") - buf.WriteString("```shell\n") - buf.WriteString(fmt.Sprintf("%s%s ./examples/\n", name, getFlags(name))) - buf.WriteString("```\n\n") - buf.WriteString("generates the following output:\n\n") + ref.Usage = fmt.Sprintf("%s%s ./examples/", ref.Command, flag) settings := print.DefaultSettings() settings.ShowColor = false @@ -168,20 +184,23 @@ func printExample(buf *bytes.Buffer, name string) error { }, } - name = strings.Replace(name, "terraform-docs ", "", -1) - printer, err := format.Factory(name, settings) + printer, err := format.Factory(ref.Name, settings) if err != nil { return err } + tfmodule, err := terraform.LoadWithOptions(options) if err != nil { log.Fatal(err) } + output, err := printer.Print(tfmodule, settings) if err != nil { return err } + segments := strings.Split(output, "\n") + buf := new(bytes.Buffer) for _, s := range segments { if s == "" { buf.WriteString("\n") @@ -189,34 +208,35 @@ func printExample(buf *bytes.Buffer, name string) error { buf.WriteString(fmt.Sprintf(" %s\n", s)) } } - buf.WriteString("\n") + ref.Example = buf.String() + return nil } -func printSeeAlso(buf *bytes.Buffer, children []*cobra.Command) error { - buf.WriteString("### SEE ALSO\n\n") +func subcommands(ref *reference, children []*cobra.Command) { + subs := []command{} for _, child := range children { - if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() { + if ignore(child) { continue } - if child.Annotations["kind"] == "" || child.Annotations["kind"] != "formatter" { - continue - } - cname := child.CommandPath() - link := strings.Replace(strings.Replace(cname, " ", "-", -1)+".md", "terraform-docs-", "", -1) - buf.WriteString(fmt.Sprintf("* [%s](%s%s/%s)\t - %s\n", cname, basedir, formatdir, link, child.Short)) + subchild := []command{} for _, c := range child.Commands() { - if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() { - continue - } - if c.Annotations["kind"] == "" || c.Annotations["kind"] != "formatter" { + if ignore(c) { continue } cname := c.CommandPath() - link := strings.Replace(strings.Replace(cname, " ", "-", -1)+".md", "terraform-docs-", "", -1) - buf.WriteString(fmt.Sprintf(" * [%s](%s%s/%s)\t - %s\n", cname, basedir, formatdir, link, c.Short)) + link := extractFilename(cname) + subchild = append(subchild, command{Name: cname, Link: link}) } + cname := child.CommandPath() + link := extractFilename(cname) + subs = append(subs, command{Name: cname, Link: link, Children: subchild}) } - buf.WriteString("\n") - return nil + ref.Subcommands = subs +} + +func extractFilename(s string) string { + s = strings.Replace(s, " ", "-", -1) + s = strings.Replace(s, "terraform-docs-", "", -1) + return s }