diff --git a/CHANGELOG.md b/CHANGELOG.md index 292457a1..18e70de1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,17 @@ +# 0.12.0 (June 29, 2022) + +BUG FIXES: + +* template data: A regression was introduced in [#155](https://github.com/hashicorp/terraform-plugin-docs/pull/155) making template data field `HasExample` and `HasImport` always true ([#162](https://github.com/hashicorp/terraform-plugin-docs/pull/162)). + +NEW FEATURES: + +* template functions: Added `lower`, `upper` and `title` ([#162](https://github.com/hashicorp/terraform-plugin-docs/pull/162)). + +ENHANCEMENTS: + +* Added documentation for all the template functions and template data fields ([#162](https://github.com/hashicorp/terraform-plugin-docs/pull/162)). + # 0.11.0 (June 28, 2022) NEW FEATURES: diff --git a/README.md b/README.md index afd2742b..8efab099 100644 --- a/README.md +++ b/README.md @@ -128,22 +128,50 @@ For examples: ### Templates -The templates are implemented with Go [`text/template`](https://golang.org/pkg/text/template/) using the following objects and functions: - -#### Template Objects - -TBD - -#### Template Functions - -| Function | Description | -|-----------------|--------------------------------------------------------------------------------------------------------------------| -| `codefile` | Create a Markdown code block and populate it with the contents of a file. Path is relative to the repository root. | -| `tffile` | A special case of the `codefile` function. In addition this will elide lines with an `OMIT` comment. | -| `trimspace` | `strings.TrimSpace` | -| `plainmarkdown` | Render Markdown content as plaintext | -| `split` | Split string into sub-strings, eg. `split .Name "_"` | - +The templates are implemented with Go [`text/template`](https://golang.org/pkg/text/template/) +using the following data fields and functions: + +#### Data fields + +##### Provider + +| Field | Type | Description | +|------------------------:|:------:|-------------------------------------------------------------------------------------------| +| `.Description` | string | Provider description | +| `.HasExample` | bool | Is there an example file? | +| `.ExampleFile` | string | Path to the file with the terraform configuration example | +| `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`) | +| `.ProviderShortName` | string | Short version of the provider name (ex. `random`) | +| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` | + +##### Resources / Data Source + +| Field | Type | Description | +|------------------------:|:------:|-------------------------------------------------------------------------------------------| +| `.Name` | string | Name of the resource/data-source (ex. `tls_certificate`) | +| `.Type` | string | Either `Resource` or `Data Source` | +| `.Description` | string | Resource / Data Source description | +| `.HasExample` | bool | Is there an example file? | +| `.ExampleFile` | string | Path to the file with the terraform configuration example | +| `.HasImport` | bool | Is there an import file? | +| `.ImportFile` | string | Path to the file with the command for importing the resource | +| `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`) | +| `.ProviderShortName` | string | Short version of the provider name (ex. `random`) | +| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` | + +#### Functions + +| Function | Description | +|-----------------|---------------------------------------------------------------------------------------------------| +| `codefile` | Create a Markdown code block with the content of a file. Path is relative to the repository root. | +| `lower` | Equivalent to [`strings.ToLower`](https://pkg.go.dev/strings#ToLower). | +| `plainmarkdown` | Render Markdown content as plaintext. | +| `prefixlines` | Add a prefix to all (newline-separated) lines in a string. | +| `split` | Split string into sub-strings, by a given separator (ex. `split .Name "_"`). | +| `title` | Equivalent to [`strings.ToLower`](https://pkg.go.dev/strings#ToTitle). | +| `tffile` | A special case of the `codefile` function, designed for Terraform files (i.e. `.tf`). | +| `trimspace` | Equivalent to [`strings.TrimSpace`](https://pkg.go.dev/strings#TrimSpace). | +| `upper` | Equivalent to [`strings.ToLower`](https://pkg.go.dev/strings#ToUpper). | ## Disclaimer diff --git a/internal/provider/template.go b/internal/provider/template.go index f1970f78..0aa777a6 100644 --- a/internal/provider/template.go +++ b/internal/provider/template.go @@ -32,17 +32,17 @@ type ( func newTemplate(name, text string) (*template.Template, error) { tmpl := template.New(name) - tmpl.Funcs(template.FuncMap(map[string]interface{}{ + tmpl.Funcs(map[string]interface{}{ "codefile": tmplfuncs.CodeFile, + "lower": strings.ToLower, "plainmarkdown": mdplain.PlainMarkdown, "prefixlines": tmplfuncs.PrefixLines, - "tffile": func(file string) (string, error) { - // TODO: omit comment handling - return tmplfuncs.CodeFile("terraform", file) - }, - "trimspace": strings.TrimSpace, - "split": strings.Split, - })) + "split": strings.Split, + "tffile": terraformCodeFile, + "title": strings.ToTitle, + "trimspace": strings.TrimSpace, + "upper": strings.ToUpper, + }) var err error tmpl, err = tmpl.Parse(text) @@ -53,6 +53,11 @@ func newTemplate(name, text string) (*template.Template, error) { return tmpl, nil } +func terraformCodeFile(file string) (string, error) { + // TODO: omit comment handling + return tmplfuncs.CodeFile("terraform", file) +} + func renderTemplate(name string, text string, out io.Writer, data interface{}) error { tmpl, err := newTemplate(name, text) if err != nil { @@ -130,16 +135,11 @@ func (t providerTemplate) Render(providerName, renderedProviderName, exampleFile return "", nil } return renderStringTemplate("providerTemplate", s, struct { - Type string - Name string Description string HasExample bool ExampleFile string - HasImport bool - ImportFile string - ProviderName string ProviderShortName string @@ -149,7 +149,7 @@ func (t providerTemplate) Render(providerName, renderedProviderName, exampleFile }{ Description: schema.Block.Description, - HasExample: exampleFile != "", + HasExample: exampleFile != "" && fileExists(exampleFile), ExampleFile: exampleFile, ProviderName: providerName, @@ -195,10 +195,10 @@ func (t resourceTemplate) Render(name, providerName, renderedProviderName, typeN Name: name, Description: schema.Block.Description, - HasExample: exampleFile != "", + HasExample: exampleFile != "" && fileExists(exampleFile), ExampleFile: exampleFile, - HasImport: importFile != "", + HasImport: importFile != "" && fileExists(importFile), ImportFile: importFile, ProviderName: providerName,