Generate: Use rendered provider name instead of provider name in default templates (#492)

* Update the default provider, resource, and function templates to use `.RenderedProviderName` instead of `.ProviderName`

* Update Readme

* Update Readme

* Add changelog entries

* Fix tests

* Sort schema keys when generating missing templates to ensure deterministic stdout.

Author: SBGoods

.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"

.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"

README.md

@@ -68,7 +68,7 @@ Usage: tfplugindocs generate [<args>]
     --provider-dir <ARG>             relative or absolute path to the root provider code directory when running the command outside the root provider code directory
     --provider-name <ARG>            provider name, as used in Terraform configurations; defaults to the --provider-dir short name (after removing `terraform-provider-` prefix)
     --providers-schema <ARG>         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 <ARG>   provider name, as generated in documentation (ex. page titles, ...)
+    --rendered-provider-name <ARG>   provider name, as generated in documentation (ex. page titles, ...); defaults to the --provider-name
     --rendered-website-dir <ARG>     output directory based on provider-dir                                                                                             (default: "docs")
     --tf-version <ARG>               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 <ARG>       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                                        |

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/<resource name>.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 generated by tfplugindocs -->
 ## 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: <!-- signature generated by tfplugindocs -->
 ```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 generated by tfplugindocs -->
 ## 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 generated by tfplugindocs -->
 ## 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 generated by tfplugindocs -->
 ## Schema
 

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

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
 		}

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 "  " }}