diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77f19b2..a90f255 100644 --- 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 diff --git a/README.md b/README.md index e860083..df6da03 100644 --- 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 diff --git a/cmd/json.go b/cmd/json.go index 87f7613..949eef3 100644 --- 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)) }, diff --git a/cmd/markdown.go b/cmd/markdown.go index 8a52106..20d287c 100644 --- 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) } diff --git a/cmd/pretty.go b/cmd/pretty.go index 3167850..45ca5fd 100644 --- 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)) }, diff --git a/cmd/root.go b/cmd/root.go index 2f858fa..226650c 100644 --- 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 { diff --git a/cmd/tfvars.go b/cmd/tfvars.go index d0b5976..80b4e4d 100644 --- 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)) }, diff --git a/cmd/xml.go b/cmd/xml.go index 82f61bd..daafb9b 100644 --- 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)) }, diff --git a/cmd/yaml.go b/cmd/yaml.go index 854cb85..1ec5586 100644 --- 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)) }, diff --git a/docs/CONTRIBUTOR_GUIDE.md b/docs/CONTRIBUTOR_GUIDE.md deleted file mode 100644 index 41b824b..0000000 --- a/docs/CONTRIBUTOR_GUIDE.md +++ /dev/null @@ -1,3 +0,0 @@ -# Contributor Guide - -TBA diff --git a/docs/README.md b/docs/FORMATS_GUIDE.md similarity index 82% rename from docs/README.md rename to docs/FORMATS_GUIDE.md index 434c5ad..a3a21a2 100644 --- a/docs/README.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 diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 5788d0d..e95d67c 100644 --- 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 diff --git a/docs/formats/json.md b/docs/formats/json.md index 2adcf91..0263d91 100644 --- 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 diff --git a/docs/formats/markdown-document.md b/docs/formats/markdown-document.md index 5a66f1d..52a2f68 100644 --- 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 diff --git a/docs/formats/markdown-table.md b/docs/formats/markdown-table.md index 74abea2..c8b0c6a 100644 --- 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 diff --git a/docs/formats/markdown.md b/docs/formats/markdown.md index 7710064..5e9e8c9 100644 --- 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 diff --git a/docs/formats/pretty.md b/docs/formats/pretty.md index c12dfbf..74d8e71 100644 --- 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 diff --git a/docs/formats/tfvars-hcl.md b/docs/formats/tfvars-hcl.md index bb5bf84..301c612 100644 --- 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 diff --git a/docs/formats/tfvars-json.md b/docs/formats/tfvars-json.md index ed5a61c..e8c6b87 100644 --- 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 diff --git a/docs/formats/tfvars.md b/docs/formats/tfvars.md index aa908d0..c4974c2 100644 --- 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 diff --git a/docs/formats/xml.md b/docs/formats/xml.md index 7009075..5ba6d64 100644 --- a/docs/formats/xml.md +++ b/docs/formats/xml.md @@ -263,4 +263,4 @@ generates the following output: -###### Auto generated by spf13/cobra on 27-Mar-2020 +###### Auto generated by spf13/cobra on 29-Mar-2020 diff --git a/docs/formats/yaml.md b/docs/formats/yaml.md index 0b51901..ac8ed55 100644 --- 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 diff --git a/scripts/docs/generate.go b/scripts/docs/generate.go index 49e1a79..d377222 100644 --- 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 +}