docs: Enhance automatic document generation (#227)

* Enhance automatic document generation * update contribuor guide * fix broken link
2026-03-27 12:58:35 +07:00 · 2020-03-29 18:17:55 -04:00
parent 9043f268ad
commit 40bd96be44
23 changed files with 130 additions and 75 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -21,13 +21,13 @@ Before contributing a new feature, please discuss its suitability with the proje

 Pull requests have to meet the following requirements:

-1. **Tests**: Code changes need to be tested with code and tests being located in the same folder (see packages [doc](https://github.com/segmentio/terraform-docs/tree/master/doc/) and [print](https://github.com/segmentio/terraform-docs/tree/master/print/) for examples). Make sure that your tests pass using `make test`.
+1. **Tests**: Code changes need to be tested with code and tests being located in the same folder (see packages [format](https://github.com/segmentio/terraform-docs/tree/master/internal/format/) for example). Make sure that your tests pass using `make test`.

-2. **Documentation**: Pull requests need to update the [documentation](https://github.com/segmentio/terraform-docs/tree/master/README.md) together with the code change.
+2. **Documentation**: Pull requests need to update the [Formats Guide](/docs/FORMATS_GUIDE.md) and if need be the main [README](README.md) together with the code change. You can generate the format guides by using `make docs`.

 3. **Commits**: Commits should be as small as possible while ensuring that each commit compiles and passes tests independently. [Write good commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). If needed, [squash your commits](https://davidwalsh.name/squash-commits-git) prior to submission.

-4. **Code Style**: Use [gofmt](https://blog.golang.org/go-fmt-your-code) to format your code. If useful, include code comments to support your intentions.
+4. **Code Style**: We use `goimports` which wrappes around [gofmt](https://blog.golang.org/go-fmt-your-code) to keep the code in unified format. You can use `make goimports` to install and `make fmt` to format your code. If useful, include code comments to support your intentions. Make sure your code doesn't have issues with `make checkfmt` and `make lint` before submission.

 ## Additional Resources

--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ terraform-docs xml ./my-terraform-module               # generate xml
 terraform-docs yaml ./my-terraform-module              # generate yaml
 ```

-Read the [User Guide](./docs/USER_GUIDE.md) for detailed documentation.
+Read the [User Guide](./docs/USER_GUIDE.md) and [Formats Guide](./docs/FORMATS_GUIDE.md) for detailed documentation.

 ## Installation

@@ -38,7 +38,7 @@ brew install terraform-docs

 Windows users can install using [Chocolatey](https://www.chocolatey.org):

-```
+``` bash
 choco install terraform-docs
 ```

@@ -89,7 +89,9 @@ To make this change permenant, the above commands can be added to your `~/.profi

 - **Users**
  - Read the [User Guide](./docs/USER_GUIDE.md) to learn how to use terraform-doccs
+  - Read the [Formats Guide](./docs/FORMATS_GUIDE.md) to learn about different output formats of terraform-doccs
 - **Developers**
+  - Read [Contributing Guide](CONTRIBUTING.md) before submitting a pull request.
  - Building: not written yet
  - Releasing: not written yet

--- a/cmd/json.go
+++ b/cmd/json.go
@@ -9,6 +9,9 @@ var jsonCmd = &cobra.Command{
 	Args:  cobra.ExactArgs(1),
 	Use:   "json [PATH]",
 	Short: "Generate JSON of inputs and outputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return doPrint(args[0], format.NewJSON(settings))
 	},
--- a/cmd/markdown.go
+++ b/cmd/markdown.go
@@ -10,26 +10,35 @@ var markdownCmd = &cobra.Command{
 	Use:     "markdown [PATH]",
 	Aliases: []string{"md"},
 	Short:   "Generate Markdown of inputs and outputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return doPrint(args[0], format.NewTable(settings))
 	},
 }

-var mdTableCmd = &cobra.Command{
+var markdownTableCmd = &cobra.Command{
 	Args:    cobra.ExactArgs(1),
 	Use:     "table [PATH]",
 	Aliases: []string{"tbl"},
 	Short:   "Generate Markdown tables of inputs and outputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return doPrint(args[0], format.NewTable(settings))
 	},
 }

-var mdDocumentCmd = &cobra.Command{
+var markdownDocumentCmd = &cobra.Command{
 	Args:    cobra.ExactArgs(1),
 	Use:     "document [PATH]",
 	Aliases: []string{"doc"},
 	Short:   "Generate Markdown document of inputs and outputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return doPrint(args[0], format.NewDocument(settings))
 	},
@@ -41,8 +50,8 @@ func init() {
 	markdownCmd.PersistentFlags().BoolVar(new(bool), "no-escape", false, "do not escape special characters")
 	markdownCmd.PersistentFlags().IntVar(&settings.MarkdownIndent, "indent", 2, "indention level of Markdown sections [1, 2, 3, 4, 5]")

-	markdownCmd.AddCommand(mdTableCmd)
-	markdownCmd.AddCommand(mdDocumentCmd)
+	markdownCmd.AddCommand(markdownTableCmd)
+	markdownCmd.AddCommand(markdownDocumentCmd)

 	rootCmd.AddCommand(markdownCmd)
 }
--- a/cmd/pretty.go
+++ b/cmd/pretty.go
@@ -9,6 +9,9 @@ var prettyCmd = &cobra.Command{
 	Args:  cobra.ExactArgs(1),
 	Use:   "pretty [PATH]",
 	Short: "Generate colorized pretty of inputs and outputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return doPrint(args[0], format.NewPretty(settings))
 	},
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -12,7 +12,6 @@ import (
 var settings = print.NewSettings()
 var options = module.NewOptions()

-// rootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
 	Args:    cobra.NoArgs,
 	Use:     "terraform-docs",
@@ -71,20 +70,9 @@ 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,
-		tfvarsHCLCmd,
-		tfvarsJSONCmd,
-		xmlCmd,
-		yamlCmd,
-	}
+// RootCmd represents the base command when called without any subcommands
+func RootCmd() *cobra.Command {
+	return rootCmd
 }

 func doPrint(path string, printer print.Format) error {
--- a/cmd/tfvars.go
+++ b/cmd/tfvars.go
@@ -9,12 +9,18 @@ var tfvarsCmd = &cobra.Command{
 	Args:  cobra.ExactArgs(1),
 	Use:   "tfvars [PATH]",
 	Short: "Generate terraform.tfvars of inputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 }

 var tfvarsHCLCmd = &cobra.Command{
 	Args:  cobra.ExactArgs(1),
 	Use:   "hcl [PATH]",
 	Short: "Generate HCL format of terraform.tfvars of inputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return doPrint(args[0], format.NewTfvarsHCL(settings))
 	},
@@ -24,6 +30,9 @@ var tfvarsJSONCmd = &cobra.Command{
 	Args:  cobra.ExactArgs(1),
 	Use:   "json [PATH]",
 	Short: "Generate JSON format of terraform.tfvars of inputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return doPrint(args[0], format.NewTfvarsJSON(settings))
 	},
--- a/cmd/xml.go
+++ b/cmd/xml.go
@@ -9,6 +9,9 @@ var xmlCmd = &cobra.Command{
 	Args:  cobra.ExactArgs(1),
 	Use:   "xml [PATH]",
 	Short: "Generate XML of inputs and outputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return doPrint(args[0], format.NewXML(settings))
 	},
--- a/cmd/yaml.go
+++ b/cmd/yaml.go
@@ -9,6 +9,9 @@ var yamlCmd = &cobra.Command{
 	Args:  cobra.ExactArgs(1),
 	Use:   "yaml [PATH]",
 	Short: "Generate YAML of inputs and outputs",
+	Annotations: map[string]string{
+		"kind": "formatter",
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return doPrint(args[0], format.NewYAML(settings))
 	},
--- a/docs/CONTRIBUTOR_GUIDE.md
+++ b/docs/CONTRIBUTOR_GUIDE.md
@@ -1,3 +0,0 @@
-# Contributor Guide
-
-TBA
--- a/docs/FORMATS_GUIDE.md
+++ b/docs/FORMATS_GUIDE.md
@@ -1,12 +1,12 @@
-# `terraform-docs`
+## terraform-docs

 A utility to generate documentation from Terraform modules in various output formats

-## Synopsis
+### Synopsis

 A utility to generate documentation from Terraform modules in various output formats

-## Options
+### Options

 ```
      --header-from string             relative path of a file to read header from (default "main.tf")
@@ -24,7 +24,7 @@ A utility to generate documentation from Terraform modules in various output for
      --with-aggregate-type-defaults   [deprecated] print default values of aggregate types
 ```

-## Output Formats
+### SEE ALSO

 * [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
@@ -33,10 +33,8 @@ A utility to generate documentation from Terraform modules in various output for
 * [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-hcl.md)	 - Generate JSON 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 xml](/docs/formats/xml.md)	 - Generate XML of inputs and outputs
 * [terraform-docs yaml](/docs/formats/yaml.md)	 - Generate YAML of inputs and outputs

-## Terraform Versions
-
-Support for Terraform `v0.12.x` has been added in `terraform-docs` version `v0.8.0`. Note that you can still generate output of module configuration which is not compatible with Terraform v0.12 with terraform-docs `v0.8.0` and future releases.
+###### Auto generated by spf13/cobra on 29-Mar-2020
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -1,8 +1,12 @@
 # User Guide

+## Terraform Versions
+
+Support for Terraform `v0.12.x` has been added in `terraform-docs` version `v0.8.0`. Note that you can still generate output of module configuration which is not compatible with Terraform v0.12 with terraform-docs `v0.8.0` and future releases.
+
 ## Syntax, Usage, and Output Formats

-Please refer to [docs/README.md](/docs/README.md) for guidance on output formats, execution syntax, CLI options, etc.
+Please refer to [Formats Guide](/docs/FORMATS_GUIDE.md) for guidance on output formats, execution syntax, CLI options, etc.

 ## Generate terraform.tfvars

--- a/docs/formats/json.md
+++ b/docs/formats/json.md
@@ -264,4 +264,4 @@ generates the following output:
    }


-###### Auto generated by spf13/cobra on 27-Mar-2020
+###### Auto generated by spf13/cobra on 29-Mar-2020
--- a/docs/formats/markdown-document.md
+++ b/docs/formats/markdown-document.md
@@ -366,4 +366,4 @@ generates the following output:



-###### Auto generated by spf13/cobra on 27-Mar-2020
+###### Auto generated by spf13/cobra on 29-Mar-2020
--- a/docs/formats/markdown-table.md
+++ b/docs/formats/markdown-table.md
@@ -140,4 +140,4 @@ generates the following output:



-###### Auto generated by spf13/cobra on 27-Mar-2020
+###### Auto generated by spf13/cobra on 29-Mar-2020
--- a/docs/formats/markdown.md
+++ b/docs/formats/markdown.md
@@ -13,11 +13,11 @@ terraform-docs markdown [PATH] [flags]
 ### Options

 ```
-  -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
-      --no-sensitive  do not show "Sensitive" column or section
+  -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
+      --no-sensitive   do not show "Sensitive" column or section
 ```

 ### Options inherited from parent commands
@@ -39,5 +39,7 @@ terraform-docs markdown [PATH] [flags]

 ### SEE ALSO

-* [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
+* [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 29-Mar-2020
--- a/docs/formats/pretty.md
+++ b/docs/formats/pretty.md
@@ -221,4 +221,4 @@ generates the following output:



-###### Auto generated by spf13/cobra on 27-Mar-2020
+###### Auto generated by spf13/cobra on 29-Mar-2020
--- a/docs/formats/tfvars-hcl.md
+++ b/docs/formats/tfvars-hcl.md
@@ -93,4 +93,4 @@ generates the following output:
    with-url                = ""


-###### Auto generated by spf13/cobra on 27-Mar-2020
+###### Auto generated by spf13/cobra on 29-Mar-2020
--- a/docs/formats/tfvars-json.md
+++ b/docs/formats/tfvars-json.md
@@ -95,4 +95,4 @@ generates the following output:
    }


-###### Auto generated by spf13/cobra on 27-Mar-2020
+###### Auto generated by spf13/cobra on 29-Mar-2020
--- a/docs/formats/tfvars.md
+++ b/docs/formats/tfvars.md
@@ -6,14 +6,10 @@ Generate terraform.tfvars of inputs

 Generate terraform.tfvars of inputs

-```
-terraform-docs tfvars [command]
-```
-
 ### Options

 ```
-  -h, --help          help for markdown
+  -h, --help   help for tfvars
 ```

 ### Options inherited from parent commands
@@ -36,4 +32,6 @@ terraform-docs tfvars [command]
 ### SEE ALSO

 * [terraform-docs tfvars hcl](/docs/formats/tfvars-hcl.md)	 - Generate HCL format of terraform.tfvars of inputs
-* [terraform-docs tfvars json](/docs/formats/tfvars-hcl.md)	 - Generate JSON 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 29-Mar-2020
--- a/docs/formats/xml.md
+++ b/docs/formats/xml.md
@@ -263,4 +263,4 @@ generates the following output:
    </module>


-###### Auto generated by spf13/cobra on 27-Mar-2020
+###### Auto generated by spf13/cobra on 29-Mar-2020
--- a/docs/formats/yaml.md
+++ b/docs/formats/yaml.md
@@ -232,4 +232,4 @@ generates the following output:
      version: '>= 2.15.0'


-###### Auto generated by spf13/cobra on 27-Mar-2020
+###### Auto generated by spf13/cobra on 29-Mar-2020
--- a/scripts/docs/generate.go
+++ b/scripts/docs/generate.go
@@ -22,28 +22,31 @@ import (
 // that we wanted to inject custom "Example" section with generated output based on the "examples"
 // folder.

+var basedir = "/docs"
+var formatdir = "/formats"
+
 func main() {
-	for _, c := range cmd.FormatterCmds() {
-		err := generate(c, "./docs/formats")
-		if err != nil {
-			log.Fatal(err)
-		}
+	err := generate(cmd.RootCmd(), "", "FORMATS_GUIDE")
+	if err != nil {
+		log.Fatal(err)
 	}
 }

-func generate(cmd *cobra.Command, dir string) error {
+func generate(cmd *cobra.Command, subdir string, basename string) error {
 	for _, c := range cmd.Commands() {
 		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 			continue
 		}
-		if err := generate(c, dir); err != nil {
+		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 {
 			return err
 		}
 	}

-	cmdpath := strings.Replace(cmd.CommandPath(), "terraform-docs ", "", -1)
-	basename := strings.Replace(cmdpath, " ", "-", -1) + ".md"
-	filename := filepath.Join(dir, basename)
+	filename := filepath.Join("."+basedir, subdir, basename+".md")
 	f, err := os.Create(filename)
 	if err != nil {
 		return err
@@ -90,15 +93,20 @@ func generateMarkdown(cmd *cobra.Command, w io.Writer) error {
 		return err
 	}

-	err := printExample(buf, name)
-	if err != nil {
-		return err
+	if len(cmd.Commands()) == 0 {
+		if err := printExample(buf, name); err != nil {
+			return err
+		}
+	} else {
+		if err := printSeeAlso(buf, cmd.Commands()); 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)
+	_, err := buf.WriteTo(w)
 	return err
 }

@@ -170,12 +178,12 @@ func printExample(buf *bytes.Buffer, name string) error {
 			Required: settings.SortByRequired,
 		},
 	}
-	tfmodule, err := module.LoadWithOptions(options)
-	if err != nil {
-		log.Fatal(err)
-	}

 	if printer := getPrinter(name, settings); printer != nil {
+		tfmodule, err := module.LoadWithOptions(options)
+		if err != nil {
+			log.Fatal(err)
+		}
 		output, err := printer.Print(tfmodule, settings)
 		if err != nil {
 			return err
@@ -193,3 +201,31 @@ func printExample(buf *bytes.Buffer, name string) error {
 	buf.WriteString("\n\n")
 	return nil
 }
+
+func printSeeAlso(buf *bytes.Buffer, children []*cobra.Command) error {
+	buf.WriteString("### SEE ALSO\n\n")
+	for _, child := range children {
+		if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
+			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))
+		for _, c := range child.Commands() {
+			if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+				continue
+			}
+			if c.Annotations["kind"] == "" || c.Annotations["kind"] != "formatter" {
+				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))
+		}
+	}
+	buf.WriteString("\n")
+	return nil
+}