Sync open source content 🐝 (from aec61aed1f85c922410ed687e8862d21056e46bf)

Author: beezythebot

docs/terraform/resource-configuration.mdx

@@ -3,28 +3,88 @@ title: "Resource Configuration"
 description: "Learn how to customize a generated Terraform Provider resource, such as custom descriptions."
 ---
 
+import { Table } from "@/mdx/components";
+
 # Resource Configuration
 
-## Resource Description
+## Resource Documentation
+
+Speakeasy automatically generates provider and resource documentation that is compliant with the [public Terraform Registry requirements](https://developer.hashicorp.com/terraform/registry/providers/docs) via the HashiCorp-maintained [`terraform-plugin-docs`](https://github.com/hashicorp/terraform-plugin-docs) tool. Speakeasy runs `terraform-plugin-docs` at the end of successful generations or manually run via `go generate ./...`.
+
+The public Terraform Registry and `terraform-plugin-docs` tool both follow specific file layout conventions.
+
+For resources, the following file conventions are used:
+
+<Table
+  data={[
+    {
+      fileConvention: "docs/data-sources/{name}.md",
+      example: "docs/data-sources/order.md",
+      description: "Data resource documentation rendered in public Terraform Registry.",
+      generatedBy: "terraform-plugin-docs",
+    },
+    {
+      fileConvention: "docs/resources/{name}.md",
+      example: "docs/resources/order.md",
+      description: "Managed resource documentation rendered in public Terraform Registry.",
+      generatedBy: "terraform-plugin-docs",
+    },
+    {
+      fileConvention: "examples/data-sources/{type}/data-source.tf",
+      example: "examples/data-sources/example_order/data-source.tf",
+      description: "Data resource example configuration added to documentation page.",
+      generatedBy: "Speakeasy",
+    },
+    {
+      fileConvention: "examples/resources/{type}/import.sh",
+      example: "examples/resources/example_order/import.sh",
+      description: "Managed resource terraform import CLI command added to documentation page.",
+      generatedBy: "Speakeasy",
+    },
+    {
+      fileConvention: "examples/resources/{type}/resource.tf",
+      example: "examples/resources/example_order/resource.tf",
+      description: "Managed resource example configuration added to documentation page.",
+      generatedBy: "Speakeasy",
+    },
+  ]}
+  columns={[
+    { key: "fileConvention", header: "File Convention" },
+    { key: "example", header: "Example" },
+    { key: "description", header: "Description" },
+    { key: "generatedBy", header: "Generated By" },
+  ]}
+/>
+
+The `terraform-plugin-docs` tool also supports its own advanced use case customization, such as custom templates. Refer to the [`terraform-plugin-docs` documentation](https://github.com/hashicorp/terraform-plugin-docs) for more information about those capabilities.
+
+### Resource Description
 
 The `x-speakeasy-entity-description` extension allows modification of the description of a Terraform data or managed resource. This is useful when augmenting the documentation in an OpenAPI specification with documentation for specific resources. This documentation is expected to be in Markdown format. Use this extension alongside the `x-speakeasy-entity` extension.
 
+In this example, an order managed resource will have `Manage a coffee order.` written as the description in the resource code for any consuming tools, including documentation written by `terraform-plugin-docs` into `docs/resources/order.md`:
+
 ```yaml
 components:
   schemas:
     Order:
       description: An order helps you make coffee
       x-speakeasy-entity: Order
       x-speakeasy-entity-description: |
-        The order resource allows you to declaratively construct an order for coffee.
-
-        resource "speakeasy_order" "example" {
-          name = "Filter Blend"
-          price = 11.5
-        }
+        Manage a coffee order.
 ```
 
-Alternatively, a template folder can be written to customize any or all aspects of generated documentation in alignment with [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs).
+### Resource Example
+
+Example resource configuration is based on the OpenAPI Specification for API operation request and response data schemas. Speakeasy only generates example configuration for configurable properties. Example configuration values use the property `example` field when available or fallback to a generated value of the expected type following any `enum` or validation fields.
+
+Fully customize the example resource configuration by using Speakeasy [code customization capabilities](/docs/customize/code/monkey-patching).
+
+For example, to manually manage and update the example configuration for a managed resource:
+
+* Edit root directory `.genignore` file with an entry for `examples/resources/{type}/resource.tf`
+* Edit `examples/resources/{type}/resource.tf` as necessary
+* Run `go generate ./...` or Speakeasy generation to update `docs/resources/{name}.md`
 
 ## Resource Version