From c3ba333e39ffb60d1817299e31d4e852447817a6 Mon Sep 17 00:00:00 2001 From: Jacob Bednarz Date: Mon, 20 Jun 2022 12:09:01 +1000 Subject: [PATCH 1/3] cmd/generate: allow `HasExample` and `HasImport` to function When building custom templates, we have `HasExample`[1] and `HasImport`[2] available that return a boolean value and allow templates to include conditionals. Some uses of this would be to only show either an example or import line should the files exist. However, when we are calling these for templates both data-sources and resources only pass in an empty string[3] resulting in the value always returning `false`[4]. This appears to be an oversight as the non-customisable render template call site correctly passes in the values[5] of these paths and the template expression renders. [1]: https://github.com/hashicorp/terraform-plugin-docs/blob/6e1a3339859e55625941bcef8ab365552235ca3b/internal/provider/template.go#L137 [2]: https://github.com/hashicorp/terraform-plugin-docs/blob/6e1a3339859e55625941bcef8ab365552235ca3b/internal/provider/template.go#L140 [3]: https://github.com/hashicorp/terraform-plugin-docs/blob/6e1a3339859e55625941bcef8ab365552235ca3b/internal/provider/generate.go#L420 [4]: https://github.com/hashicorp/terraform-plugin-docs/blob/e52e735a834db7cdbd980cc817989588c77d96d4/internal/provider/template.go#L198 [5]: https://github.com/hashicorp/terraform-plugin-docs/blob/6e1a3339859e55625941bcef8ab365552235ca3b/internal/provider/generate.go##L258 --- internal/provider/generate.go | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/internal/provider/generate.go b/internal/provider/generate.go index f9fed5f8..7641fd22 100644 --- a/internal/provider/generate.go +++ b/internal/provider/generate.go @@ -415,9 +415,10 @@ func (g *generator) renderStaticWebsite(providerName string, providerSchema *tfj switch relDir { case "data-sources/": resSchema, resName := resourceSchema(providerSchema.DataSourceSchemas, shortName, relFile) + exampleFilePath := filepath.Join(g.examplesDir, "data-sources", resName, "data-source.tf") if resSchema != nil { tmpl := resourceTemplate(tmplData) - render, err := tmpl.Render(resName, providerName, g.renderedProviderName, "Data Source", "", "", resSchema) + render, err := tmpl.Render(resName, providerName, g.renderedProviderName, "Data Source", exampleFilePath, "", resSchema) if err != nil { return fmt.Errorf("unable to render data source template %q: %w", rel, err) } @@ -430,9 +431,12 @@ func (g *generator) renderStaticWebsite(providerName string, providerSchema *tfj g.warnf("data source entitled %q, or %q does not exist", shortName, resName) case "resources/": resSchema, resName := resourceSchema(providerSchema.ResourceSchemas, shortName, relFile) + exampleFilePath := filepath.Join(g.examplesDir, "resources", resName, "resource.tf") + importFilePath := filepath.Join(g.examplesDir, "resources", resName, "import.sh") + if resSchema != nil { tmpl := resourceTemplate(tmplData) - render, err := tmpl.Render(resName, providerName, g.renderedProviderName, "Resource", "", "", resSchema) + render, err := tmpl.Render(resName, providerName, g.renderedProviderName, "Resource", exampleFilePath, importFilePath, resSchema) if err != nil { return fmt.Errorf("unable to render resource template %q: %w", rel, err) } @@ -446,7 +450,8 @@ func (g *generator) renderStaticWebsite(providerName string, providerSchema *tfj case "": // provider if relFile == "index.md.tmpl" { tmpl := providerTemplate(tmplData) - render, err := tmpl.Render(providerName, g.renderedProviderName, "", providerSchema.ConfigSchema) + exampleFilePath := filepath.Join(g.examplesDir, "provider", "provider.tf") + render, err := tmpl.Render(providerName, g.renderedProviderName, exampleFilePath, providerSchema.ConfigSchema) if err != nil { return fmt.Errorf("unable to render provider template %q: %w", rel, err) } From 493f4ff9a1185e7e1d39e38dd25bfac5054a3b6b Mon Sep 17 00:00:00 2001 From: Ivan De Marino Date: Thu, 23 Jun 2022 11:19:27 +0100 Subject: [PATCH 2/3] Improved documentation of paths for templates and examples, in README --- README.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 93300f50..8701ef24 100644 --- a/README.md +++ b/README.md @@ -44,20 +44,30 @@ Otherwise, the provider developer can set an arbitrary description like this: ### Conventional Paths -The generation of missing documentation is based on a number of assumptions / conventional paths: +The generation of missing documentation is based on a number of assumptions / conventional paths. + +For templates: | Path | Description | |-----------------------------------------------------------|----------------------------------------| | `templates/` | Root of templated docs | | `templates/index.md[.tmpl]` | Docs index page (or template) | -| `examples/provider/provider.tf` | Provider example config* | | `templates/data-sources.md[.tmpl]` | Generic data source page (or template) | | `templates/data-sources/.md[.tmpl]` | Data source page (or template) | -| `examples/data-sources//data-source.tf` | Data source example config* | | `templates/resources.md[.tmpl]` | Generic resource page (or template) | | `templates/resources/.md[.tmpl]` | Resource page (or template) | -| `examples/resources//resource.tf` | Resource example config* | -| `examples/resources//import.sh` | Resource example import command | + +Note: the `.tmpl` extension is necessary, for the file to be correctly handled as a template. + +For examples: + +| Path | Description | +|-----------------------------------------------------------|---------------------------------| +| `examples/` | Root of examples | +| `examples/provider/provider.tf` | Provider example config | +| `examples/data-sources//data-source.tf` | Data source example config | +| `examples/resources//resource.tf` | Resource example config | +| `examples/resources//import.sh` | Resource example import command | ### Templates From df94c862c52d5b829302549778ad4e8e3acd7dd1 Mon Sep 17 00:00:00 2001 From: Jacob Bednarz Date: Fri, 24 Jun 2022 06:06:26 +1000 Subject: [PATCH 3/3] add CHANGELOG entry --- CHANGELOG.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 73b1e5b5..9cc8e495 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +# 0.10.2 (Unreleased) + +BUG FIXES: + +* cmd/tfplugindocs: Pass through filepaths for `examples` and `import` to allow use of `HasExample` and `HasImport` template helpers in custom templates ([#155](https://github.com/hashicorp/terraform-plugin-docs/pull/155)). + # 0.10.1 (June 14, 2022) BUG FIXES: