centersl/terraform-docs
1
0
Fork 0
mirror of https://github.com/terraform-docs/terraform-docs.git synced 2026-03-27 04:48:33 +07:00
Code Issues Packages Projects Releases Wiki Activity

docs: Auto generate formats document from examples (#192)

Browse Source 
* Auto generate formats document from examples

* fix lint issues
This commit is contained in:
Khosrow Moossavi
2020-02-10 20:53:57 -05:00
committed by GitHub
parent dafa2e84f7
commit 54ab7f9bbb
17 changed files with 583 additions and 368 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
Makefile
View File

@@ -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 ##
#####################

66
README.md
View File

@@ -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

2
cmd/json.go
View File

@@ -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)

2
cmd/pretty.go
View File

@@ -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)

13
cmd/root.go
View File

@@ -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 {

2
cmd/yaml.go
View File

@@ -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)

3
docs/CONTRIBUTOR_GUIDE.md Normal file
View File

@@ -0,0 +1,3 @@
# Contributor Guide
TBA

38
docs/README.md
View File

@@ -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

3
docs/USER_GUIDE.md Normal file
View File

@@ -0,0 +1,3 @@
# User Guide
TBA

10
docs/formats/README.md
View File

@@ -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)

354
docs/formats/json.md
View File

@@ -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

56
docs/formats/markdown-document.md
View File

@@ -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

54
docs/formats/markdown-table.md
View File

@@ -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.<br>And an example in a code block<pre>default = [<br> "machine rack01:neptune"<br>]</pre> | `list` | <pre>[<br> "name rack:location"<br>]</pre> | 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

39
docs/formats/markdown.md
View File

@@ -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

86
docs/formats/pretty.md
View File

@@ -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

30
docs/formats/yaml.md
View File

@@ -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

188
scripts/docs/generate.go Normal file
View File

@@ -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
}