diff --git a/.changes/unreleased/BREAKING CHANGES-20250613-135104.yaml b/.changes/unreleased/BREAKING CHANGES-20250613-135104.yaml new file mode 100644 index 0000000..ddef526 --- /dev/null +++ b/.changes/unreleased/BREAKING CHANGES-20250613-135104.yaml @@ -0,0 +1,6 @@ +kind: BREAKING CHANGES +body: 'generate: The `.ProviderShortName` template function now uses the rendered provider name to derive the provider short name. Users that pass in the +`--rendered-provider-name` flag might see a different output for this function' +time: 2025-06-13T13:51:04.745115-04:00 +custom: + Issue: "492" diff --git a/.changes/unreleased/ENHANCEMENTS-20250613-134814.yaml b/.changes/unreleased/ENHANCEMENTS-20250613-134814.yaml new file mode 100644 index 0000000..271fcd9 --- /dev/null +++ b/.changes/unreleased/ENHANCEMENTS-20250613-134814.yaml @@ -0,0 +1,5 @@ +kind: ENHANCEMENTS +body: 'generate: Default resource and function templates now use `.RenderedProviderName` instead of `.ProviderName`' +time: 2025-06-13T13:48:14.705452-04:00 +custom: + Issue: "492" diff --git a/README.md b/README.md index 1a6bedb..c9fb2a0 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ Usage: tfplugindocs generate [] --provider-dir relative or absolute path to the root provider code directory when running the command outside the root provider code directory --provider-name provider name, as used in Terraform configurations; defaults to the --provider-dir short name (after removing `terraform-provider-` prefix) --providers-schema path to the providers schema JSON file, which contains the output of the terraform providers schema -json command. Setting this flag will skip building the provider and calling Terraform CLI - --rendered-provider-name provider name, as generated in documentation (ex. page titles, ...) + --rendered-provider-name provider name, as generated in documentation (ex. page titles, ...); defaults to the --provider-name --rendered-website-dir output directory based on provider-dir (default: "docs") --tf-version terraform binary version to download. If not provided, will look for a terraform binary in the local environment. If not found in the environment, will download the latest version of Terraform --website-source-dir templates directory based on provider-dir (default: "templates") @@ -286,7 +286,7 @@ using the following data fields and functions: | `.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`) | +| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) | | `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` | | `.SchemaMarkdown` | string | a Markdown formatted Provider Schema definition | @@ -302,7 +302,7 @@ using the following data fields and functions: | `.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`) | +| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) | | `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` | | `.SchemaMarkdown` | string | a Markdown formatted Resource / Data Source Schema definition | @@ -317,7 +317,7 @@ using the following data fields and functions: | `.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`) | +| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) | | `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` | | `.FunctionSignatureMarkdown` | string | a Markdown formatted Function signature | | `.FunctionArgumentsMarkdown` | string | a Markdown formatted Function arguments definition | diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar index 50d254e..e90405e 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar @@ -4,7 +4,7 @@ # Successful run of tfplugindocs on a Framework provider with "named" template paths (i.e. templates/resources/.md.tmpl) # Templates test all implemented data fields and functions. [!unix] skip -exec tfplugindocs --provider-name=terraform-provider-scaffolding --providers-schema=schema.json +exec tfplugindocs --provider-name=terraform-provider-scaffolding --providers-schema=schema.json --rendered-provider-name=Scaffolding cmp stdout expected-output.txt cmpenv docs/index.md expected-index.md cmpenv docs/data-sources/example.md expected-datasource.md @@ -13,7 +13,7 @@ cmpenv docs/functions/example.md expected-function.md cmpenv docs/ephemeral-resources/example.md expected-ephemeral-resource.md -- expected-output.txt -- -rendering website for provider "terraform-provider-scaffolding" (as "terraform-provider-scaffolding") +rendering website for provider "terraform-provider-scaffolding" (as "Scaffolding") copying any existing content to tmp dir exporting schema from JSON file getting provider schema @@ -46,8 +46,8 @@ HasExample: true ExampleFile: $WORK/examples/data-sources/scaffolding_example/data-source.tf HasImport: false ProviderName: terraform-provider-scaffolding -ProviderShortName: scaffolding -RenderedProviderName: terraform-provider-scaffolding +ProviderShortName: Scaffolding +RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema @@ -102,8 +102,8 @@ Summary: Echo a string HasExample: true ExampleFile: $WORK/examples/functions/example/function.tf ProviderName: terraform-provider-scaffolding -ProviderShortName: scaffolding -RenderedProviderName: terraform-provider-scaffolding +ProviderShortName: Scaffolding +RenderedProviderName: Scaffolding FunctionSignatureMarkdown: ```text example(input string, variadicInput string...) string @@ -146,8 +146,8 @@ Description: Example provider HasExample: true ExampleFile: $WORK/examples/provider/provider.tf ProviderName: terraform-provider-scaffolding -ProviderShortName: scaffolding -RenderedProviderName: terraform-provider-scaffolding +ProviderShortName: Scaffolding +RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema @@ -193,8 +193,8 @@ ExampleFile: $WORK/examples/resources/scaffolding_example/resource.tf HasImport: true ImportFile: $WORK/examples/resources/scaffolding_example/import.sh ProviderName: terraform-provider-scaffolding -ProviderShortName: scaffolding -RenderedProviderName: terraform-provider-scaffolding +ProviderShortName: Scaffolding +RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema @@ -260,8 +260,8 @@ HasExample: true ExampleFile: $WORK/examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf HasImport: false ProviderName: terraform-provider-scaffolding -ProviderShortName: scaffolding -RenderedProviderName: terraform-provider-scaffolding +ProviderShortName: Scaffolding +RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar index ba8e1bf..04f2bcc 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar @@ -3,7 +3,7 @@ # Successful run of tfplugindocs on a Framework provider with examples but no templates or pre-exiting docs. [!unix] skip -exec tfplugindocs --provider-name=terraform-provider-scaffolding --providers-schema=schema.json +exec tfplugindocs --provider-name=terraform-provider-scaffolding --providers-schema=schema.json --rendered-provider-name=Scaffolding cmp stdout expected-output.txt cmp docs/index.md expected-index.md cmp docs/data-sources/example.md expected-datasource.md @@ -13,7 +13,7 @@ cmp docs/functions/no-variadic.md expected-no-variadic-function.md cmp docs/ephemeral-resources/example.md expected-ephemeral-resource.md -- expected-output.txt -- -rendering website for provider "terraform-provider-scaffolding" (as "terraform-provider-scaffolding") +rendering website for provider "terraform-provider-scaffolding" (as "Scaffolding") exporting schema from JSON file getting provider schema generating missing templates @@ -40,7 +40,7 @@ rendering "resources/example.md.tmpl" -- expected-datasource.md -- --- # generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "scaffolding_example Data Source - terraform-provider-scaffolding" +page_title: "scaffolding_example Data Source - Scaffolding" subcategory: "" description: |- Example data source @@ -71,7 +71,7 @@ data "scaffolding_example" "example" { -- expected-function.md -- --- # generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "example function - terraform-provider-scaffolding" +page_title: "example function - Scaffolding" subcategory: "" description: |- Echo a string @@ -105,7 +105,7 @@ example(input string, variadicInput string...) string -- expected-no-variadic-function.md -- --- # generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "no-variadic function - terraform-provider-scaffolding" +page_title: "no-variadic function - Scaffolding" subcategory: "" description: |- Echo a string @@ -137,12 +137,12 @@ no-variadic(input string) string -- expected-index.md -- --- # generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "scaffolding Provider" +page_title: "Scaffolding Provider" description: |- Example provider --- -# scaffolding Provider +# Scaffolding Provider Example provider @@ -163,7 +163,7 @@ provider "scaffolding" { -- expected-resource.md -- --- # generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "scaffolding_example Resource - terraform-provider-scaffolding" +page_title: "scaffolding_example Resource - Scaffolding" subcategory: "" description: |- Example resource @@ -195,7 +195,7 @@ resource "scaffolding_example" "example" { -- expected-ephemeral-resource.md -- --- # generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "scaffolding_example Ephemeral Resource - terraform-provider-scaffolding" +page_title: "scaffolding_example Ephemeral Resource - Scaffolding" subcategory: "" description: |- Example ephemeral resource diff --git a/internal/provider/generate.go b/internal/provider/generate.go index 7df7b63..3b814b8 100644 --- a/internal/provider/generate.go +++ b/internal/provider/generate.go @@ -10,6 +10,7 @@ import ( "os/exec" "path/filepath" "runtime" + "sort" "strings" "github.com/hashicorp/cli" @@ -443,7 +444,16 @@ func (g *generator) generateMissingProviderTemplate() error { func (g *generator) generateMissingTemplates(providerSchema *tfjson.ProviderSchema) error { g.infof("generating missing resource content") - for name, schema := range providerSchema.ResourceSchemas { + + resourceKeys := make([]string, 0, len(providerSchema.ResourceSchemas)) + for key := range providerSchema.ResourceSchemas { + resourceKeys = append(resourceKeys, key) + } + sort.Strings(resourceKeys) + + for _, name := range resourceKeys { + schema := providerSchema.ResourceSchemas[name] + if g.ignoreDeprecated && schema.Block.Deprecated { continue } @@ -455,7 +465,16 @@ func (g *generator) generateMissingTemplates(providerSchema *tfjson.ProviderSche } g.infof("generating missing data source content") - for name, schema := range providerSchema.DataSourceSchemas { + + dataSourceKeys := make([]string, 0, len(providerSchema.DataSourceSchemas)) + for key := range providerSchema.DataSourceSchemas { + dataSourceKeys = append(dataSourceKeys, key) + } + sort.Strings(dataSourceKeys) + + for _, name := range dataSourceKeys { + schema := providerSchema.DataSourceSchemas[name] + if g.ignoreDeprecated && schema.Block.Deprecated { continue } @@ -467,7 +486,16 @@ func (g *generator) generateMissingTemplates(providerSchema *tfjson.ProviderSche } g.infof("generating missing function content") - for name, signature := range providerSchema.Functions { + + functionKeys := make([]string, 0, len(providerSchema.Functions)) + for key := range providerSchema.Functions { + functionKeys = append(functionKeys, key) + } + sort.Strings(functionKeys) + + for _, name := range functionKeys { + signature := providerSchema.Functions[name] + if g.ignoreDeprecated && signature.DeprecationMessage != "" { continue } @@ -479,7 +507,16 @@ func (g *generator) generateMissingTemplates(providerSchema *tfjson.ProviderSche } g.infof("generating missing ephemeral resource content") - for name, schema := range providerSchema.EphemeralResourceSchemas { + + ephemeralKeys := make([]string, 0, len(providerSchema.EphemeralResourceSchemas)) + for key := range providerSchema.EphemeralResourceSchemas { + ephemeralKeys = append(ephemeralKeys, key) + } + sort.Strings(ephemeralKeys) + + for _, name := range ephemeralKeys { + schema := providerSchema.EphemeralResourceSchemas[name] + if g.ignoreDeprecated && schema.Block.Deprecated { continue } diff --git a/internal/provider/template.go b/internal/provider/template.go index ab3bb66..2be400e 100644 --- a/internal/provider/template.go +++ b/internal/provider/template.go @@ -150,7 +150,7 @@ func (t providerTemplate) Render(providerDir, providerName, renderedProviderName ExampleFile: exampleFile, ProviderName: providerName, - ProviderShortName: providerShortName(providerName), + ProviderShortName: providerShortName(renderedProviderName), SchemaMarkdown: schemaComment + "\n" + schemaBuffer.String(), @@ -199,7 +199,7 @@ func (t resourceTemplate) Render(providerDir, name, providerName, renderedProvid ImportFile: importFile, ProviderName: providerName, - ProviderShortName: providerShortName(providerName), + ProviderShortName: providerShortName(renderedProviderName), SchemaMarkdown: schemaComment + "\n" + schemaBuffer.String(), @@ -257,7 +257,7 @@ func (t functionTemplate) Render(providerDir, name, providerName, renderedProvid ExampleFile: exampleFile, ProviderName: providerName, - ProviderShortName: providerShortName(providerName), + ProviderShortName: providerShortName(renderedProviderName), FunctionSignatureMarkdown: signatureComment + "\n" + funcSig, FunctionArgumentsMarkdown: argumentComment + "\n" + funcArgs, @@ -271,7 +271,7 @@ func (t functionTemplate) Render(providerDir, name, providerName, renderedProvid const defaultResourceTemplate resourceTemplate = `--- ` + frontmatterComment + ` -page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +page_title: "{{.Name}} {{.Type}} - {{.RenderedProviderName}}" subcategory: "" description: |- {{ .Description | plainmarkdown | trimspace | prefixlines " " }} @@ -300,7 +300,7 @@ Import is supported using the following syntax: const defaultFunctionTemplate functionTemplate = `--- ` + frontmatterComment + ` -page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +page_title: "{{.Name}} {{.Type}} - {{.RenderedProviderName}}" subcategory: "" description: |- {{ .Summary | plainmarkdown | trimspace | prefixlines " " }}