Fix incorrect rendering of example and import files for providers with no templates or fallback templates

.changes/unreleased/BUG FIXES-20231121-150034.yaml

@@ -0,0 +1,6 @@
+kind: BUG FIXES
+body: 'generate: fix incorrect rendering of example and import files for providers
+  with no docs templates or with generic fallback templates.'
+time: 2023-11-21T15:00:34.216261-05:00
+custom:
+  Issue: "300"

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar

@@ -20,13 +20,11 @@ compiling provider "scaffolding"
 using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
 running terraform init
 getting provider schema
-rendering missing docs
+generating missing templates
 generating missing resource content
-resource "scaffolding_example" fallback template exists
-generating template for "scaffolding_example"
+resource "scaffolding_example" fallback template exists, creating template
 generating missing data source content
-resource "scaffolding_example" fallback template exists
-generating template for "scaffolding_example"
+data-source "scaffolding_example" fallback template exists, creating template
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website
@@ -78,11 +76,7 @@ printf codefile:
 printf tffile:
 ## Example Usage
 
-```terraform
-data "scaffolding_example" "example" {
-  configurable_attribute = "some-value"
-}
-```
+{{tffile "$WORK/examples/data-sources/scaffolding_example/data-source.tf"}}
 
 codefile:
 
@@ -182,18 +176,12 @@ printf codefile:
 
 Import is supported using the following syntax:
 
-```shell
-terraform import scaffolding_example.example
-```
+{{codefile "shell" "$WORK/examples/resources/scaffolding_example/import.sh"}}
 
 printf tffile:
 ## Example Usage
 
-```terraform
-resource "scaffolding_example" "example" {
-  configurable_attribute = "some-value"
-}
-```
+{{tffile "$WORK/examples/resources/scaffolding_example/resource.tf"}}
 
 codefile:
 ## Import

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar

@@ -20,11 +20,11 @@ compiling provider "scaffolding"
 using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
 running terraform init
 getting provider schema
-rendering missing docs
+generating missing templates
 generating missing resource content
 resource "scaffolding_example" template exists, skipping
 generating missing data source content
-resource "scaffolding_example" template exists, skipping
+data-source "scaffolding_example" template exists, skipping
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar

@@ -18,13 +18,13 @@ compiling provider "scaffolding"
 using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
 running terraform init
 getting provider schema
-rendering missing docs
+generating missing templates
 generating missing resource content
-generating template for "scaffolding_example"
+generating new template for "scaffolding_example"
 generating missing data source content
-generating template for "scaffolding_example"
+generating new template for data-source "scaffolding_example"
 generating missing provider content
-generating template for "terraform-provider-scaffolding"
+generating new template for "terraform-provider-scaffolding"
 rendering static website
 cleaning rendered website dir
 rendering templated website to static markdown

cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar

@@ -17,13 +17,11 @@ compiling provider "null"
 using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
 running terraform init
 getting provider schema
-rendering missing docs
+generating missing templates
 generating missing resource content
-resource "null_resource" fallback template exists
-generating template for "null_resource"
+resource "null_resource" fallback template exists, creating template
 generating missing data source content
-resource "null_data_source" fallback template exists
-generating template for "null_data_source"
+data-source "null_data_source" fallback template exists, creating template
 generating missing provider content
 provider "terraform-provider-null" template exists, skipping
 rendering static website

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar

@@ -15,13 +15,11 @@ rendering website for provider "terraform-provider-scaffolding" (as "terraform-p
 copying any existing content to tmp dir
 exporting schema from JSON file
 getting provider schema
-rendering missing docs
+generating missing templates
 generating missing resource content
-resource "scaffolding_example" fallback template exists
-generating template for "scaffolding_example"
+resource "scaffolding_example" fallback template exists, creating template
 generating missing data source content
-resource "scaffolding_example" fallback template exists
-generating template for "scaffolding_example"
+data-source "scaffolding_example" fallback template exists, creating template
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website
@@ -73,11 +71,7 @@ printf codefile:
 printf tffile:
 ## Example Usage
 
-```terraform
-data "scaffolding_example" "example" {
-  configurable_attribute = "some-value"
-}
-```
+{{tffile "$WORK/examples/data-sources/scaffolding_example/data-source.tf"}}
 
 codefile:
 
@@ -177,18 +171,12 @@ printf codefile:
 
 Import is supported using the following syntax:
 
-```shell
-terraform import scaffolding_example.example
-```
+{{codefile "shell" "$WORK/examples/resources/scaffolding_example/import.sh"}}
 
 printf tffile:
 ## Example Usage
 
-```terraform
-resource "scaffolding_example" "example" {
-  configurable_attribute = "some-value"
-}
-```
+{{tffile "$WORK/examples/resources/scaffolding_example/resource.tf"}}
 
 codefile:
 ## Import

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_legacy_docs.txtar

@@ -0,0 +1,210 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+# Successful run of tfplugindocs on a Framework provider with docs in the legacy directory structure (i.e. r/<resource name>.md.tmpl)
+[!unix] skip
+exec tfplugindocs --provider-name=terraform-provider-scaffolding --providers-schema=schema.json
+cmp stdout expected-output.txt
+
+# Check that static files copied successfully to rendered docs directory
+cmp templates/r/example.md docs/r/example.md
+cmp templates/r/example.markdown docs/r/example.markdown
+cmp templates/r/example.html.markdown docs/r/example.html.markdown
+cmp templates/r/example.html.md docs/r/example.html.md
+
+cmp templates/d/example.md docs/d/example.md
+cmp templates/d/example.markdown docs/d/example.markdown
+cmp templates/d/example.html.markdown docs/d/example.html.markdown
+cmp templates/d/example.html.md docs/d/example.html.md
+
+cmp templates/index.md docs/index.md
+cmp templates/index.markdown docs/index.markdown
+cmp templates/index.html.markdown docs/index.html.markdown
+cmp templates/index.html.md docs/index.html.md
+-- expected-output.txt --
+rendering website for provider "terraform-provider-scaffolding" (as "terraform-provider-scaffolding")
+copying any existing content to tmp dir
+exporting schema from JSON file
+getting provider schema
+generating missing templates
+generating missing resource content
+resource "scaffolding_example" static file exists, skipping
+generating missing data source content
+data-source "scaffolding_example" static file exists, skipping
+generating missing provider content
+provider "terraform-provider-scaffolding" static file exists, skipping
+rendering static website
+cleaning rendered website dir
+rendering templated website to static markdown
+copying non-template file: "d/example.html.markdown"
+copying non-template file: "d/example.html.md"
+copying non-template file: "d/example.markdown"
+copying non-template file: "d/example.md"
+copying non-template file: "index.html.markdown"
+copying non-template file: "index.html.md"
+copying non-template file: "index.markdown"
+copying non-template file: "index.md"
+copying non-template file: "r/example.html.markdown"
+copying non-template file: "r/example.html.md"
+copying non-template file: "r/example.markdown"
+copying non-template file: "r/example.md"
+-- templates/r/example.md --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/r/example.markdown --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/r/example.html.markdown --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/r/example.html.md --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/d/example.md --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/d/example.markdown --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/d/example.html.markdown --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/d/example.html.md --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/index.md --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/index.markdown --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/index.html.markdown --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- templates/index.html.md --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+-- examples/README.md --
+# Examples
+
+This directory contains examples that are mostly used for documentation, but can also be run/tested manually via the Terraform CLI.
+
+The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or ar testable even if some parts are not relevant for the documentation.
+
+* **provider/provider.tf** example file for the provider index page
+* **data-sources/`full data source name`/data-source.tf** example file for the named data source page
+* **resources/`full resource name`/resource.tf** example file for the named data source page
+-- examples/data-sources/scaffolding_example/data-source.tf --
+data "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
+-- examples/provider/provider.tf --
+provider "scaffolding" {
+  # example configuration here
+}
+-- examples/resources/scaffolding_example/resource.tf --
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
+-- examples/resources/scaffolding_example/import.sh --
+terraform import scaffolding_example.example
+-- schema.json --
+{
+  "format_version": "1.0",
+  "provider_schemas": {
+    "registry.terraform.io/hashicorp/scaffolding": {
+      "provider": {
+        "version": 0,
+        "block": {
+          "attributes": {
+            "endpoint": {
+              "type": "string",
+              "description": "Example provider attribute",
+              "description_kind": "markdown",
+              "optional": true
+            }
+          },
+          "description": "Example provider",
+          "description_kind": "markdown"
+        }
+      },
+      "resource_schemas": {
+        "scaffolding_example": {
+          "version": 0,
+          "block": {
+            "attributes": {
+              "configurable_attribute": {
+                "type": "string",
+                "description": "Example configurable attribute",
+                "description_kind": "markdown",
+                "optional": true
+              },
+              "defaulted": {
+                "type": "string",
+                "description": "Example configurable attribute with default value",
+                "description_kind": "markdown",
+                "optional": true,
+                "computed": true
+              },
+              "id": {
+                "type": "string",
+                "description": "Example identifier",
+                "description_kind": "markdown",
+                "computed": true
+              }
+            },
+            "description": "Example resource",
+            "description_kind": "markdown"
+          }
+        }
+      },
+      "data_source_schemas": {
+        "scaffolding_example": {
+          "version": 0,
+          "block": {
+            "attributes": {
+              "configurable_attribute": {
+                "type": "string",
+                "description": "Example configurable attribute",
+                "description_kind": "markdown",
+                "optional": true
+              },
+              "id": {
+                "type": "string",
+                "description": "Example identifier",
+                "description_kind": "markdown",
+                "computed": true
+              }
+            },
+            "description": "Example data source",
+            "description_kind": "markdown"
+          }
+        }
+      }
+    }
+  }
+}

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar

@@ -15,11 +15,11 @@ rendering website for provider "terraform-provider-scaffolding" (as "terraform-p
 copying any existing content to tmp dir
 exporting schema from JSON file
 getting provider schema
-rendering missing docs
+generating missing templates
 generating missing resource content
 resource "scaffolding_example" template exists, skipping
 generating missing data source content
-resource "scaffolding_example" template exists, skipping
+data-source "scaffolding_example" template exists, skipping
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website