From 54ab7f9bbba020e44115a065c3760af4fad0c848 Mon Sep 17 00:00:00 2001 From: Khosrow Moossavi Date: Mon, 10 Feb 2020 20:53:57 -0500 Subject: [PATCH] docs: Auto generate formats document from examples (#192) * Auto generate formats document from examples * fix lint issues --- Makefile | 5 + README.md | 66 +++--- cmd/json.go | 2 +- cmd/pretty.go | 2 +- cmd/root.go | 13 ++ cmd/yaml.go | 2 +- docs/CONTRIBUTOR_GUIDE.md | 3 + docs/README.md | 38 +--- docs/USER_GUIDE.md | 3 + docs/formats/README.md | 10 - docs/formats/json.md | 354 +++++++++++++++--------------- docs/formats/markdown-document.md | 56 +++-- docs/formats/markdown-table.md | 54 +++-- docs/formats/markdown.md | 39 ++-- docs/formats/pretty.md | 86 +++++--- docs/formats/yaml.md | 30 ++- scripts/docs/generate.go | 188 ++++++++++++++++ 17 files changed, 583 insertions(+), 368 deletions(-) create mode 100644 docs/CONTRIBUTOR_GUIDE.md create mode 100644 docs/USER_GUIDE.md delete mode 100644 docs/formats/README.md create mode 100644 scripts/docs/generate.go diff --git a/Makefile b/Makefile index 7716a2e..8e28f7d 100644 --- a/Makefile +++ b/Makefile @@ -98,6 +98,11 @@ build-all: clean ## Build binary for all OS/ARCH @ $(MAKE) --no-print-directory log-$@ @ ./scripts/build/build-all-osarch.sh "$(BUILD_DIR)" "$(NAME)" "$(VERSION)" "$(GOOS)" "$(GOARCH)" $(GOLDFLAGS) +.PHONY: docs +docs: ## Generate document of formatter commands + @ $(MAKE) --no-print-directory log-$@ + $(GORUN) ./scripts/docs/generate.go + ##################### ## Release targets ## ##################### diff --git a/README.md b/README.md index d4da269..b12dae0 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,23 @@ -# terraform-docs [![Build Status](https://github.com/segmentio/terraform-docs/workflows/build/badge.svg)](https://github.com/segmentio/terraform-docs/actions) [![GoDoc](https://godoc.org/github.com/segmentio/terraform-docs?status.svg)](https://godoc.org/github.com/segmentio/terraform-docs) [![Go Report Card](https://goreportcard.com/badge/github.com/segmentio/terraform-docs)](https://goreportcard.com/report/github.com/segmentio/terraform-docs) +# terraform-docs -> **A utility to generate documentation from Terraform modules in various output formats.** +[![Build Status](https://github.com/segmentio/terraform-docs/workflows/build/badge.svg)](https://github.com/segmentio/terraform-docs/actions) [![GoDoc](https://godoc.org/github.com/segmentio/terraform-docs?status.svg)](https://godoc.org/github.com/segmentio/terraform-docs) [![Go Report Card](https://goreportcard.com/badge/github.com/segmentio/terraform-docs)](https://goreportcard.com/report/github.com/segmentio/terraform-docs) [![License](https://img.shields.io/github/license/segmentio/terraform-docs)](https://github.com/segmentio/terraform-docs/blob/master/LICENSE) [![Latest release](https://img.shields.io/github/v/release/segmentio/terraform-docs)](https://github.com/segmentio/terraform-docs/releases) ![terraform-docs-teaser](./images/terraform-docs-teaser.png) -## Table of Contents +## What is terraform-docs -- [Maintenance](#maintenance) -- [Installation](#installation) -- [Getting Started](#getting-started) -- [Development Requirements](#development-requirements) -- [License](#license) +A utility to generate documentation from Terraform modules in various output formats. -## Maintenance +``` bash +terraform-docs pretty ./my-terraform-module # generate colorized pretty +terraform-docs json ./my-terraform-module # generate json +terraform-docs yaml ./my-terraform-module # generate yaml +terraform-docs markdown ./my-terraform-module # generate markdown table +terraform-docs markdown table ./my-terraform-module # generate markdown table +terraform-docs markdown document ./my-terraform-module # generate markdown document +``` -This project is no longer maintained by Segment. Instead, [Martin Etmajer](https://github.com/metmajer) from [GetCloudnative](https://github.com/getcloudnative) and [Khosrow Moossavi](https://github.com/khos2ow) from [CloudOps](https://github.com/cloudops) are maintaining the project with help from these awesome [contributors](AUTHORS). Note that maintainers are unaffiliated with Segment. +Read the [User Guide](./docs/USER_GUIDE.md) for detailed documentation. ## Installation @@ -73,44 +76,27 @@ autoload -U compinit && compinit To make this change permenant, the above commands can be added to your `~/.profile` file. -## Getting Started +## Documentation -Show help information: +- **Users** + - Read the [User Guide](./docs/USER_GUIDE.md) to learn how to use terraform-doccs +- **Developers** + - Building: not written yet + - Releasing: not written yet -``` bash -terraform-docs --help -``` - -Generate [JSON](docs/formats/json.md) from the Terraform configuration in folder `./examples`: - -```bash -terraform-docs json ./examples -``` - -Generate [YAML](docs/formats/yaml.md) from the Terraform configuration in folder `./examples`: - -```bash -terraform-docs yaml ./examples -``` - -Generate [Markdown tables](docs/formats/markdown-table.md) from the Terraform configuration in folder `./examples`: - -```bash -terraform-docs markdown table ./examples -``` - -Generate a [Markdown document](docs/formats/markdown-document.md) from the Terraform configuration in folder `./examples`: - -```bash -terraform-docs markdown document ./examples -``` +Visit [./docs](./docs/) for all documentation. ## Development Requirements -- Go 1.13+ +- [Go](https://golang.org/) 1.13+ +- [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) - [git-chlog](https://github.com/git-chglog/git-chglog) - [golangci-lint](https://github.com/golangci/golangci-lint) +## Maintenance + +This project is no longer maintained by Segment. Instead, [Martin Etmajer](https://github.com/metmajer) from [GetCloudnative](https://github.com/getcloudnative) and [Khosrow Moossavi](https://github.com/khos2ow) from [CloudOps](https://github.com/cloudops) are maintaining the project with help from these awesome [contributors](AUTHORS). Note that maintainers are unaffiliated with Segment. + ## License MIT License diff --git a/cmd/json.go b/cmd/json.go index 5559afe..49fa0ac 100644 --- a/cmd/json.go +++ b/cmd/json.go @@ -9,7 +9,7 @@ import ( var jsonCmd = &cobra.Command{ Args: cobra.ExactArgs(1), Use: "json [PATH]", - Short: "Generate a JSON of inputs and outputs", + Short: "Generate JSON of inputs and outputs", Run: func(cmd *cobra.Command, args []string) { doPrint(args, func(module *tfconf.Module) (string, error) { return json.Print(module, settings) diff --git a/cmd/pretty.go b/cmd/pretty.go index c467b5d..6427c12 100644 --- a/cmd/pretty.go +++ b/cmd/pretty.go @@ -9,7 +9,7 @@ import ( var prettyCmd = &cobra.Command{ Args: cobra.ExactArgs(1), Use: "pretty [PATH]", - Short: "Generate a colorized pretty of inputs and outputs", + Short: "Generate colorized pretty of inputs and outputs", Run: func(cmd *cobra.Command, args []string) { doPrint(args, func(module *tfconf.Module) (string, error) { return pretty.Print(module, settings) diff --git a/cmd/root.go b/cmd/root.go index 18c4935..938fcd6 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -73,6 +73,19 @@ func Execute() error { return rootCmd.Execute() } +// FormatterCmds returns list of available formatter +// commands (e.g. markdown, json, yaml) and ignores +// the other commands (e.g. completion, version, help) +func FormatterCmds() []*cobra.Command { + return []*cobra.Command{ + jsonCmd, + prettyCmd, + mdDocumentCmd, + mdTableCmd, + yamlCmd, + } +} + func doPrint(paths []string, fn func(*tfconf.Module) (string, error)) { module, err := tfconf.CreateModule(paths[0]) if err != nil { diff --git a/cmd/yaml.go b/cmd/yaml.go index 3bb6aed..08bda57 100644 --- a/cmd/yaml.go +++ b/cmd/yaml.go @@ -9,7 +9,7 @@ import ( var yamlCmd = &cobra.Command{ Args: cobra.ExactArgs(1), Use: "yaml [PATH]", - Short: "Generate a YAML of inputs and outputs", + Short: "Generate YAML of inputs and outputs", Run: func(cmd *cobra.Command, args []string) { doPrint(args, func(module *tfconf.Module) (string, error) { return yaml.Print(module, settings) diff --git a/docs/CONTRIBUTOR_GUIDE.md b/docs/CONTRIBUTOR_GUIDE.md new file mode 100644 index 0000000..41b824b --- /dev/null +++ b/docs/CONTRIBUTOR_GUIDE.md @@ -0,0 +1,3 @@ +# Contributor Guide + +TBA diff --git a/docs/README.md b/docs/README.md index 86cf4c0..c77296b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,23 +1,14 @@ -# `terraform-docs` Documentations +# `terraform-docs` -A utility to generate documentation from Terraform modules in various output formats. +A utility to generate documentation from Terraform modules in various output formats -## Usage +## Synopsis -```text -Usage: - terraform-docs [command] +A utility to generate documentation from Terraform modules in various output formats -Available Commands: - completion Generate autocomplete for terraform-docs - help Help about any command - json Generate a JSON of inputs and outputs - markdown Generate Markdown of inputs and outputs - pretty Generate a colorized pretty of inputs and outputs - version Print the version number of terraform-docs - yaml Generate a YAML of inputs and outputs +## Options -Flags: +``` -h, --help help for terraform-docs --no-header do not show module header --no-inputs do not show inputs @@ -26,22 +17,17 @@ Flags: --no-sort do no sort items --sort-by-required sort items by name and print required ones first --sort-inputs-by-required [deprecated] use '--sort-by-required' instead - --version version for terraform-docs --with-aggregate-type-defaults [deprecated] print default values of aggregate types - -Use "terraform-docs [command] --help" for more information about a command. ``` ## Output Formats -The following output formats are available: - -- [JSON](/docs/formats/json.md) -- [Markdown](/docs/formats/markdown.md) - - [Document](/docs/formats/markdown-document.md) - - [Table](/docs/formats/markdown-table.md) -- [Pretty](/docs/formats/pretty.md) -- [YAML](/docs/formats/yaml.md) +* [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 yaml](/docs/formats/yaml.md) - Generate YAML of inputs and outputs ## Terraform Versions diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 0000000..f240a16 --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,3 @@ +# User Guide + +TBA diff --git a/docs/formats/README.md b/docs/formats/README.md deleted file mode 100644 index 5c893e1..0000000 --- a/docs/formats/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Output Formats - -The following output formats are available: - -- [JSON](/docs/formats/json.md) -- [Markdown](/docs/formats/markdown.md) - - [Document](/docs/formats/markdown-document.md) - - [Table](/docs/formats/markdown-table.md) -- [Pretty](/docs/formats/pretty.md) -- [YAML](/docs/formats/yaml.md) diff --git a/docs/formats/json.md b/docs/formats/json.md index 01360b9..9b3003c 100644 --- a/docs/formats/json.md +++ b/docs/formats/json.md @@ -1,18 +1,25 @@ -# JSON +## terraform-docs json -Generate a JSON of inputs and outputs. +Generate JSON of inputs and outputs -## Usage +### Synopsis -```text -Usage: - terraform-docs json [PATH] [flags] +Generate JSON of inputs and outputs -Flags: +``` +terraform-docs json [PATH] [flags] +``` + +### Options + +``` -h, --help help for json --no-escape do not escape special characters +``` -Global Flags: +### Options inherited from parent commands + +``` --no-header do not show module header --no-inputs do not show inputs --no-outputs do not show outputs @@ -23,7 +30,7 @@ Global Flags: --with-aggregate-type-defaults [deprecated] print default values of aggregate types ``` -## Example +### Example Given the [`examples`](/examples/) module: @@ -33,171 +40,172 @@ terraform-docs json ./examples/ generates the following output: -```json -{ - "header": "Usage:\n\nExample of 'foo_bar' module in `foo_bar.tf`.\n\n- list item 1\n- list item 2\n\nEven inline **formatting** in _here_ is possible.\nand some [link](https://domain.com/)\n\n* list item 3\n* list item 4\n\n```hcl\nmodule \"foo_bar\" {\n source = \"github.com/foo/bar\"\n\n id = \"1234567890\"\n name = \"baz\"\n\n zones = [\"us-east-1\", \"us-west-1\"]\n\n tags = {\n Name = \"baz\"\n Created-By = \"first.last@email.com\"\n Date-Created = \"20180101\"\n }\n}\n```\n\nHere is some trailing text after code block,\nfollowed by another line of text.\n\n| Name | Description |\n|------|-----------------|\n| Foo | Foo description |\n| Bar | Bar description |", - "inputs": [ { - "name": "input-with-code-block", - "type": "list", - "description": "This is a complicated one. We need a newline. \nAnd an example in a code block\n```\ndefault = [\n \"machine rack01:neptune\"\n]\n```\n", - "default": [ - "name rack:location" - ] - }, - { - "name": "input-with-pipe", - "type": "string", - "description": "It includes v1 | v2 | v3", - "default": "v1" - }, - { - "name": "input_with_underscores", - "type": "any", - "description": "A variable with underscores.", - "default": null - }, - { - "name": "list-1", - "type": "list", - "description": "It's list number one.", - "default": [ - "a", - "b", - "c" - ] - }, - { - "name": "list-2", - "type": "list", - "description": "It's list number two.", - "default": null - }, - { - "name": "list-3", - "type": "list", - "description": null, - "default": [] - }, - { - "name": "long_type", - "type": "object({\n name = string,\n foo = object({ foo = string, bar = string }),\n bar = object({ foo = string, bar = string }),\n fizz = list(string),\n buzz = list(string)\n })", - "description": "This description is itself markdown.\n\nIt spans over multiple lines.\n", - "default": { - "bar": { - "bar": "bar", - "foo": "bar" + "header": "Usage:\n\nExample of 'foo_bar' module in `foo_bar.tf`.\n\n- list item 1\n- list item 2\n\nEven inline **formatting** in _here_ is possible.\nand some [link](https://domain.com/)\n\n* list item 3\n* list item 4\n\n```hcl\nmodule \"foo_bar\" {\n source = \"github.com/foo/bar\"\n\n id = \"1234567890\"\n name = \"baz\"\n\n zones = [\"us-east-1\", \"us-west-1\"]\n\n tags = {\n Name = \"baz\"\n Created-By = \"first.last@email.com\"\n Date-Created = \"20180101\"\n }\n}\n```\n\nHere is some trailing text after code block,\nfollowed by another line of text.\n\n| Name | Description |\n|------|-----------------|\n| Foo | Foo description |\n| Bar | Bar description |", + "inputs": [ + { + "name": "input-with-code-block", + "type": "list", + "description": "This is a complicated one. We need a newline. \nAnd an example in a code block\n```\ndefault = [\n \"machine rack01:neptune\"\n]\n```\n", + "default": [ + "name rack:location" + ] }, - "buzz": [ - "fizz", - "buzz" - ], - "fizz": [], - "foo": { - "bar": "foo", - "foo": "foo" + { + "name": "input-with-pipe", + "type": "string", + "description": "It includes v1 | v2 | v3", + "default": "v1" }, - "name": "hello" - } - }, - { - "name": "map-1", - "type": "map", - "description": "It's map number one.", - "default": { - "a": 1, - "b": 2, - "c": 3 - } - }, - { - "name": "map-2", - "type": "map", - "description": "It's map number two.", - "default": null - }, - { - "name": "map-3", - "type": "map", - "description": null, - "default": {} - }, - { - "name": "no-escape-default-value", - "type": "string", - "description": "The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'.", - "default": "VALUE_WITH_UNDERSCORE" - }, - { - "name": "string-1", - "type": "string", - "description": "It's string number one.", - "default": "bar" - }, - { - "name": "string-2", - "type": "string", - "description": "It's string number two.", - "default": null - }, - { - "name": "string-3", - "type": "string", - "description": null, - "default": "" - }, - { - "name": "unquoted", - "type": "any", - "description": null, - "default": null - }, - { - "name": "with-url", - "type": "string", - "description": "The description contains url. https://www.domain.com/foo/bar_baz.html", - "default": "" + { + "name": "input_with_underscores", + "type": "any", + "description": "A variable with underscores.", + "default": null + }, + { + "name": "list-1", + "type": "list", + "description": "It's list number one.", + "default": [ + "a", + "b", + "c" + ] + }, + { + "name": "list-2", + "type": "list", + "description": "It's list number two.", + "default": null + }, + { + "name": "list-3", + "type": "list", + "description": null, + "default": [] + }, + { + "name": "long_type", + "type": "object({\n name = string,\n foo = object({ foo = string, bar = string }),\n bar = object({ foo = string, bar = string }),\n fizz = list(string),\n buzz = list(string)\n })", + "description": "This description is itself markdown.\n\nIt spans over multiple lines.\n", + "default": { + "bar": { + "bar": "bar", + "foo": "bar" + }, + "buzz": [ + "fizz", + "buzz" + ], + "fizz": [], + "foo": { + "bar": "foo", + "foo": "foo" + }, + "name": "hello" + } + }, + { + "name": "map-1", + "type": "map", + "description": "It's map number one.", + "default": { + "a": 1, + "b": 2, + "c": 3 + } + }, + { + "name": "map-2", + "type": "map", + "description": "It's map number two.", + "default": null + }, + { + "name": "map-3", + "type": "map", + "description": null, + "default": {} + }, + { + "name": "no-escape-default-value", + "type": "string", + "description": "The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'.", + "default": "VALUE_WITH_UNDERSCORE" + }, + { + "name": "string-1", + "type": "string", + "description": "It's string number one.", + "default": "bar" + }, + { + "name": "string-2", + "type": "string", + "description": "It's string number two.", + "default": null + }, + { + "name": "string-3", + "type": "string", + "description": null, + "default": "" + }, + { + "name": "unquoted", + "type": "any", + "description": null, + "default": null + }, + { + "name": "with-url", + "type": "string", + "description": "The description contains url. https://www.domain.com/foo/bar_baz.html", + "default": "" + } + ], + "outputs": [ + { + "name": "output-0.12", + "description": "terraform 0.12 only" + }, + { + "name": "output-1", + "description": "It's output number one." + }, + { + "name": "output-2", + "description": "It's output number two." + }, + { + "name": "unquoted", + "description": "It's unquoted output." + } + ], + "providers": [ + { + "name": "aws", + "alias": null, + "version": "\u003e= 2.15.0" + }, + { + "name": "aws", + "alias": "ident", + "version": "\u003e= 2.15.0" + }, + { + "name": "null", + "alias": null, + "version": null + }, + { + "name": "tls", + "alias": null, + "version": null + } + ] } - ], - "outputs": [ - { - "name": "output-0.12", - "description": "terraform 0.12 only" - }, - { - "name": "output-1", - "description": "It's output number one." - }, - { - "name": "output-2", - "description": "It's output number two." - }, - { - "name": "unquoted", - "description": "It's unquoted output." - } - ], - "providers": [ - { - "name": "aws", - "alias": null, - "version": "\u003e= 2.15.0" - }, - { - "name": "aws", - "alias": "ident", - "version": "\u003e= 2.15.0" - }, - { - "name": "null", - "alias": null, - "version": null - }, - { - "name": "tls", - "alias": null, - "version": null - } - ] -} -``` + + +###### Auto generated by spf13/cobra on 10-Feb-2020 diff --git a/docs/formats/markdown-document.md b/docs/formats/markdown-document.md index ba4f03c..231465d 100644 --- a/docs/formats/markdown-document.md +++ b/docs/formats/markdown-document.md @@ -1,20 +1,24 @@ -# Markdown Document +## terraform-docs markdown document -Generate Markdown document of inputs and outputs. +Generate Markdown document of inputs and outputs -## Usage +### Synopsis -```text -Usage: - terraform-docs markdown document [PATH] [flags] +Generate Markdown document of inputs and outputs -Aliases: - document, doc +``` +terraform-docs markdown document [PATH] [flags] +``` -Flags: +### Options + +``` -h, --help help for document +``` -Global Flags: +### Options inherited from parent commands + +``` --indent int indention level of Markdown sections [1, 2, 3, 4, 5] (default 2) --no-escape do not escape special characters --no-header do not show module header @@ -28,7 +32,7 @@ Global Flags: --with-aggregate-type-defaults [deprecated] print default values of aggregate types ``` -## Example +### Example Given the [`examples`](/examples/) module: @@ -45,7 +49,7 @@ generates the following output: - list item 1 - list item 2 - Even inline **formatting** in _here_ is possible. + Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -53,22 +57,22 @@ generates the following output: ```hcl module "foo_bar" { - source = "github.com/foo/bar" + source = "github.com/foo/bar" - id = "1234567890" - name = "baz" + id = "1234567890" + name = "baz" - zones = ["us-east-1", "us-west-1"] + zones = ["us-east-1", "us-west-1"] - tags = { - Name = "baz" - Created-By = "first.last@email.com" - Date-Created = "20180101" - } + tags = { + Name = "baz" + Created-By = "first.last@email.com" + Date-Created = "20180101" + } } ``` - Here is some trailing text after code block, + Here is some trailing text after code block, followed by another line of text. | Name | Description | @@ -128,7 +132,7 @@ generates the following output: ### input-with-code-block - Description: This is a complicated one. We need a newline. + Description: This is a complicated one. We need a newline. And an example in a code block ``` default = [ @@ -193,7 +197,7 @@ generates the following output: bar = object({ foo = string, bar = string }), fizz = list(string), buzz = list(string) - }) + }) ``` Default: @@ -292,3 +296,7 @@ generates the following output: ### unquoted Description: It's unquoted output. + + + +###### Auto generated by spf13/cobra on 10-Feb-2020 diff --git a/docs/formats/markdown-table.md b/docs/formats/markdown-table.md index d23e996..1c1e147 100644 --- a/docs/formats/markdown-table.md +++ b/docs/formats/markdown-table.md @@ -1,20 +1,24 @@ -# Markdown Table +## terraform-docs markdown table -Generate Markdown tables of inputs and outputs. +Generate Markdown tables of inputs and outputs -## Usage +### Synopsis -```text -Usage: - terraform-docs markdown table [PATH] [flags] +Generate Markdown tables of inputs and outputs -Aliases: - table, tbl +``` +terraform-docs markdown table [PATH] [flags] +``` -Flags: +### Options + +``` -h, --help help for table +``` -Global Flags: +### Options inherited from parent commands + +``` --indent int indention level of Markdown sections [1, 2, 3, 4, 5] (default 2) --no-escape do not escape special characters --no-header do not show module header @@ -28,7 +32,7 @@ Global Flags: --with-aggregate-type-defaults [deprecated] print default values of aggregate types ``` -## Example +### Example Given the [`examples`](/examples/) module: @@ -45,7 +49,7 @@ generates the following output: - list item 1 - list item 2 - Even inline **formatting** in _here_ is possible. + Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -53,22 +57,22 @@ generates the following output: ```hcl module "foo_bar" { - source = "github.com/foo/bar" + source = "github.com/foo/bar" - id = "1234567890" - name = "baz" + id = "1234567890" + name = "baz" - zones = ["us-east-1", "us-west-1"] + zones = ["us-east-1", "us-west-1"] - tags = { - Name = "baz" - Created-By = "first.last@email.com" - Date-Created = "20180101" - } + tags = { + Name = "baz" + Created-By = "first.last@email.com" + Date-Created = "20180101" + } } ``` - Here is some trailing text after code block, + Here is some trailing text after code block, followed by another line of text. | Name | Description | @@ -88,7 +92,7 @@ generates the following output: ## Inputs | Name | Description | Type | Default | Required | - |------|-------------|------|---------|:-----:| + |------|-------------|------|---------|:--------:| | input-with-code-block | This is a complicated one. We need a newline.
And an example in a code block
default     = [
  "machine rack01:neptune"
]
| `list` | 
[
  "name rack:location"
]
| no | | input-with-pipe | It includes v1 \| v2 \| v3 | `string` | `"v1"` | no | | input\_with\_underscores | A variable with underscores. | `any` | n/a | yes | @@ -114,3 +118,7 @@ generates the following output: | output-1 | It's output number one. | | output-2 | It's output number two. | | unquoted | It's unquoted output. | + + + +###### Auto generated by spf13/cobra on 10-Feb-2020 diff --git a/docs/formats/markdown.md b/docs/formats/markdown.md index d488b9a..8840173 100644 --- a/docs/formats/markdown.md +++ b/docs/formats/markdown.md @@ -1,28 +1,27 @@ -# Markdown +## terraform-docs markdown -Generate Markdown of inputs and outputs. +Generate Markdown of inputs and outputs -## Usage +### Synopsis -```text -Usage: - terraform-docs markdown [PATH] [flags] - terraform-docs markdown [command] +Generate Markdown of inputs and outputs -Aliases: - markdown, md +``` +terraform-docs markdown [PATH] [flags] +``` -Available Commands: - document Generate Markdown document of inputs and outputs - table Generate Markdown tables of inputs and outputs +### Options -Flags: +``` -h, --help help for markdown --indent int indention level of Markdown sections [1, 2, 3, 4, 5] (default 2) --no-escape do not escape special characters --no-required do not show "Required" column or section +``` -Global Flags: +### Options inherited from parent commands + +``` --no-header do not show module header --no-inputs do not show inputs --no-outputs do not show outputs @@ -31,15 +30,9 @@ Global Flags: --sort-by-required sort items by name and print required ones first --sort-inputs-by-required [deprecated] use '--sort-by-required' instead --with-aggregate-type-defaults [deprecated] print default values of aggregate types - -Use "terraform-docs markdown [command] --help" for more information about a command. ``` -## Markdown Types +### SEE ALSO -The following Markdown specific output formats are available: - -- [Document](/docs/formats/markdown-document.md) -- [Table](/docs/formats/markdown-table.md) - -Note that the default format, if not explicitly defined, is `tables`. +* [terraform-docs markdown document](markdown-document.md) - Generate Markdown document of inputs and outputs +* [terraform-docs markdown table](markdown-table.md) - Generate Markdown tables of inputs and outputs diff --git a/docs/formats/pretty.md b/docs/formats/pretty.md index 2cdf8f3..8ee6fe6 100644 --- a/docs/formats/pretty.md +++ b/docs/formats/pretty.md @@ -1,18 +1,25 @@ -# Pretty +## terraform-docs pretty -Generate a colorized pretty of inputs and outputs. +Generate colorized pretty of inputs and outputs -## Usage +### Synopsis -```text -Usage: - terraform-docs pretty [PATH] [flags] +Generate colorized pretty of inputs and outputs -Flags: +``` +terraform-docs pretty [PATH] [flags] +``` + +### Options + +``` -h, --help help for pretty --no-color do not colorize printed result +``` -Global Flags: +### Options inherited from parent commands + +``` --no-header do not show module header --no-inputs do not show inputs --no-outputs do not show outputs @@ -23,7 +30,7 @@ Global Flags: --with-aggregate-type-defaults [deprecated] print default values of aggregate types ``` -## Example +### Example Given the [`examples`](/examples/) module: @@ -33,6 +40,8 @@ terraform-docs pretty --no-color ./examples/ generates the following output: + + Usage: Example of 'foo_bar' module in `foo_bar.tf`. @@ -46,20 +55,20 @@ generates the following output: * list item 3 * list item 4 - ``` + ```hcl module "foo_bar" { - source = "github.com/foo/bar" + source = "github.com/foo/bar" - id = "1234567890" - name = "baz" + id = "1234567890" + name = "baz" - zones = ["us-east-1", "us-west-1"] + zones = ["us-east-1", "us-west-1"] - tags = { - Name = "baz" - Created-By = "first.last@email.com" - Date-Created = "20180101" - } + tags = { + Name = "baz" + Created-By = "first.last@email.com" + Date-Created = "20180101" + } } ``` @@ -84,13 +93,13 @@ generates the following output: input.input-with-code-block ([ - "name rack:location" + "name rack:location" ]) - This is a complicated one. We need a newline. + This is a complicated one. We need a newline. And an example in a code block ``` default = [ - "machine rack01:neptune" + "machine rack01:neptune" ] ``` @@ -101,9 +110,9 @@ generates the following output: A variable with underscores. input.list-1 ([ - "a", - "b", - "c" + "a", + "b", + "c" ]) It's list number one. @@ -114,29 +123,29 @@ generates the following output: n/a input.long_type ({ - "bar": { + "bar": { "bar": "bar", "foo": "bar" - }, - "buzz": [ + }, + "buzz": [ "fizz", "buzz" - ], - "fizz": [], - "foo": { + ], + "fizz": [], + "foo": { "bar": "foo", "foo": "foo" - }, - "name": "hello" + }, + "name": "hello" }) This description is itself markdown. It spans over multiple lines. input.map-1 ({ - "a": 1, - "b": 2, - "c": 3 + "a": 1, + "b": 2, + "c": 3 }) It's map number one. @@ -177,3 +186,8 @@ generates the following output: output.unquoted It's unquoted output. + + + + +###### Auto generated by spf13/cobra on 10-Feb-2020 diff --git a/docs/formats/yaml.md b/docs/formats/yaml.md index 6441fe6..fdd4318 100644 --- a/docs/formats/yaml.md +++ b/docs/formats/yaml.md @@ -1,17 +1,24 @@ -# YAML +## terraform-docs yaml -Generate a YAML of inputs and outputs. +Generate YAML of inputs and outputs -## Usage +### Synopsis -```text -Usage: - terraform-docs yaml [PATH] [flags] +Generate YAML of inputs and outputs -Flags: - -h, --help help for json +``` +terraform-docs yaml [PATH] [flags] +``` -Global Flags: +### Options + +``` + -h, --help help for yaml +``` + +### Options inherited from parent commands + +``` --no-header do not show module header --no-inputs do not show inputs --no-outputs do not show outputs @@ -22,7 +29,7 @@ Global Flags: --with-aggregate-type-defaults [deprecated] print default values of aggregate types ``` -## Example +### Example Given the [`examples`](/examples/) module: @@ -186,3 +193,6 @@ generates the following output: - name: tls alias: "" version: "" + + +###### Auto generated by spf13/cobra on 10-Feb-2020 diff --git a/scripts/docs/generate.go b/scripts/docs/generate.go new file mode 100644 index 0000000..7d9ffea --- /dev/null +++ b/scripts/docs/generate.go @@ -0,0 +1,188 @@ +package main + +import ( + "bytes" + "fmt" + "io" + "log" + "os" + "path/filepath" + "strings" + "time" + + "github.com/segmentio/terraform-docs/cmd" + "github.com/segmentio/terraform-docs/internal/pkg/print" + "github.com/segmentio/terraform-docs/internal/pkg/print/json" + "github.com/segmentio/terraform-docs/internal/pkg/print/markdown/document" + "github.com/segmentio/terraform-docs/internal/pkg/print/markdown/table" + "github.com/segmentio/terraform-docs/internal/pkg/print/pretty" + "github.com/segmentio/terraform-docs/internal/pkg/print/yaml" + "github.com/segmentio/terraform-docs/internal/pkg/tfconf" + "github.com/spf13/cobra" +) + +// 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. + +func main() { + for _, c := range cmd.FormatterCmds() { + err := generate(c, "./docs/formats") + if err != nil { + log.Fatal(err) + } + } +} + +func generate(cmd *cobra.Command, dir string) error { + for _, c := range cmd.Commands() { + if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() { + continue + } + if err := generate(c, dir); err != nil { + return err + } + } + + cmdpath := strings.Replace(cmd.CommandPath(), "terraform-docs ", "", -1) + basename := strings.Replace(cmdpath, " ", "-", -1) + ".md" + filename := filepath.Join(dir, basename) + f, err := os.Create(filename) + if err != nil { + return err + } + defer f.Close() //nolint:errcheck + + if _, err := io.WriteString(f, ""); err != nil { + return err + } + if err := generateMarkdown(cmd, f); err != nil { + return err + } + return nil +} + +func generateMarkdown(cmd *cobra.Command, w io.Writer) error { + cmd.InitDefaultHelpCmd() + cmd.InitDefaultHelpFlag() + + buf := new(bytes.Buffer) + name := cmd.CommandPath() + + 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())) + } + + if len(cmd.Example) > 0 { + buf.WriteString("### Examples\n\n") + buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example)) + } + + if err := printOptions(buf, cmd, name); err != nil { + return err + } + + err := printExample(buf, name) + if err != nil { + return err + } + + if !cmd.DisableAutoGenTag { + buf.WriteString("###### Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "\n") + } + _, err = buf.WriteTo(w) + return err +} + +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 +} + +type printer func(*tfconf.Module, *print.Settings) (string, error) + +func getPrinter(name string) printer { + switch strings.Replace(name, "terraform-docs ", "", -1) { + case "json": + return json.Print + case "markdown document": + return document.Print + case "markdown table": + return table.Print + case "pretty": + return pretty.Print + case "yaml": + return yaml.Print + } + return nil +} + +func getFlags(name string) string { + switch strings.Replace(name, "terraform-docs ", "", -1) { + case "pretty": + return " --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") + + module, err := tfconf.CreateModule("./examples") + if err != nil { + log.Fatal(err) + } + + // fmt.Println(name) + if fn := getPrinter(name); fn != nil { + settings := print.NewSettings() + settings.ShowColor = false + + output, err := fn(module, settings) + if err != nil { + return err + } + segments := strings.Split(output, "\n") + for _, s := range segments { + if s == "" { + buf.WriteString("\n") + } else { + buf.WriteString(fmt.Sprintf(" %s\n", s)) + } + } + } + + buf.WriteString("\n\n") + return nil +}