Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix regression with HasImport/HasExample data fields, and (finally) document template data fields #162

Merged
merged 5 commits into from Jun 29, 2022
Merged

Fix regression with HasImport/HasExample data fields, and (finally) document template data fields #162

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6c3b36f
Bugfix: Ensure we don't set `HasExample` and `HasImport` unless the f…
Jun 29, 2022
84d6a67
Document template data fields and functions
Jun 29, 2022
c24f072
Adding `lower`, `upper` and `title` functions
Jun 29, 2022
a26cf6b
Also fixing `HasExample` for Provider templates
Jun 29, 2022
3f21b09
Preparing changelog for 0.12.0
Jun 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
@@ -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:
Expand Down
60 changes: 44 additions & 16 deletions README.md
View file
Open in desktop
Expand Up @@ -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

Expand Down
32 changes: 16 additions & 16 deletions internal/provider/template.go
View file
Open in desktop
Expand Up @@ -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)
Expand All @@ -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 {
Expand Down Expand Up @@ -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

Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down