From af14120aa155379dba3669b0fb00aa7d133a9d56 Mon Sep 17 00:00:00 2001 From: Toni Kangas Date: Mon, 29 Apr 2024 16:22:27 +0300 Subject: [PATCH 1/5] Render blocks without specifying if they are required or optional This avoids all blocks being rendered as optional in resources implemented with terraform-plugin-framework. --- internal/schemamd/behaviors.go | 7 +++++++ internal/schemamd/render.go | 5 +++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/internal/schemamd/behaviors.go b/internal/schemamd/behaviors.go index 26a60c92..b8dfaa5f 100644 --- a/internal/schemamd/behaviors.go +++ b/internal/schemamd/behaviors.go @@ -95,6 +95,13 @@ func childBlockContainsWriteOnly(block *tfjson.SchemaBlockType) bool { return true } } + return false +} + +func childBlockIsWritable(block *tfjson.SchemaBlockType) bool { + return !childBlockIsReadOnly(block) +} +func omitChild[T *tfjson.SchemaAttribute | *tfjson.SchemaBlockType](_ T) bool { return false } diff --git a/internal/schemamd/render.go b/internal/schemamd/render.go index 0dd2ec3d..1000982b 100644 --- a/internal/schemamd/render.go +++ b/internal/schemamd/render.go @@ -183,8 +183,9 @@ var ( // * Optional // * Read-Only groupFilters = []groupFilter{ - {"### Required", "Required:", childAttributeIsRequired, childBlockIsRequired}, - {"### Optional", "Optional:", childAttributeIsOptional, childBlockIsOptional}, + {"### Required Attributes", "Required Attributes:", childAttributeIsRequired, omitChild[*tfjson.SchemaBlockType]}, + {"### Optional Attributes", "Optional Attributes:", childAttributeIsOptional, omitChild[*tfjson.SchemaBlockType]}, + {"### Blocks", "Blocks:", omitChild[*tfjson.SchemaAttribute], childBlockIsWritable}, {"### Read-Only", "Read-Only:", childAttributeIsReadOnly, childBlockIsReadOnly}, } ) From 88f58e02fe0a79ab38074ad32231ca12df72c62f Mon Sep 17 00:00:00 2001 From: Toni Kangas Date: Mon, 29 Apr 2024 16:22:34 +0300 Subject: [PATCH 2/5] Update testdata --- ...k_provider_success_generic_templates.txtar | 6 +- ...ork_provider_success_named_templates.txtar | 6 +- ...mework_provider_success_no_templates.txtar | 6 +- .../generate/null_provider_success.txtar | 12 +- ...provider_success_all_framework_types.txtar | 86 +++--- ...k_provider_success_generic_templates.txtar | 6 +- ...ork_provider_success_named_templates.txtar | 6 +- ...mework_provider_success_no_templates.txtar | 278 ++++++++++++++++++ .../generate/nested_id_attribute.txtar | 39 +-- .../generate/null_provider_success.txtar | 12 +- .../schemamd/testdata/aws_acm_certificate.md | 9 +- .../testdata/aws_route_table_association.md | 4 +- .../testdata/awscc_acmpca_certificate.md | 34 +-- .../schemamd/testdata/awscc_logs_log_group.md | 2 +- internal/schemamd/testdata/framework_types.md | 57 +++- 15 files changed, 443 insertions(+), 120 deletions(-) create mode 100644 cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar index 3119c8d0..148f38b5 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar @@ -53,7 +53,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute @@ -106,7 +106,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `endpoint` (String) Example provider attribute @@ -155,7 +155,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar index 6f833761..2f820264 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar @@ -53,7 +53,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute @@ -106,7 +106,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `endpoint` (String) Example provider attribute @@ -169,7 +169,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar index 382fd001..61b4c4f2 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar @@ -60,7 +60,7 @@ data "scaffolding_example" "example" { ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute @@ -90,7 +90,7 @@ provider "scaffolding" { ## Schema -### Optional +### Optional Attributes - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -117,7 +117,7 @@ resource "scaffolding_example" "example" { ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar index e7bf28a1..9fd7eed6 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar @@ -232,7 +232,7 @@ class MyConvertedCode(TerraformStack): ## Schema -### Optional +### Optional Attributes - `has_computed_default` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -343,7 +343,7 @@ class MyConvertedCode(TerraformStack): ## Schema -### Optional +### Optional Attributes - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. @@ -460,7 +460,7 @@ class MyConvertedCode extends TerraformStack { ## Schema -### Optional +### Optional Attributes - `hasComputedDefault` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -581,7 +581,7 @@ class MyConvertedCode extends TerraformStack { ## Schema -### Optional +### Optional Attributes - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. @@ -667,7 +667,7 @@ output "all_server_ips" { ## Schema -### Optional +### Optional Attributes - `has_computed_default` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -762,7 +762,7 @@ resource "null_resource" "cluster" { ## Schema -### Optional +### Optional Attributes - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar index 370a64a5..14168fdc 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar @@ -48,7 +48,7 @@ Example provider ## Schema -### Optional +### Optional Attributes - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -75,7 +75,7 @@ example resource - `required_write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example required write-only string attribute -### Optional +### Optional Attributes > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. @@ -83,8 +83,6 @@ example resource - `float64_attribute` (Number) example float64 attribute - `int64_attribute` (Number) example int64 attribute - `list_attribute` (List of String) example list attribute -- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) -- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `map_attribute` (Map of String) example map attribute - `number_attribute` (Number) example number attribute - `object_attribute` (Object) example object attribute (see [below for nested schema](#nestedatt--object_attribute)) @@ -99,48 +97,26 @@ example resource - `sensitive_set_attribute` (Set of String, Sensitive) example sensitive set attribute - `sensitive_string_attribute` (String, Sensitive) example sensitive string attribute - `set_attribute` (Set of String) example set attribute +- `string_attribute` (String) example string attribute +- `write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example write-only string attribute + +### Blocks + +- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) +- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) - `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) - `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) -- `string_attribute` (String) example string attribute -- `write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example write-only string attribute ### Read-Only - `id` (String) The ID of this resource. - `set_nested_block_sensitive_nested_attribute` (Block Set) example sensitive set nested block (see [below for nested schema](#nestedblock--set_nested_block_sensitive_nested_attribute)) - -### Nested Schema for `list_nested_block` - -Optional: - -- `list_nested_block_attribute` (String) example list nested block attribute -- `list_nested_block_attribute_with_default` (String) example list nested block attribute with default -- `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) - - -### Nested Schema for `list_nested_block.nested_list_block` - -Optional: - -- `nested_block_string_attribute` (String) example nested block string attribute - - - - -### Nested Schema for `list_nested_block_sensitive_nested_attribute` - -Optional: - -- `list_nested_block_attribute` (String) example list nested block attribute -- `list_nested_block_sensitive_attribute` (String, Sensitive) example sensitive list nested block attribute - - ### Nested Schema for `object_attribute` -Optional: +Optional Attributes: - `object_attribute_attribute` (String) @@ -148,7 +124,7 @@ Optional: ### Nested Schema for `object_attribute_with_nested_object_attribute` -Optional: +Optional Attributes: - `nested_object` (Object) (see [below for nested schema](#nestedobjatt--object_attribute_with_nested_object_attribute--nested_object)) - `object_attribute_attribute` (String) @@ -156,7 +132,7 @@ Optional: ### Nested Schema for `object_attribute_with_nested_object_attribute.nested_object` -Optional: +Optional Attributes: - `nested_object_attribute` (String) @@ -165,15 +141,45 @@ Optional: ### Nested Schema for `sensitive_object_attribute` -Optional: +Optional Attributes: - `object_attribute_attribute` (String) + +### Nested Schema for `list_nested_block` + +Optional Attributes: + +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_attribute_with_default` (String) example list nested block attribute with default + +Blocks: + +- `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) + + +### Nested Schema for `list_nested_block.nested_list_block` + +Optional Attributes: + +- `nested_block_string_attribute` (String) example nested block string attribute + + + + +### Nested Schema for `list_nested_block_sensitive_nested_attribute` + +Optional Attributes: + +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_sensitive_attribute` (String, Sensitive) example sensitive list nested block attribute + + ### Nested Schema for `set_nested_block` -Optional: +Optional Attributes: - `set_nested_block_attribute` (String) example set nested block attribute @@ -181,7 +187,7 @@ Optional: ### Nested Schema for `single_nested_block` -Optional: +Optional Attributes: - `single_nested_block_attribute` (String) example single nested block attribute @@ -189,7 +195,7 @@ Optional: ### Nested Schema for `single_nested_block_sensitive_nested_attribute` -Optional: +Optional Attributes: - `single_nested_block_attribute` (String) example single nested block attribute - `single_nested_block_sensitive_attribute` (String, Sensitive) example sensitive single nested block attribute diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar index a695740e..1cc3b236 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar @@ -222,7 +222,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute @@ -322,7 +322,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `endpoint` (String) Example provider attribute @@ -371,7 +371,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value 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 984c5011..a1c23f0d 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 @@ -221,7 +221,7 @@ RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute @@ -321,7 +321,7 @@ RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `endpoint` (String) Example provider attribute @@ -384,7 +384,7 @@ RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema -### Optional +### Optional Attributes - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value 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 new file mode 100644 index 00000000..e5b22e50 --- /dev/null +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar @@ -0,0 +1,278 @@ +# Copyright (c) HashiCorp, Inc. +# SPDX-License-Identifier: MPL-2.0 + +# 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 +cmp stdout expected-output.txt +cmp docs/index.md expected-index.md +cmp docs/data-sources/example.md expected-datasource.md +cmp docs/resources/example.md expected-resource.md +cmp docs/functions/example.md expected-function.md + +-- expected-output.txt -- +rendering website for provider "terraform-provider-scaffolding" (as "terraform-provider-scaffolding") +exporting schema from JSON file +getting provider schema +generating missing templates +generating missing resource content +generating new template for "scaffolding_example" +generating missing data source content +generating new template for data-source "scaffolding_example" +generating missing function content +generating new template for function "example" +generating missing provider content +generating new template for "terraform-provider-scaffolding" +rendering static website +cleaning rendered website dir +rendering templated website to static markdown +rendering "data-sources/example.md.tmpl" +rendering "functions/example.md.tmpl" +rendering "index.md.tmpl" +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" +subcategory: "" +description: |- + Example data source +--- + +# scaffolding_example (Data Source) + +Example data source + +## Example Usage + +```terraform +data "scaffolding_example" "example" { + configurable_attribute = "some-value" +} +``` + + +## Schema + +### Optional Attributes + +- `configurable_attribute` (String) Example configurable attribute + +### Read-Only + +- `id` (String) Example identifier +-- expected-function.md -- +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "example function - terraform-provider-scaffolding" +subcategory: "" +description: |- + Echo a string +--- + +# function: example + +Given a string value, returns the same value. + +## Example Usage + +```terraform +output "test" { + value = provider::scaffolding::example("testvalue1", "testvalue2") +} +``` + +## Signature + + +```text +example(input string, variadicInput string...) string +``` + +## Arguments + + +1. `input` (String) Value to echo. + +1. `variadicInput` (Variadic, String) Variadic input to echo. +-- expected-index.md -- +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "scaffolding Provider" +subcategory: "" +description: |- + Example provider +--- + +# scaffolding Provider + +Example provider + +## Example Usage + +```terraform +provider "scaffolding" { + # example configuration here +} +``` + + +## Schema + +### Optional Attributes + +- `endpoint` (String) Example provider attribute +-- expected-resource.md -- +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "scaffolding_example Resource - terraform-provider-scaffolding" +subcategory: "" +description: |- + Example resource +--- + +# scaffolding_example (Resource) + +Example resource + +## Example Usage + +```terraform +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} +``` + + +## Schema + +### Optional Attributes + +- `configurable_attribute` (String) Example configurable attribute +- `defaulted` (String) Example configurable attribute with default value + +### Read-Only + +- `id` (String) Example identifier +-- 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/functions/example/function.tf -- +output "test" { + value = provider::scaffolding::example("testvalue1", "testvalue2") +} +-- examples/provider/provider.tf -- +provider "scaffolding" { + # example configuration here +} +-- examples/resources/scaffolding_example/resource.tf -- +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} + +-- 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" + } + } + }, + "functions": { + "example": { + "description": "Given a string value, returns the same value.", + "summary": "Echo a string", + "return_type": "string", + "parameters": [ + { + "name": "input", + "description": "Value to echo.", + "type": "string" + } + ], + "variadic_parameter": { + "name": "variadicInput", + "description": "Variadic input to echo.", + "type": "string" + } + } + } + } + } +} \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar index 2ab41c10..b05b6cfd 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar @@ -45,7 +45,7 @@ Example provider ## Schema -### Optional +### Optional Attributes - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -66,15 +66,18 @@ example resource ## Schema -### Required +### Required Attributes - `required_object_attribute` (Object) example required object attribute (see [below for nested schema](#nestedatt--required_object_attribute)) -### Optional +### Optional Attributes + +- `optional_object_attribute` (Object) example optional object attribute (see [below for nested schema](#nestedatt--optional_object_attribute)) + +### Blocks - `list_nested_block_optional_id` (Block List) example list nested block with optional id attribute (see [below for nested schema](#nestedblock--list_nested_block_optional_id)) - `list_nested_block_required_id` (Block List) example list nested block with required id attribute (see [below for nested schema](#nestedblock--list_nested_block_required_id)) -- `optional_object_attribute` (Object) example optional object attribute (see [below for nested schema](#nestedatt--optional_object_attribute)) - `set_nested_block_optional_id` (Block Set) example set nested block with optional id attribute (see [below for nested schema](#nestedblock--set_nested_block_optional_id)) - `set_nested_block_required_id` (Block Set) example set nested block with required id attribute (see [below for nested schema](#nestedblock--set_nested_block_required_id)) - `single_nested_block_optional_id` (Block, Optional) example single nested block with optional id attribute (see [below for nested schema](#nestedblock--single_nested_block_optional_id)) @@ -91,31 +94,31 @@ example resource ### Nested Schema for `required_object_attribute` -Required: +Required Attributes: - `id` (String) - -### Nested Schema for `list_nested_block_optional_id` + +### Nested Schema for `optional_object_attribute` -Optional: +Optional Attributes: - `id` (String) - -### Nested Schema for `list_nested_block_required_id` + +### Nested Schema for `list_nested_block_optional_id` -Required: +Optional Attributes: - `id` (String) - -### Nested Schema for `optional_object_attribute` + +### Nested Schema for `list_nested_block_required_id` -Optional: +Required Attributes: - `id` (String) @@ -123,7 +126,7 @@ Optional: ### Nested Schema for `set_nested_block_optional_id` -Optional: +Optional Attributes: - `id` (String) @@ -131,7 +134,7 @@ Optional: ### Nested Schema for `set_nested_block_required_id` -Required: +Required Attributes: - `id` (String) @@ -139,7 +142,7 @@ Required: ### Nested Schema for `single_nested_block_optional_id` -Optional: +Optional Attributes: - `id` (String) @@ -147,7 +150,7 @@ Optional: ### Nested Schema for `single_nested_block_required_id` -Required: +Required Attributes: - `id` (String) diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar index 9a9b0db6..a8735b92 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar @@ -207,7 +207,7 @@ class MyConvertedCode(TerraformStack): ## Schema -### Optional +### Optional Attributes - `has_computed_default` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -318,7 +318,7 @@ class MyConvertedCode(TerraformStack): ## Schema -### Optional +### Optional Attributes - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. @@ -435,7 +435,7 @@ class MyConvertedCode extends TerraformStack { ## Schema -### Optional +### Optional Attributes - `hasComputedDefault` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -556,7 +556,7 @@ class MyConvertedCode extends TerraformStack { ## Schema -### Optional +### Optional Attributes - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. @@ -642,7 +642,7 @@ output "all_server_ips" { ## Schema -### Optional +### Optional Attributes - `has_computed_default` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -737,7 +737,7 @@ resource "null_resource" "cluster" { ## Schema -### Optional +### Optional Attributes - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. diff --git a/internal/schemamd/testdata/aws_acm_certificate.md b/internal/schemamd/testdata/aws_acm_certificate.md index 7ead0c69..4a666b3e 100644 --- a/internal/schemamd/testdata/aws_acm_certificate.md +++ b/internal/schemamd/testdata/aws_acm_certificate.md @@ -1,18 +1,21 @@ ## Schema -### Optional +### Optional Attributes - `certificate_authority_arn` (String) - `certificate_body` (String) - `certificate_chain` (String) - `domain_name` (String) -- `options` (Block List, Max: 1) (see [below for nested schema](#nestedblock--options)) - `private_key` (String, Sensitive) - `subject_alternative_names` (Set of String) - `tags` (Map of String) - `tags_all` (Map of String) - `validation_method` (String) +### Blocks + +- `options` (Block List, Max: 1) (see [below for nested schema](#nestedblock--options)) + ### Read-Only - `arn` (String) @@ -24,7 +27,7 @@ ### Nested Schema for `options` -Optional: +Optional Attributes: - `certificate_transparency_logging_preference` (String) diff --git a/internal/schemamd/testdata/aws_route_table_association.md b/internal/schemamd/testdata/aws_route_table_association.md index 279d6c19..78bc2641 100644 --- a/internal/schemamd/testdata/aws_route_table_association.md +++ b/internal/schemamd/testdata/aws_route_table_association.md @@ -1,10 +1,10 @@ ## Schema -### Required +### Required Attributes - `route_table_id` (String) -### Optional +### Optional Attributes - `gateway_id` (String) - `subnet_id` (String) diff --git a/internal/schemamd/testdata/awscc_acmpca_certificate.md b/internal/schemamd/testdata/awscc_acmpca_certificate.md index 73bc8880..2cbe1b5c 100644 --- a/internal/schemamd/testdata/awscc_acmpca_certificate.md +++ b/internal/schemamd/testdata/awscc_acmpca_certificate.md @@ -1,13 +1,13 @@ ## Schema -### Required +### Required Attributes - `certificate_authority_arn` (String) - `certificate_signing_request` (String) The certificate signing request (CSR) for the Certificate. - `signing_algorithm` (String) The name of the algorithm that will be used to sign the Certificate. - `validity` (Attributes) Validity for a certificate. (see [below for nested schema](#nestedatt--validity)) -### Optional +### Optional Attributes - `api_passthrough` (Attributes) Structure that specifies fields to be overridden in a certificate at the time of issuance. These requires an API Passthrough template be used or they will be ignored. (see [below for nested schema](#nestedatt--api_passthrough)) - `template_arn` (String) @@ -22,7 +22,7 @@ ### Nested Schema for `validity` -Required: +Required Attributes: - `type` (String) - `value` (Number) @@ -31,7 +31,7 @@ Required: ### Nested Schema for `api_passthrough` -Optional: +Optional Attributes: - `extensions` (Attributes) Structure that contains X.500 extensions for a Certificate. (see [below for nested schema](#nestedatt--api_passthrough--extensions)) - `subject` (Attributes) Structure that contains X.500 distinguished name information. (see [below for nested schema](#nestedatt--api_passthrough--subject)) @@ -39,7 +39,7 @@ Optional: ### Nested Schema for `api_passthrough.extensions` -Optional: +Optional Attributes: - `certificate_policies` (Attributes List) (see [below for nested schema](#nestedatt--api_passthrough--extensions--certificate_policies)) - `extended_key_usage` (Attributes List) (see [below for nested schema](#nestedatt--api_passthrough--extensions--extended_key_usage)) @@ -49,18 +49,18 @@ Optional: ### Nested Schema for `api_passthrough.extensions.certificate_policies` -Required: +Required Attributes: - `cert_policy_id` (String) String that contains X.509 ObjectIdentifier information. -Optional: +Optional Attributes: - `policy_qualifiers` (Attributes List) (see [below for nested schema](#nestedatt--api_passthrough--extensions--certificate_policies--policy_qualifiers)) ### Nested Schema for `api_passthrough.extensions.certificate_policies.policy_qualifiers` -Required: +Required Attributes: - `policy_qualifier_id` (String) - `qualifier` (Attributes) Structure that contains a X.509 policy qualifier. (see [below for nested schema](#nestedatt--api_passthrough--extensions--certificate_policies--policy_qualifiers--qualifier)) @@ -68,7 +68,7 @@ Required: ### Nested Schema for `api_passthrough.extensions.certificate_policies.policy_qualifiers.qualifier` -Required: +Required Attributes: - `cps_uri` (String) @@ -78,7 +78,7 @@ Required: ### Nested Schema for `api_passthrough.extensions.extended_key_usage` -Optional: +Optional Attributes: - `extended_key_usage_object_identifier` (String) String that contains X.509 ObjectIdentifier information. - `extended_key_usage_type` (String) @@ -87,7 +87,7 @@ Optional: ### Nested Schema for `api_passthrough.extensions.key_usage` -Optional: +Optional Attributes: - `crl_sign` (Boolean) - `data_encipherment` (Boolean) @@ -103,7 +103,7 @@ Optional: ### Nested Schema for `api_passthrough.extensions.subject_alternative_names` -Optional: +Optional Attributes: - `directory_name` (Attributes) Structure that contains X.500 distinguished name information. (see [below for nested schema](#nestedatt--api_passthrough--extensions--subject_alternative_names--directory_name)) - `dns_name` (String) String that contains X.509 DnsName information. @@ -117,7 +117,7 @@ Optional: ### Nested Schema for `api_passthrough.extensions.subject_alternative_names.directory_name` -Optional: +Optional Attributes: - `common_name` (String) - `country` (String) @@ -138,7 +138,7 @@ Optional: ### Nested Schema for `api_passthrough.extensions.subject_alternative_names.edi_party_name` -Required: +Required Attributes: - `name_assigner` (String) - `party_name` (String) @@ -147,7 +147,7 @@ Required: ### Nested Schema for `api_passthrough.extensions.subject_alternative_names.other_name` -Required: +Required Attributes: - `type_id` (String) String that contains X.509 ObjectIdentifier information. - `value` (String) @@ -158,7 +158,7 @@ Required: ### Nested Schema for `api_passthrough.subject` -Optional: +Optional Attributes: - `common_name` (String) - `country` (String) @@ -180,7 +180,7 @@ Optional: ### Nested Schema for `validity_not_before` -Required: +Required Attributes: - `type` (String) - `value` (Number) diff --git a/internal/schemamd/testdata/awscc_logs_log_group.md b/internal/schemamd/testdata/awscc_logs_log_group.md index ebbbb0e5..697095dd 100644 --- a/internal/schemamd/testdata/awscc_logs_log_group.md +++ b/internal/schemamd/testdata/awscc_logs_log_group.md @@ -1,6 +1,6 @@ ## Schema -### Optional +### Optional Attributes - `kms_key_id` (String) The Amazon Resource Name (ARN) of the CMK to use when encrypting log data. - `log_group_name` (String) The name of the log group. If you don't specify a name, AWS CloudFormation generates a unique ID for the log group. diff --git a/internal/schemamd/testdata/framework_types.md b/internal/schemamd/testdata/framework_types.md index 8607a931..f9903044 100644 --- a/internal/schemamd/testdata/framework_types.md +++ b/internal/schemamd/testdata/framework_types.md @@ -6,7 +6,7 @@ - `required_write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example required write-only string attribute -### Optional +### Optional Attributes > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. @@ -14,8 +14,6 @@ - `float64_attribute` (Number) example float64 attribute - `int64_attribute` (Number) example int64 attribute - `list_attribute` (List of String) example list attribute -- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) -- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `map_attribute` (Map of String) example map attribute - `number_attribute` (Number) example number attribute - `object_attribute` (Object) example object attribute (see [below for nested schema](#nestedatt--object_attribute)) @@ -30,11 +28,16 @@ - `sensitive_set_attribute` (Set of String, Sensitive) example sensitive set attribute - `sensitive_string_attribute` (String, Sensitive) example sensitive string attribute - `set_attribute` (Set of String) example set attribute +- `string_attribute` (String) example string attribute +- `write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example write only string attribute + +### Blocks + +- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) +- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) - `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) - `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) -- `string_attribute` (String) example string attribute -- `write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example write only string attribute ### Read-Only @@ -74,7 +77,7 @@ Optional: ### Nested Schema for `object_attribute` -Optional: +Optional Attributes: - `object_attribute_attribute` (String) @@ -82,7 +85,7 @@ Optional: ### Nested Schema for `object_attribute_with_nested_object_attribute` -Optional: +Optional Attributes: - `nested_object` (Object) (see [below for nested schema](#nestedobjatt--object_attribute_with_nested_object_attribute--nested_object)) - `object_attribute_attribute` (String) @@ -90,7 +93,7 @@ Optional: ### Nested Schema for `object_attribute_with_nested_object_attribute.nested_object` -Optional: +Optional Attributes: - `nested_object_attribute` (String) @@ -99,15 +102,45 @@ Optional: ### Nested Schema for `sensitive_object_attribute` -Optional: +Optional Attributes: - `object_attribute_attribute` (String) + +### Nested Schema for `list_nested_block` + +Optional Attributes: + +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_attribute_with_default` (String) example list nested block attribute with default + +Blocks: + +- `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) + + +### Nested Schema for `list_nested_block.nested_list_block` + +Optional Attributes: + +- `nested_block_string_attribute` (String) example nested block string attribute + + + + +### Nested Schema for `list_nested_block_sensitive_nested_attribute` + +Optional Attributes: + +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_sensitive_attribute` (String, Sensitive) example sensitive list nested block attribute + + ### Nested Schema for `set_nested_block` -Optional: +Optional Attributes: > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. @@ -118,7 +151,7 @@ Optional: ### Nested Schema for `single_nested_block` -Optional: +Optional Attributes: - `single_nested_block_attribute` (String) example single nested block attribute @@ -126,7 +159,7 @@ Optional: ### Nested Schema for `single_nested_block_sensitive_nested_attribute` -Optional: +Optional Attributes: - `single_nested_block_attribute` (String) example single nested block attribute - `single_nested_block_sensitive_attribute` (String, Sensitive) example sensitive single nested block attribute From b1cdd28666b60cf9019d20647068db19697dee1c Mon Sep 17 00:00:00 2001 From: Toni Kangas Date: Mon, 12 Aug 2024 13:48:11 +0300 Subject: [PATCH 3/5] Add `--blocks-section` flag to `generate` command Render blocks in separate section if this flag is defined. --- ...k_provider_success_generic_templates.txtar | 6 +- ...ork_provider_success_named_templates.txtar | 6 +- ...mework_provider_success_no_templates.txtar | 6 +- .../generate/null_provider_success.txtar | 12 +- ...provider_success_all_framework_types.txtar | 84 ++- ...s_all_framework_types_blocks_section.txtar | 644 ++++++++++++++++++ ...k_provider_success_generic_templates.txtar | 6 +- ...ork_provider_success_named_templates.txtar | 6 +- ...mework_provider_success_no_templates.txtar | 6 +- .../generate/nested_id_attribute.txtar | 39 +- .../generate/null_provider_success.txtar | 12 +- internal/cmd/generate.go | 3 + internal/provider/generate.go | 18 +- internal/provider/template.go | 8 +- internal/provider/template_test.go | 4 +- internal/schemamd/render.go | 49 +- internal/schemamd/render_test.go | 29 +- .../schemamd/testdata/aws_acm_certificate.md | 9 +- .../testdata/aws_route_table_association.md | 4 +- .../testdata/awscc_acmpca_certificate.md | 34 +- .../schemamd/testdata/awscc_logs_log_group.md | 2 +- .../deep_nested_attributes_blocks_section.md | 46 ++ internal/schemamd/testdata/framework_types.md | 59 +- .../framework_types_blocks_section.md | 132 ++++ 24 files changed, 1020 insertions(+), 204 deletions(-) create mode 100644 cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar create mode 100644 internal/schemamd/testdata/deep_nested_attributes_blocks_section.md create mode 100644 internal/schemamd/testdata/framework_types_blocks_section.md diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar index 148f38b5..3119c8d0 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar @@ -53,7 +53,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -106,7 +106,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute @@ -155,7 +155,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar index 2f820264..6f833761 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar @@ -53,7 +53,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -106,7 +106,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute @@ -169,7 +169,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar index 61b4c4f2..382fd001 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar @@ -60,7 +60,7 @@ data "scaffolding_example" "example" { ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -90,7 +90,7 @@ provider "scaffolding" { ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -117,7 +117,7 @@ resource "scaffolding_example" "example" { ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar index 9fd7eed6..e7bf28a1 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar @@ -232,7 +232,7 @@ class MyConvertedCode(TerraformStack): ## Schema -### Optional Attributes +### Optional - `has_computed_default` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -343,7 +343,7 @@ class MyConvertedCode(TerraformStack): ## Schema -### Optional Attributes +### Optional - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. @@ -460,7 +460,7 @@ class MyConvertedCode extends TerraformStack { ## Schema -### Optional Attributes +### Optional - `hasComputedDefault` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -581,7 +581,7 @@ class MyConvertedCode extends TerraformStack { ## Schema -### Optional Attributes +### Optional - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. @@ -667,7 +667,7 @@ output "all_server_ips" { ## Schema -### Optional Attributes +### Optional - `has_computed_default` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -762,7 +762,7 @@ resource "null_resource" "cluster" { ## Schema -### Optional Attributes +### Optional - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar index 14168fdc..238d320e 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar @@ -48,7 +48,7 @@ Example provider ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -69,13 +69,7 @@ example resource ## Schema -### Required - -> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - -- `required_write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example required write-only string attribute - -### Optional Attributes +### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. @@ -83,6 +77,8 @@ example resource - `float64_attribute` (Number) example float64 attribute - `int64_attribute` (Number) example int64 attribute - `list_attribute` (List of String) example list attribute +- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) +- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `map_attribute` (Map of String) example map attribute - `number_attribute` (Number) example number attribute - `object_attribute` (Object) example object attribute (see [below for nested schema](#nestedatt--object_attribute)) @@ -107,79 +103,77 @@ example resource - `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) - `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) - `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) +- `string_attribute` (String) example string attribute ### Read-Only - `id` (String) The ID of this resource. - `set_nested_block_sensitive_nested_attribute` (Block Set) example sensitive set nested block (see [below for nested schema](#nestedblock--set_nested_block_sensitive_nested_attribute)) - -### Nested Schema for `object_attribute` + +### Nested Schema for `list_nested_block` -Optional Attributes: +Optional: -- `object_attribute_attribute` (String) +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_attribute_with_default` (String) example list nested block attribute with default +- `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) + +### Nested Schema for `list_nested_block.nested_list_block` - -### Nested Schema for `object_attribute_with_nested_object_attribute` +Optional: -Optional Attributes: +- `nested_block_string_attribute` (String) example nested block string attribute -- `nested_object` (Object) (see [below for nested schema](#nestedobjatt--object_attribute_with_nested_object_attribute--nested_object)) -- `object_attribute_attribute` (String) - -### Nested Schema for `object_attribute_with_nested_object_attribute.nested_object` -Optional Attributes: + +### Nested Schema for `list_nested_block_sensitive_nested_attribute` -- `nested_object_attribute` (String) +Optional: +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_sensitive_attribute` (String, Sensitive) example sensitive list nested block attribute - -### Nested Schema for `sensitive_object_attribute` + +### Nested Schema for `object_attribute` -Optional Attributes: +Optional: - `object_attribute_attribute` (String) - -### Nested Schema for `list_nested_block` - -Optional Attributes: - -- `list_nested_block_attribute` (String) example list nested block attribute -- `list_nested_block_attribute_with_default` (String) example list nested block attribute with default + +### Nested Schema for `object_attribute_with_nested_object_attribute` -Blocks: +Optional: -- `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) +- `nested_object` (Object) (see [below for nested schema](#nestedobjatt--object_attribute_with_nested_object_attribute--nested_object)) +- `object_attribute_attribute` (String) - -### Nested Schema for `list_nested_block.nested_list_block` + +### Nested Schema for `object_attribute_with_nested_object_attribute.nested_object` -Optional Attributes: +Optional: -- `nested_block_string_attribute` (String) example nested block string attribute +- `nested_object_attribute` (String) - -### Nested Schema for `list_nested_block_sensitive_nested_attribute` + +### Nested Schema for `sensitive_object_attribute` -Optional Attributes: +Optional: -- `list_nested_block_attribute` (String) example list nested block attribute -- `list_nested_block_sensitive_attribute` (String, Sensitive) example sensitive list nested block attribute +- `object_attribute_attribute` (String) ### Nested Schema for `set_nested_block` -Optional Attributes: +Optional: - `set_nested_block_attribute` (String) example set nested block attribute @@ -187,7 +181,7 @@ Optional Attributes: ### Nested Schema for `single_nested_block` -Optional Attributes: +Optional: - `single_nested_block_attribute` (String) example single nested block attribute @@ -195,7 +189,7 @@ Optional Attributes: ### Nested Schema for `single_nested_block_sensitive_nested_attribute` -Optional Attributes: +Optional: - `single_nested_block_attribute` (String) example single nested block attribute - `single_nested_block_sensitive_attribute` (String, Sensitive) example sensitive single nested block attribute diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar new file mode 100644 index 00000000..f74165a3 --- /dev/null +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar @@ -0,0 +1,644 @@ +# Copyright (c) HashiCorp, Inc. +# SPDX-License-Identifier: MPL-2.0 + +# Successful run of tfplugindocs on a Framework provider with a resource and function schema containing all framework types +[!unix] skip +exec tfplugindocs --provider-name=terraform-provider-scaffolding --providers-schema=schema.json --blocks-section +cmp stdout expected-output.txt +cmp docs/index.md expected-index.md +cmp docs/resources/example.md expected-resource.md +cmp docs/functions/scaffolding.md expected-function.md + +-- expected-output.txt -- +rendering website for provider "terraform-provider-scaffolding" (as "terraform-provider-scaffolding") +exporting schema from JSON file +getting provider schema +generating missing templates +generating missing resource content +generating new template for "scaffolding_example" +generating missing data source content +generating missing function content +generating new template for function "scaffolding" +generating missing provider content +generating new template for "terraform-provider-scaffolding" +rendering static website +cleaning rendered website dir +rendering templated website to static markdown +rendering "functions/scaffolding.md.tmpl" +rendering "index.md.tmpl" +rendering "resources/example.md.tmpl" +-- expected-index.md -- +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "scaffolding Provider" +subcategory: "" +description: |- + Example provider +--- + +# scaffolding Provider + +Example provider + + + + +## Schema + +### Optional Attributes + +- `endpoint` (String) Example provider attribute +-- expected-resource.md -- +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "scaffolding_example Resource - terraform-provider-scaffolding" +subcategory: "" +description: |- + example resource +--- + +# scaffolding_example (Resource) + +example resource + + + + +## Schema + +### Optional Attributes + +- `bool_attribute` (Boolean) example bool attribute +- `float64_attribute` (Number) example float64 attribute +- `int64_attribute` (Number) example int64 attribute +- `list_attribute` (List of String) example list attribute +- `map_attribute` (Map of String) example map attribute +- `number_attribute` (Number) example number attribute +- `object_attribute` (Object) example object attribute (see [below for nested schema](#nestedatt--object_attribute)) +- `object_attribute_with_nested_object_attribute` (Object) example object attribute with nested object attribute (see [below for nested schema](#nestedatt--object_attribute_with_nested_object_attribute)) +- `sensitive_bool_attribute` (Boolean, Sensitive) example sensitive bool attribute +- `sensitive_float64_attribute` (Number, Sensitive) example sensitive float64 attribute +- `sensitive_int64_attribute` (Number, Sensitive) example sensitive int64 attribute +- `sensitive_list_attribute` (List of String, Sensitive) example sensitive list attribute +- `sensitive_map_attribute` (Map of String, Sensitive) example sensitive map attribute +- `sensitive_number_attribute` (Number, Sensitive) example sensitive number attribute +- `sensitive_object_attribute` (Object, Sensitive) example sensitive object attribute (see [below for nested schema](#nestedatt--sensitive_object_attribute)) +- `sensitive_set_attribute` (Set of String, Sensitive) example sensitive set attribute +- `sensitive_string_attribute` (String, Sensitive) example sensitive string attribute +- `set_attribute` (Set of String) example set attribute +- `string_attribute` (String) example string attribute + +### Blocks + +- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) +- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) +- `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) +- `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) +- `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) + +### Read-Only + +- `id` (String) The ID of this resource. +- `set_nested_block_sensitive_nested_attribute` (Block Set) example sensitive set nested block (see [below for nested schema](#nestedblock--set_nested_block_sensitive_nested_attribute)) + + +### Nested Schema for `object_attribute` + +Optional Attributes: + +- `object_attribute_attribute` (String) + + + +### Nested Schema for `object_attribute_with_nested_object_attribute` + +Optional Attributes: + +- `nested_object` (Object) (see [below for nested schema](#nestedobjatt--object_attribute_with_nested_object_attribute--nested_object)) +- `object_attribute_attribute` (String) + + +### Nested Schema for `object_attribute_with_nested_object_attribute.nested_object` + +Optional Attributes: + +- `nested_object_attribute` (String) + + + + +### Nested Schema for `sensitive_object_attribute` + +Optional Attributes: + +- `object_attribute_attribute` (String) + + + +### Nested Schema for `list_nested_block` + +Optional Attributes: + +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_attribute_with_default` (String) example list nested block attribute with default + +Blocks: + +- `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) + + +### Nested Schema for `list_nested_block.nested_list_block` + +Optional Attributes: + +- `nested_block_string_attribute` (String) example nested block string attribute + + + + +### Nested Schema for `list_nested_block_sensitive_nested_attribute` + +Optional Attributes: + +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_sensitive_attribute` (String, Sensitive) example sensitive list nested block attribute + + + +### Nested Schema for `set_nested_block` + +Optional Attributes: + +- `set_nested_block_attribute` (String) example set nested block attribute + + + +### Nested Schema for `single_nested_block` + +Optional Attributes: + +- `single_nested_block_attribute` (String) example single nested block attribute + + + +### Nested Schema for `single_nested_block_sensitive_nested_attribute` + +Optional Attributes: + +- `single_nested_block_attribute` (String) example single nested block attribute +- `single_nested_block_sensitive_attribute` (String, Sensitive) example sensitive single nested block attribute + + + +### Nested Schema for `set_nested_block_sensitive_nested_attribute` + +Read-Only: + +- `set_nested_block_attribute` (String) example set nested block attribute +- `set_nested_block_sensitive_attribute` (String, Sensitive) example sensitive set nested block attribute +-- expected-function.md -- +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "scaffolding function - terraform-provider-scaffolding" +subcategory: "" +description: |- + Echo a string test test +--- + +# function: scaffolding + +Given a string value, returns the same value. + + + +## Signature + + +```text +scaffolding(stringInput string, boolInput bool, float64Input number, int64Input number, listStringInput list of string, mapStringInput map of string, numberInput number, objectInput object, setStringInput set of string, variadicParam string...) string +``` + +## Arguments + + +1. `stringInput` (String) Value to echo testing +1. `boolInput` (Boolean) Value to echo testing +1. `float64Input` (Number) Float64 Value to echo +1. `int64Input` (Number) Int64 Value to echo +1. `listStringInput` (List of String) List of strings to echo +1. `mapStringInput` (Map of String) Map of strings to echo +1. `numberInput` (Number) Number to echo +1. `objectInput` (Object) Object to echo +1. `setStringInput` (Set of String) Set of strings to echo + +1. `variadicParam` (Variadic, String) Value to echo +-- 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": { + "bool_attribute": { + "type": "bool", + "description": "example bool attribute", + "description_kind": "markdown", + "optional": true + }, + "float64_attribute": { + "type": "number", + "description": "example float64 attribute", + "description_kind": "markdown", + "optional": true + }, + "id": { + "type": "string", + "description_kind": "plain", + "computed": true + }, + "int64_attribute": { + "type": "number", + "description": "example int64 attribute", + "description_kind": "markdown", + "optional": true + }, + "list_attribute": { + "type": [ + "list", + "string" + ], + "description": "example list attribute", + "description_kind": "markdown", + "optional": true + }, + "map_attribute": { + "type": [ + "map", + "string" + ], + "description": "example map attribute", + "description_kind": "markdown", + "optional": true + }, + "number_attribute": { + "type": "number", + "description": "example number attribute", + "description_kind": "markdown", + "optional": true + }, + "object_attribute": { + "type": [ + "object", + { + "object_attribute_attribute": "string" + } + ], + "description": "example object attribute", + "description_kind": "markdown", + "optional": true + }, + "object_attribute_with_nested_object_attribute": { + "type": [ + "object", + { + "nested_object": [ + "object", + { + "nested_object_attribute": "string" + } + ], + "object_attribute_attribute": "string" + } + ], + "description": "example object attribute with nested object attribute", + "description_kind": "markdown", + "optional": true + }, + "sensitive_bool_attribute": { + "type": "bool", + "description": "example sensitive bool attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + }, + "sensitive_float64_attribute": { + "type": "number", + "description": "example sensitive float64 attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + }, + "sensitive_int64_attribute": { + "type": "number", + "description": "example sensitive int64 attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + }, + "sensitive_list_attribute": { + "type": [ + "list", + "string" + ], + "description": "example sensitive list attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + }, + "sensitive_map_attribute": { + "type": [ + "map", + "string" + ], + "description": "example sensitive map attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + }, + "sensitive_number_attribute": { + "type": "number", + "description": "example sensitive number attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + }, + "sensitive_object_attribute": { + "type": [ + "object", + { + "object_attribute_attribute": "string" + } + ], + "description": "example sensitive object attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + }, + "sensitive_set_attribute": { + "type": [ + "set", + "string" + ], + "description": "example sensitive set attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + }, + "sensitive_string_attribute": { + "type": "string", + "description": "example sensitive string attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + }, + "set_attribute": { + "type": [ + "set", + "string" + ], + "description": "example set attribute", + "description_kind": "markdown", + "optional": true + }, + "string_attribute": { + "type": "string", + "description": "example string attribute", + "description_kind": "markdown", + "optional": true + } + }, + "block_types": { + "list_nested_block": { + "nesting_mode": "list", + "block": { + "attributes": { + "list_nested_block_attribute": { + "type": "string", + "description": "example list nested block attribute", + "description_kind": "markdown", + "optional": true + }, + "list_nested_block_attribute_with_default": { + "type": "string", + "description": "example list nested block attribute with default", + "description_kind": "markdown", + "optional": true, + "computed": true + } + }, + "block_types": { + "nested_list_block": { + "nesting_mode": "list", + "block": { + "attributes": { + "nested_block_string_attribute": { + "type": "string", + "description": "example nested block string attribute", + "description_kind": "markdown", + "optional": true + } + }, + "description_kind": "plain" + } + } + }, + "description": "example list nested block", + "description_kind": "markdown" + } + }, + "list_nested_block_sensitive_nested_attribute": { + "nesting_mode": "list", + "block": { + "attributes": { + "list_nested_block_attribute": { + "type": "string", + "description": "example list nested block attribute", + "description_kind": "markdown", + "optional": true + }, + "list_nested_block_sensitive_attribute": { + "type": "string", + "description": "example sensitive list nested block attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + } + }, + "description_kind": "plain" + } + }, + "set_nested_block": { + "nesting_mode": "set", + "block": { + "attributes": { + "set_nested_block_attribute": { + "type": "string", + "description": "example set nested block attribute", + "description_kind": "markdown", + "optional": true + } + }, + "description": "example set nested block", + "description_kind": "markdown" + } + }, + "set_nested_block_sensitive_nested_attribute": { + "nesting_mode": "set", + "block": { + "attributes": { + "set_nested_block_attribute": { + "type": "string", + "description": "example set nested block attribute", + "description_kind": "markdown", + "computed": true + }, + "set_nested_block_sensitive_attribute": { + "type": "string", + "description": "example sensitive set nested block attribute", + "description_kind": "markdown", + "computed": true, + "sensitive": true + } + }, + "description": "example sensitive set nested block", + "description_kind": "markdown" + } + }, + "single_nested_block": { + "nesting_mode": "single", + "block": { + "attributes": { + "single_nested_block_attribute": { + "type": "string", + "description": "example single nested block attribute", + "description_kind": "markdown", + "optional": true + } + }, + "description": "example single nested block", + "description_kind": "markdown" + } + }, + "single_nested_block_sensitive_nested_attribute": { + "nesting_mode": "single", + "block": { + "attributes": { + "single_nested_block_attribute": { + "type": "string", + "description": "example single nested block attribute", + "description_kind": "markdown", + "optional": true + }, + "single_nested_block_sensitive_attribute": { + "type": "string", + "description": "example sensitive single nested block attribute", + "description_kind": "markdown", + "optional": true, + "sensitive": true + } + }, + "description": "example sensitive single nested block", + "description_kind": "markdown" + } + } + }, + "description": "example resource", + "description_kind": "plain" + } + } + }, + "functions": { + "scaffolding": { + "description": "Given a string value, returns the same value.", + "summary": "Echo a string test test", + "return_type": "string", + "parameters": [ + { + "name": "stringInput", + "description": "Value to echo testing", + "type": "string" + }, + { + "name": "boolInput", + "description": "Value to echo testing", + "type": "bool" + }, + { + "name": "float64Input", + "description": "Float64 Value to echo", + "type": "number" + }, + { + "name": "int64Input", + "description": "Int64 Value to echo", + "type": "number" + }, + { + "name": "listStringInput", + "description": "List of strings to echo", + "type": [ + "list", + "string" + ] + }, + { + "name": "mapStringInput", + "description": "Map of strings to echo", + "type": [ + "map", + "string" + ] + }, + { + "name": "numberInput", + "description": "Number to echo", + "type": "number" + }, + { + "name": "objectInput", + "description": "Object to echo", + "type": [ + "object", + { + "attr1": "string", + "attr2": "number" + } + ] + }, + { + "name": "setStringInput", + "description": "Set of strings to echo", + "type": [ + "set", + "string" + ] + } + ], + "variadic_parameter": { + "name": "variadicParam", + "description": "Value to echo", + "type": "string" + } + } + } + } + } +} diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar index 1cc3b236..a695740e 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar @@ -222,7 +222,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -322,7 +322,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute @@ -371,7 +371,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value 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 a1c23f0d..984c5011 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 @@ -221,7 +221,7 @@ RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -321,7 +321,7 @@ RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute @@ -384,7 +384,7 @@ RenderedProviderName: Scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value 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 e5b22e50..8ac9b9ad 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 @@ -54,7 +54,7 @@ data "scaffolding_example" "example" { ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -119,7 +119,7 @@ provider "scaffolding" { ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -146,7 +146,7 @@ resource "scaffolding_example" "example" { ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute - `defaulted` (String) Example configurable attribute with default value diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar index b05b6cfd..2ab41c10 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar @@ -45,7 +45,7 @@ Example provider ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -66,18 +66,15 @@ example resource ## Schema -### Required Attributes +### Required - `required_object_attribute` (Object) example required object attribute (see [below for nested schema](#nestedatt--required_object_attribute)) -### Optional Attributes - -- `optional_object_attribute` (Object) example optional object attribute (see [below for nested schema](#nestedatt--optional_object_attribute)) - -### Blocks +### Optional - `list_nested_block_optional_id` (Block List) example list nested block with optional id attribute (see [below for nested schema](#nestedblock--list_nested_block_optional_id)) - `list_nested_block_required_id` (Block List) example list nested block with required id attribute (see [below for nested schema](#nestedblock--list_nested_block_required_id)) +- `optional_object_attribute` (Object) example optional object attribute (see [below for nested schema](#nestedatt--optional_object_attribute)) - `set_nested_block_optional_id` (Block Set) example set nested block with optional id attribute (see [below for nested schema](#nestedblock--set_nested_block_optional_id)) - `set_nested_block_required_id` (Block Set) example set nested block with required id attribute (see [below for nested schema](#nestedblock--set_nested_block_required_id)) - `single_nested_block_optional_id` (Block, Optional) example single nested block with optional id attribute (see [below for nested schema](#nestedblock--single_nested_block_optional_id)) @@ -94,31 +91,31 @@ example resource ### Nested Schema for `required_object_attribute` -Required Attributes: +Required: - `id` (String) - -### Nested Schema for `optional_object_attribute` + +### Nested Schema for `list_nested_block_optional_id` -Optional Attributes: +Optional: - `id` (String) - -### Nested Schema for `list_nested_block_optional_id` + +### Nested Schema for `list_nested_block_required_id` -Optional Attributes: +Required: - `id` (String) - -### Nested Schema for `list_nested_block_required_id` + +### Nested Schema for `optional_object_attribute` -Required Attributes: +Optional: - `id` (String) @@ -126,7 +123,7 @@ Required Attributes: ### Nested Schema for `set_nested_block_optional_id` -Optional Attributes: +Optional: - `id` (String) @@ -134,7 +131,7 @@ Optional Attributes: ### Nested Schema for `set_nested_block_required_id` -Required Attributes: +Required: - `id` (String) @@ -142,7 +139,7 @@ Required Attributes: ### Nested Schema for `single_nested_block_optional_id` -Optional Attributes: +Optional: - `id` (String) @@ -150,7 +147,7 @@ Optional Attributes: ### Nested Schema for `single_nested_block_required_id` -Required Attributes: +Required: - `id` (String) diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar index a8735b92..9a9b0db6 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar @@ -207,7 +207,7 @@ class MyConvertedCode(TerraformStack): ## Schema -### Optional Attributes +### Optional - `has_computed_default` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -318,7 +318,7 @@ class MyConvertedCode(TerraformStack): ## Schema -### Optional Attributes +### Optional - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. @@ -435,7 +435,7 @@ class MyConvertedCode extends TerraformStack { ## Schema -### Optional Attributes +### Optional - `hasComputedDefault` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -556,7 +556,7 @@ class MyConvertedCode extends TerraformStack { ## Schema -### Optional Attributes +### Optional - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. @@ -642,7 +642,7 @@ output "all_server_ips" { ## Schema -### Optional Attributes +### Optional - `has_computed_default` (String) If set, its literal value will be stored and returned. If not, its value defaults to `"default"`. This argument exists primarily for testing and has little practical use. - `inputs` (Map of String) A map of arbitrary strings that is copied into the `outputs` attribute, and accessible directly for interpolation. @@ -737,7 +737,7 @@ resource "null_resource" "cluster" { ## Schema -### Optional Attributes +### Optional - `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners. diff --git a/internal/cmd/generate.go b/internal/cmd/generate.go index d50d9b2f..6ce5d75f 100644 --- a/internal/cmd/generate.go +++ b/internal/cmd/generate.go @@ -19,6 +19,7 @@ type generateCmd struct { flagProviderName string flagRenderedProviderName string + flagBlocksSection bool flagProviderDir string flagProvidersSchema string flagRenderedWebsiteDir string @@ -72,6 +73,7 @@ func (cmd *generateCmd) Help() string { func (cmd *generateCmd) Flags() *flag.FlagSet { fs := flag.NewFlagSet("generate", flag.ExitOnError) + fs.BoolVar(&cmd.flagBlocksSection, "blocks-section", false, "render blocks in a separate section instead of including them with attributes in the required and optional sections.") fs.StringVar(&cmd.flagProviderName, "provider-name", "", "provider name, as used in Terraform configurations; defaults to the --provider-dir short name (after removing `terraform-provider-` prefix)") fs.StringVar(&cmd.flagProviderDir, "provider-dir", "", "relative or absolute path to the root provider code directory when running the command outside the root provider code directory") fs.StringVar(&cmd.flagProvidersSchema, "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") @@ -109,6 +111,7 @@ func (cmd *generateCmd) runInternal() error { cmd.flagWebsiteSourceDir, cmd.tfVersion, cmd.flagIgnoreDeprecated, + cmd.flagBlocksSection, ) if err != nil { return fmt.Errorf("unable to generate website: %w", err) diff --git a/internal/provider/generate.go b/internal/provider/generate.go index 2cb43d5b..b68ea501 100644 --- a/internal/provider/generate.go +++ b/internal/provider/generate.go @@ -116,6 +116,7 @@ var ( ) type generator struct { + blocksSection bool ignoreDeprecated bool tfVersion string @@ -141,7 +142,7 @@ func (g *generator) warnf(format string, a ...interface{}) { g.ui.Warn(fmt.Sprintf(format, a...)) } -func Generate(ui cli.Ui, providerDir, providerName, providersSchemaPath, renderedProviderName, renderedWebsiteDir, examplesDir, websiteTmpDir, templatesDir, tfVersion string, ignoreDeprecated bool) error { +func Generate(ui cli.Ui, providerDir, providerName, providersSchemaPath, renderedProviderName, renderedWebsiteDir, examplesDir, websiteTmpDir, templatesDir, tfVersion string, ignoreDeprecated, blocksSection bool) error { // Ensure provider directory is resolved absolute path if providerDir == "" { wd, err := os.Getwd() @@ -173,6 +174,7 @@ func Generate(ui cli.Ui, providerDir, providerName, providersSchemaPath, rendere } g := &generator{ + blocksSection: blocksSection, ignoreDeprecated: ignoreDeprecated, tfVersion: tfVersion, @@ -268,7 +270,7 @@ func (g *generator) Generate(ctx context.Context) error { } g.infof("rendering static website") - err = g.renderStaticWebsite(providerSchema) + err = g.renderStaticWebsite(providerSchema, g.blocksSection) if err != nil { return fmt.Errorf("error rendering static website: %w", err) } @@ -734,7 +736,7 @@ func (g *generator) generateMissingTemplates(providerSchema *tfjson.ProviderSche return nil } -func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema) error { +func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema, blocksSection bool) error { g.infof("cleaning rendered website dir") dirEntry, err := os.ReadDir(g.ProviderDocsDir()) if err != nil && !os.IsNotExist(err) { @@ -839,7 +841,7 @@ func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema) e slices.Sort(exampleFiles) tmpl := resourceTemplate(tmplData) - render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "Data Source", exampleFilePath, exampleFiles, "", "", "", resSchema, nil) + render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "Data Source", exampleFilePath, exampleFiles, "", "", "", resSchema, nil, blocksSection) if err != nil { return fmt.Errorf("unable to render data source template %q: %w", rel, err) } @@ -870,7 +872,7 @@ func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema) e importIdentityConfigFilePath := filepath.Join(g.ProviderExamplesDir(), "resources", resName, "import-by-identity.tf") tmpl := resourceTemplate(tmplData) - render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "Resource", exampleFilePath, exampleFiles, importIDConfigFilePath, importIdentityConfigFilePath, importFilePath, resSchema, resIdentitySchema) + render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "Resource", exampleFilePath, exampleFiles, importIDConfigFilePath, importIdentityConfigFilePath, importFilePath, resSchema, resIdentitySchema, blocksSection) if err != nil { return fmt.Errorf("unable to render resource template %q: %w", rel, err) } @@ -922,7 +924,7 @@ func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema) e slices.Sort(exampleFiles) tmpl := resourceTemplate(tmplData) - render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "Ephemeral Resource", exampleFilePath, exampleFiles, "", "", "", resSchema, nil) + render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "Ephemeral Resource", exampleFilePath, exampleFiles, "", "", "", resSchema, nil, blocksSection) if err != nil { return fmt.Errorf("unable to render ephemeral resource template %q: %w", rel, err) } @@ -973,7 +975,7 @@ func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema) e if resSchema != nil { tmpl := resourceTemplate(tmplData) - render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "List Resource", exampleFilePath, exampleFiles, "", "", "", resSchema, nil) + render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "List Resource", exampleFilePath, exampleFiles, "", "", "", resSchema, nil, blocksSection) if err != nil { return fmt.Errorf("unable to render list resource template %q: %w", rel, err) } @@ -1023,7 +1025,7 @@ func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema) e slices.Sort(exampleFiles) tmpl := providerTemplate(tmplData) - render, err := tmpl.Render(g.providerDir, g.providerName, g.renderedProviderName, exampleFilePath, exampleFiles, providerSchema.ConfigSchema) + render, err := tmpl.Render(g.providerDir, g.providerName, g.renderedProviderName, exampleFilePath, exampleFiles, providerSchema.ConfigSchema, blocksSection) if err != nil { return fmt.Errorf("unable to render provider template %q: %w", rel, err) } diff --git a/internal/provider/template.go b/internal/provider/template.go index 43e785dc..7011e82b 100644 --- a/internal/provider/template.go +++ b/internal/provider/template.go @@ -186,9 +186,9 @@ func (t docTemplate) Render(providerDir string, out io.Writer) error { return renderTemplate(providerDir, "docTemplate", s, out, nil) } -func (t providerTemplate) Render(providerDir, providerName, renderedProviderName, exampleFile string, exampleFiles []string, schema *tfjson.Schema) (string, error) { +func (t providerTemplate) Render(providerDir, providerName, renderedProviderName, exampleFile string, exampleFiles []string, schema *tfjson.Schema, blocksSection bool) (string, error) { schemaBuffer := bytes.NewBuffer(nil) - err := schemamd.Render(schema, schemaBuffer) + err := schemamd.Render(schema, schemaBuffer, blocksSection) if err != nil { return "", fmt.Errorf("unable to render schema: %w", err) } @@ -215,9 +215,9 @@ func (t providerTemplate) Render(providerDir, providerName, renderedProviderName }) } -func (t resourceTemplate) Render(providerDir, name, providerName, renderedProviderName, typeName, exampleFile string, exampleFiles []string, importIDConfigFile, importIdentityConfigFile, importCmdFile string, schema *tfjson.Schema, identitySchema *tfjson.IdentitySchema) (string, error) { +func (t resourceTemplate) Render(providerDir, name, providerName, renderedProviderName, typeName, exampleFile string, exampleFiles []string, importIDConfigFile, importIdentityConfigFile, importCmdFile string, schema *tfjson.Schema, identitySchema *tfjson.IdentitySchema, blocksSection bool) (string, error) { schemaBuffer := bytes.NewBuffer(nil) - err := schemamd.Render(schema, schemaBuffer) + err := schemamd.Render(schema, schemaBuffer, blocksSection) if err != nil { return "", fmt.Errorf("unable to render schema: %w", err) } diff --git a/internal/provider/template_test.go b/internal/provider/template_test.go index aa25f420..47b7e8ab 100644 --- a/internal/provider/template_test.go +++ b/internal/provider/template_test.go @@ -93,7 +93,7 @@ provider "scaffolding" { }, } - result, err := tpl.Render("testdata/test-provider-dir", "testTemplate", "test-provider", "test-provider", "Resource", "provider.tf", []string{"provider.tf"}, "", "", "", &schema, nil) + result, err := tpl.Render("testdata/test-provider-dir", "testTemplate", "test-provider", "test-provider", "Resource", "provider.tf", []string{"provider.tf"}, "", "", "", &schema, nil, false) if err != nil { t.Error(err) } @@ -133,7 +133,7 @@ provider "scaffolding" { }, } - result, err := tpl.Render("testdata/test-provider-dir", "testTemplate", "test-provider", "provider.tf", []string{"provider.tf"}, &schema) + result, err := tpl.Render("testdata/test-provider-dir", "testTemplate", "test-provider", "provider.tf", []string{"provider.tf"}, &schema, false) if err != nil { t.Error(err) } diff --git a/internal/schemamd/render.go b/internal/schemamd/render.go index 1000982b..821f7c87 100644 --- a/internal/schemamd/render.go +++ b/internal/schemamd/render.go @@ -22,13 +22,13 @@ import ( // }, // "version": 0 // }, -func Render(schema *tfjson.Schema, w io.Writer) error { +func Render(schema *tfjson.Schema, w io.Writer, blocksSection bool) error { _, err := io.WriteString(w, "## Schema\n\n") if err != nil { return err } - err = writeRootBlock(w, schema.Block) + err = writeRootBlock(w, schema.Block, blocksSection) if err != nil { return fmt.Errorf("unable to render schema: %w", err) } @@ -44,7 +44,7 @@ func RenderAction(schema *tfjson.ActionSchema, w io.Writer) error { return err } - err = writeRootBlock(w, schema.Block) + err = writeRootBlock(w, schema.Block, false) if err != nil { return fmt.Errorf("unable to render action schema: %w", err) } @@ -182,7 +182,14 @@ var ( // * Required // * Optional // * Read-Only - groupFilters = []groupFilter{ + defaultGroupFilters = []groupFilter{ + {"### Required", "Required:", childAttributeIsRequired, childBlockIsRequired}, + {"### Optional", "Optional:", childAttributeIsOptional, childBlockIsOptional}, + {"### Read-Only", "Read-Only:", childAttributeIsReadOnly, childBlockIsReadOnly}, + } + + // When --blocks-section is enabled, blocks are rendered in a separate section regardless of their optional or required characteristics. + blocksSectionGroupFilters = []groupFilter{ {"### Required Attributes", "Required Attributes:", childAttributeIsRequired, omitChild[*tfjson.SchemaBlockType]}, {"### Optional Attributes", "Optional Attributes:", childAttributeIsOptional, omitChild[*tfjson.SchemaBlockType]}, {"### Blocks", "Blocks:", omitChild[*tfjson.SchemaAttribute], childBlockIsWritable}, @@ -190,6 +197,14 @@ var ( } ) +func getGroupFilters(blocksSection bool) []groupFilter { + if blocksSection { + return blocksSectionGroupFilters + } + + return defaultGroupFilters +} + type nestedType struct { anchorID string pathTitle string @@ -313,8 +328,8 @@ func writeBlockType(w io.Writer, path []string, block *tfjson.SchemaBlockType) ( return []nestedType{nt}, nil } -func writeRootBlock(w io.Writer, block *tfjson.SchemaBlock) error { - return writeBlockChildren(w, nil, block, true) +func writeRootBlock(w io.Writer, block *tfjson.SchemaBlock, blocksSection bool) error { + return writeBlockChildren(w, nil, block, true, blocksSection) } // A Block contains: @@ -344,7 +359,7 @@ func writeRootBlock(w io.Writer, block *tfjson.SchemaBlock) error { // }, // "description_kind": "plain" // }, -func writeBlockChildren(w io.Writer, parents []string, block *tfjson.SchemaBlock, root bool) error { +func writeBlockChildren(w io.Writer, parents []string, block *tfjson.SchemaBlock, root bool, blocksSection bool) error { names := []string{} for n := range block.Attributes { names = append(names, n) @@ -355,6 +370,7 @@ func writeBlockChildren(w io.Writer, parents []string, block *tfjson.SchemaBlock groups := map[int][]string{} + groupFilters := getGroupFilters(blocksSection) // Group Attributes/Blocks by characteristics. nameLoop: for _, n := range names { @@ -492,7 +508,7 @@ nameLoop: } } - err := writeNestedTypes(w, nestedTypes) + err := writeNestedTypes(w, nestedTypes, blocksSection) if err != nil { return err } @@ -500,7 +516,7 @@ nameLoop: return nil } -func writeNestedTypes(w io.Writer, nestedTypes []nestedType) error { +func writeNestedTypes(w io.Writer, nestedTypes []nestedType, blocksSection bool) error { for _, nt := range nestedTypes { _, err := io.WriteString(w, "\n") if err != nil { @@ -514,17 +530,17 @@ func writeNestedTypes(w io.Writer, nestedTypes []nestedType) error { switch { case nt.block != nil: - err = writeBlockChildren(w, nt.path, nt.block, false) + err = writeBlockChildren(w, nt.path, nt.block, false, blocksSection) if err != nil { return err } case nt.object != nil: - err = writeObjectChildren(w, nt.path, *nt.object, nt.group) + err = writeObjectChildren(w, nt.path, *nt.object, nt.group, blocksSection) if err != nil { return err } case nt.attrs != nil: - err = writeNestedAttributeChildren(w, nt.path, nt.attrs, nt.group) + err = writeNestedAttributeChildren(w, nt.path, nt.attrs, nt.group, blocksSection) if err != nil { return err } @@ -606,7 +622,7 @@ func writeObjectAttribute(w io.Writer, path []string, att cty.Type, group groupF return nestedTypes, nil } -func writeObjectChildren(w io.Writer, parents []string, ty cty.Type, group groupFilter) error { +func writeObjectChildren(w io.Writer, parents []string, ty cty.Type, group groupFilter, blocksSection bool) error { _, err := io.WriteString(w, group.nestedTitle+"\n\n") if err != nil { return err @@ -639,7 +655,7 @@ func writeObjectChildren(w io.Writer, parents []string, ty cty.Type, group group return err } - err = writeNestedTypes(w, nestedTypes) + err = writeNestedTypes(w, nestedTypes, blocksSection) if err != nil { return err } @@ -647,13 +663,14 @@ func writeObjectChildren(w io.Writer, parents []string, ty cty.Type, group group return nil } -func writeNestedAttributeChildren(w io.Writer, parents []string, nestedAttributes *tfjson.SchemaNestedAttributeType, group groupFilter) error { +func writeNestedAttributeChildren(w io.Writer, parents []string, nestedAttributes *tfjson.SchemaNestedAttributeType, group groupFilter, blocksSection bool) error { sortedNames := []string{} for n := range nestedAttributes.Attributes { sortedNames = append(sortedNames, n) } sort.Strings(sortedNames) + groupFilters := getGroupFilters(blocksSection) groups := map[int][]string{} for _, name := range sortedNames { att := nestedAttributes.Attributes[name] @@ -698,7 +715,7 @@ func writeNestedAttributeChildren(w io.Writer, parents []string, nestedAttribute } } - err := writeNestedTypes(w, nestedTypes) + err := writeNestedTypes(w, nestedTypes, blocksSection) if err != nil { return err } diff --git a/internal/schemamd/render_test.go b/internal/schemamd/render_test.go index 98daa9c7..c24372ac 100644 --- a/internal/schemamd/render_test.go +++ b/internal/schemamd/render_test.go @@ -19,45 +19,66 @@ func TestRender(t *testing.T) { t.Parallel() for _, c := range []struct { - name string - inputFile string - expectedFile string + name string + inputFile string + expectedFile string + blocksSection bool }{ { "aws_route_table_association", "testdata/aws_route_table_association.schema.json", "testdata/aws_route_table_association.md", + false, }, { "aws_acm_certificate", "testdata/aws_acm_certificate.schema.json", "testdata/aws_acm_certificate.md", + false, }, { "awscc_logs_log_group", "testdata/awscc_logs_log_group.schema.json", "testdata/awscc_logs_log_group.md", + false, }, { "awscc_acmpca_certificate", "testdata/awscc_acmpca_certificate.schema.json", "testdata/awscc_acmpca_certificate.md", + false, }, { "framework_types", "testdata/framework_types.schema.json", "testdata/framework_types.md", + false, + }, + { + "framework_types_blocks_section", + "testdata/framework_types.schema.json", + "testdata/framework_types_blocks_section.md", + true, }, { // Reference: https://github.com/hashicorp/terraform-plugin-docs/issues/380 "deep_nested_attributes", "testdata/deep_nested_attributes.schema.json", "testdata/deep_nested_attributes.md", + false, + }, + { + // Reference: https://github.com/hashicorp/terraform-plugin-docs/issues/380 + "deep_nested_attributes_blocks_section", + "testdata/deep_nested_attributes.schema.json", + "testdata/deep_nested_attributes_blocks_section.md", + true, }, { "deep_nested_write_only_attributes", "testdata/deep_nested_write_only_attributes.schema.json", "testdata/deep_nested_write_only_attributes.md", + false, }, } { t.Run(c.name, func(t *testing.T) { @@ -81,7 +102,7 @@ func TestRender(t *testing.T) { } b := &strings.Builder{} - err = schemamd.Render(&schema, b) + err = schemamd.Render(&schema, b, c.blocksSection) if err != nil { t.Fatal(err) } diff --git a/internal/schemamd/testdata/aws_acm_certificate.md b/internal/schemamd/testdata/aws_acm_certificate.md index 4a666b3e..7ead0c69 100644 --- a/internal/schemamd/testdata/aws_acm_certificate.md +++ b/internal/schemamd/testdata/aws_acm_certificate.md @@ -1,21 +1,18 @@ ## Schema -### Optional Attributes +### Optional - `certificate_authority_arn` (String) - `certificate_body` (String) - `certificate_chain` (String) - `domain_name` (String) +- `options` (Block List, Max: 1) (see [below for nested schema](#nestedblock--options)) - `private_key` (String, Sensitive) - `subject_alternative_names` (Set of String) - `tags` (Map of String) - `tags_all` (Map of String) - `validation_method` (String) -### Blocks - -- `options` (Block List, Max: 1) (see [below for nested schema](#nestedblock--options)) - ### Read-Only - `arn` (String) @@ -27,7 +24,7 @@ ### Nested Schema for `options` -Optional Attributes: +Optional: - `certificate_transparency_logging_preference` (String) diff --git a/internal/schemamd/testdata/aws_route_table_association.md b/internal/schemamd/testdata/aws_route_table_association.md index 78bc2641..279d6c19 100644 --- a/internal/schemamd/testdata/aws_route_table_association.md +++ b/internal/schemamd/testdata/aws_route_table_association.md @@ -1,10 +1,10 @@ ## Schema -### Required Attributes +### Required - `route_table_id` (String) -### Optional Attributes +### Optional - `gateway_id` (String) - `subnet_id` (String) diff --git a/internal/schemamd/testdata/awscc_acmpca_certificate.md b/internal/schemamd/testdata/awscc_acmpca_certificate.md index 2cbe1b5c..73bc8880 100644 --- a/internal/schemamd/testdata/awscc_acmpca_certificate.md +++ b/internal/schemamd/testdata/awscc_acmpca_certificate.md @@ -1,13 +1,13 @@ ## Schema -### Required Attributes +### Required - `certificate_authority_arn` (String) - `certificate_signing_request` (String) The certificate signing request (CSR) for the Certificate. - `signing_algorithm` (String) The name of the algorithm that will be used to sign the Certificate. - `validity` (Attributes) Validity for a certificate. (see [below for nested schema](#nestedatt--validity)) -### Optional Attributes +### Optional - `api_passthrough` (Attributes) Structure that specifies fields to be overridden in a certificate at the time of issuance. These requires an API Passthrough template be used or they will be ignored. (see [below for nested schema](#nestedatt--api_passthrough)) - `template_arn` (String) @@ -22,7 +22,7 @@ ### Nested Schema for `validity` -Required Attributes: +Required: - `type` (String) - `value` (Number) @@ -31,7 +31,7 @@ Required Attributes: ### Nested Schema for `api_passthrough` -Optional Attributes: +Optional: - `extensions` (Attributes) Structure that contains X.500 extensions for a Certificate. (see [below for nested schema](#nestedatt--api_passthrough--extensions)) - `subject` (Attributes) Structure that contains X.500 distinguished name information. (see [below for nested schema](#nestedatt--api_passthrough--subject)) @@ -39,7 +39,7 @@ Optional Attributes: ### Nested Schema for `api_passthrough.extensions` -Optional Attributes: +Optional: - `certificate_policies` (Attributes List) (see [below for nested schema](#nestedatt--api_passthrough--extensions--certificate_policies)) - `extended_key_usage` (Attributes List) (see [below for nested schema](#nestedatt--api_passthrough--extensions--extended_key_usage)) @@ -49,18 +49,18 @@ Optional Attributes: ### Nested Schema for `api_passthrough.extensions.certificate_policies` -Required Attributes: +Required: - `cert_policy_id` (String) String that contains X.509 ObjectIdentifier information. -Optional Attributes: +Optional: - `policy_qualifiers` (Attributes List) (see [below for nested schema](#nestedatt--api_passthrough--extensions--certificate_policies--policy_qualifiers)) ### Nested Schema for `api_passthrough.extensions.certificate_policies.policy_qualifiers` -Required Attributes: +Required: - `policy_qualifier_id` (String) - `qualifier` (Attributes) Structure that contains a X.509 policy qualifier. (see [below for nested schema](#nestedatt--api_passthrough--extensions--certificate_policies--policy_qualifiers--qualifier)) @@ -68,7 +68,7 @@ Required Attributes: ### Nested Schema for `api_passthrough.extensions.certificate_policies.policy_qualifiers.qualifier` -Required Attributes: +Required: - `cps_uri` (String) @@ -78,7 +78,7 @@ Required Attributes: ### Nested Schema for `api_passthrough.extensions.extended_key_usage` -Optional Attributes: +Optional: - `extended_key_usage_object_identifier` (String) String that contains X.509 ObjectIdentifier information. - `extended_key_usage_type` (String) @@ -87,7 +87,7 @@ Optional Attributes: ### Nested Schema for `api_passthrough.extensions.key_usage` -Optional Attributes: +Optional: - `crl_sign` (Boolean) - `data_encipherment` (Boolean) @@ -103,7 +103,7 @@ Optional Attributes: ### Nested Schema for `api_passthrough.extensions.subject_alternative_names` -Optional Attributes: +Optional: - `directory_name` (Attributes) Structure that contains X.500 distinguished name information. (see [below for nested schema](#nestedatt--api_passthrough--extensions--subject_alternative_names--directory_name)) - `dns_name` (String) String that contains X.509 DnsName information. @@ -117,7 +117,7 @@ Optional Attributes: ### Nested Schema for `api_passthrough.extensions.subject_alternative_names.directory_name` -Optional Attributes: +Optional: - `common_name` (String) - `country` (String) @@ -138,7 +138,7 @@ Optional Attributes: ### Nested Schema for `api_passthrough.extensions.subject_alternative_names.edi_party_name` -Required Attributes: +Required: - `name_assigner` (String) - `party_name` (String) @@ -147,7 +147,7 @@ Required Attributes: ### Nested Schema for `api_passthrough.extensions.subject_alternative_names.other_name` -Required Attributes: +Required: - `type_id` (String) String that contains X.509 ObjectIdentifier information. - `value` (String) @@ -158,7 +158,7 @@ Required Attributes: ### Nested Schema for `api_passthrough.subject` -Optional Attributes: +Optional: - `common_name` (String) - `country` (String) @@ -180,7 +180,7 @@ Optional Attributes: ### Nested Schema for `validity_not_before` -Required Attributes: +Required: - `type` (String) - `value` (Number) diff --git a/internal/schemamd/testdata/awscc_logs_log_group.md b/internal/schemamd/testdata/awscc_logs_log_group.md index 697095dd..ebbbb0e5 100644 --- a/internal/schemamd/testdata/awscc_logs_log_group.md +++ b/internal/schemamd/testdata/awscc_logs_log_group.md @@ -1,6 +1,6 @@ ## Schema -### Optional Attributes +### Optional - `kms_key_id` (String) The Amazon Resource Name (ARN) of the CMK to use when encrypting log data. - `log_group_name` (String) The name of the log group. If you don't specify a name, AWS CloudFormation generates a unique ID for the log group. diff --git a/internal/schemamd/testdata/deep_nested_attributes_blocks_section.md b/internal/schemamd/testdata/deep_nested_attributes_blocks_section.md new file mode 100644 index 00000000..74641a16 --- /dev/null +++ b/internal/schemamd/testdata/deep_nested_attributes_blocks_section.md @@ -0,0 +1,46 @@ +## Schema + +### Required Attributes + +- `level_one` (Attributes) (see [below for nested schema](#nestedatt--level_one)) + +### Read-Only + +- `id` (String) Example identifier + + +### Nested Schema for `level_one` + +Optional Attributes: + +- `level_two` (Attributes) (see [below for nested schema](#nestedatt--level_one--level_two)) + + +### Nested Schema for `level_one.level_two` + +Optional Attributes: + +- `level_three` (Attributes) (see [below for nested schema](#nestedatt--level_one--level_two--level_three)) + + +### Nested Schema for `level_one.level_two.level_three` + +Optional Attributes: + +- `level_four_primary` (Attributes) (see [below for nested schema](#nestedatt--level_one--level_two--level_three--level_four_primary)) +- `level_four_secondary` (String) + + +### Nested Schema for `level_one.level_two.level_three.level_four_primary` + +Optional Attributes: + +- `level_five` (Attributes) Parent should be level_one.level_two.level_three.level_four_primary. (see [below for nested schema](#nestedatt--level_one--level_two--level_three--level_four_primary--level_five)) +- `level_four_primary_string` (String) Parent should be level_one.level_two.level_three.level_four_primary. + + +### Nested Schema for `level_one.level_two.level_three.level_four_primary.level_five` + +Optional Attributes: + +- `level_five_string` (String) Parent should be level_one.level_two.level_three.level_four_primary.level_five. diff --git a/internal/schemamd/testdata/framework_types.md b/internal/schemamd/testdata/framework_types.md index f9903044..7041fe64 100644 --- a/internal/schemamd/testdata/framework_types.md +++ b/internal/schemamd/testdata/framework_types.md @@ -6,7 +6,7 @@ - `required_write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example required write-only string attribute -### Optional Attributes +### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. @@ -14,6 +14,8 @@ - `float64_attribute` (Number) example float64 attribute - `int64_attribute` (Number) example int64 attribute - `list_attribute` (List of String) example list attribute +- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) +- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `map_attribute` (Map of String) example map attribute - `number_attribute` (Number) example number attribute - `object_attribute` (Object) example object attribute (see [below for nested schema](#nestedatt--object_attribute)) @@ -28,16 +30,10 @@ - `sensitive_set_attribute` (Set of String, Sensitive) example sensitive set attribute - `sensitive_string_attribute` (String, Sensitive) example sensitive string attribute - `set_attribute` (Set of String) example set attribute -- `string_attribute` (String) example string attribute -- `write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example write only string attribute - -### Blocks - -- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) -- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) - `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) - `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) +- `string_attribute` (String) example string attribute ### Read-Only @@ -49,11 +45,8 @@ Optional: -> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. - - `list_nested_block_attribute` (String) example list nested block attribute - `list_nested_block_attribute_with_default` (String) example list nested block attribute with default -- `list_nested_block_write_only_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example list nested block write-only attribute - `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) @@ -77,7 +70,7 @@ Optional: ### Nested Schema for `object_attribute` -Optional Attributes: +Optional: - `object_attribute_attribute` (String) @@ -85,7 +78,7 @@ Optional Attributes: ### Nested Schema for `object_attribute_with_nested_object_attribute` -Optional Attributes: +Optional: - `nested_object` (Object) (see [below for nested schema](#nestedobjatt--object_attribute_with_nested_object_attribute--nested_object)) - `object_attribute_attribute` (String) @@ -93,7 +86,7 @@ Optional Attributes: ### Nested Schema for `object_attribute_with_nested_object_attribute.nested_object` -Optional Attributes: +Optional: - `nested_object_attribute` (String) @@ -102,45 +95,15 @@ Optional Attributes: ### Nested Schema for `sensitive_object_attribute` -Optional Attributes: +Optional: - `object_attribute_attribute` (String) - -### Nested Schema for `list_nested_block` - -Optional Attributes: - -- `list_nested_block_attribute` (String) example list nested block attribute -- `list_nested_block_attribute_with_default` (String) example list nested block attribute with default - -Blocks: - -- `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) - - -### Nested Schema for `list_nested_block.nested_list_block` - -Optional Attributes: - -- `nested_block_string_attribute` (String) example nested block string attribute - - - - -### Nested Schema for `list_nested_block_sensitive_nested_attribute` - -Optional Attributes: - -- `list_nested_block_attribute` (String) example list nested block attribute -- `list_nested_block_sensitive_attribute` (String, Sensitive) example sensitive list nested block attribute - - ### Nested Schema for `set_nested_block` -Optional Attributes: +Optional: > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. @@ -151,7 +114,7 @@ Optional Attributes: ### Nested Schema for `single_nested_block` -Optional Attributes: +Optional: - `single_nested_block_attribute` (String) example single nested block attribute @@ -159,7 +122,7 @@ Optional Attributes: ### Nested Schema for `single_nested_block_sensitive_nested_attribute` -Optional Attributes: +Optional: - `single_nested_block_attribute` (String) example single nested block attribute - `single_nested_block_sensitive_attribute` (String, Sensitive) example sensitive single nested block attribute diff --git a/internal/schemamd/testdata/framework_types_blocks_section.md b/internal/schemamd/testdata/framework_types_blocks_section.md new file mode 100644 index 00000000..6601fab6 --- /dev/null +++ b/internal/schemamd/testdata/framework_types_blocks_section.md @@ -0,0 +1,132 @@ +## Schema + +### Optional Attributes + +- `bool_attribute` (Boolean) example bool attribute +- `float64_attribute` (Number) example float64 attribute +- `int64_attribute` (Number) example int64 attribute +- `list_attribute` (List of String) example list attribute +- `map_attribute` (Map of String) example map attribute +- `number_attribute` (Number) example number attribute +- `object_attribute` (Object) example object attribute (see [below for nested schema](#nestedatt--object_attribute)) +- `object_attribute_with_nested_object_attribute` (Object) example object attribute with nested object attribute (see [below for nested schema](#nestedatt--object_attribute_with_nested_object_attribute)) +- `sensitive_bool_attribute` (Boolean, Sensitive) example sensitive bool attribute +- `sensitive_float64_attribute` (Number, Sensitive) example sensitive float64 attribute +- `sensitive_int64_attribute` (Number, Sensitive) example sensitive int64 attribute +- `sensitive_list_attribute` (List of String, Sensitive) example sensitive list attribute +- `sensitive_map_attribute` (Map of String, Sensitive) example sensitive map attribute +- `sensitive_number_attribute` (Number, Sensitive) example sensitive number attribute +- `sensitive_object_attribute` (Object, Sensitive) example sensitive object attribute (see [below for nested schema](#nestedatt--sensitive_object_attribute)) +- `sensitive_set_attribute` (Set of String, Sensitive) example sensitive set attribute +- `sensitive_string_attribute` (String, Sensitive) example sensitive string attribute +- `set_attribute` (Set of String) example set attribute +- `string_attribute` (String) example string attribute + +### Blocks + +- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) +- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) +- `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) +- `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) +- `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) + +### Read-Only + +- `id` (String) The ID of this resource. +- `set_nested_block_sensitive_nested_attribute` (Block Set) example sensitive set nested block (see [below for nested schema](#nestedblock--set_nested_block_sensitive_nested_attribute)) + + +### Nested Schema for `object_attribute` + +Optional Attributes: + +- `object_attribute_attribute` (String) + + + +### Nested Schema for `object_attribute_with_nested_object_attribute` + +Optional Attributes: + +- `nested_object` (Object) (see [below for nested schema](#nestedobjatt--object_attribute_with_nested_object_attribute--nested_object)) +- `object_attribute_attribute` (String) + + +### Nested Schema for `object_attribute_with_nested_object_attribute.nested_object` + +Optional Attributes: + +- `nested_object_attribute` (String) + + + + +### Nested Schema for `sensitive_object_attribute` + +Optional Attributes: + +- `object_attribute_attribute` (String) + + + +### Nested Schema for `list_nested_block` + +Optional Attributes: + +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_attribute_with_default` (String) example list nested block attribute with default + +Blocks: + +- `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) + + +### Nested Schema for `list_nested_block.nested_list_block` + +Optional Attributes: + +- `nested_block_string_attribute` (String) example nested block string attribute + + + + +### Nested Schema for `list_nested_block_sensitive_nested_attribute` + +Optional Attributes: + +- `list_nested_block_attribute` (String) example list nested block attribute +- `list_nested_block_sensitive_attribute` (String, Sensitive) example sensitive list nested block attribute + + + +### Nested Schema for `set_nested_block` + +Optional Attributes: + +- `set_nested_block_attribute` (String) example set nested block attribute + + + +### Nested Schema for `single_nested_block` + +Optional Attributes: + +- `single_nested_block_attribute` (String) example single nested block attribute + + + +### Nested Schema for `single_nested_block_sensitive_nested_attribute` + +Optional Attributes: + +- `single_nested_block_attribute` (String) example single nested block attribute +- `single_nested_block_sensitive_attribute` (String, Sensitive) example sensitive single nested block attribute + + + +### Nested Schema for `set_nested_block_sensitive_nested_attribute` + +Read-Only: + +- `set_nested_block_attribute` (String) example set nested block attribute +- `set_nested_block_sensitive_attribute` (String, Sensitive) example sensitive set nested block attribute From 9b54e49987711b6966d43901a4b89cf897040992 Mon Sep 17 00:00:00 2001 From: Toni Kangas Date: Wed, 4 Feb 2026 15:59:14 +0200 Subject: [PATCH 4/5] Update testdata --- ...provider_success_all_framework_types.txtar | 14 +- ...s_all_framework_types_blocks_section.txtar | 4 +- ...mework_provider_success_no_templates.txtar | 278 ------------------ internal/schemamd/testdata/framework_types.md | 4 + .../framework_types_blocks_section.md | 17 ++ 5 files changed, 31 insertions(+), 286 deletions(-) delete mode 100644 cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar index 238d320e..370a64a5 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar @@ -69,6 +69,12 @@ example resource ## Schema +### Required + +> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. + +- `required_write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example required write-only string attribute + ### Optional > **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. @@ -93,17 +99,11 @@ example resource - `sensitive_set_attribute` (Set of String, Sensitive) example sensitive set attribute - `sensitive_string_attribute` (String, Sensitive) example sensitive string attribute - `set_attribute` (Set of String) example set attribute -- `string_attribute` (String) example string attribute -- `write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example write-only string attribute - -### Blocks - -- `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) -- `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) - `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) - `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) - `string_attribute` (String) example string attribute +- `write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example write-only string attribute ### Read-Only diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar index f74165a3..61b4c820 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar @@ -19,6 +19,9 @@ generating new template for "scaffolding_example" generating missing data source content generating missing function content generating new template for function "scaffolding" +generating missing ephemeral resource content +generating missing action content +generating missing list resource content generating missing provider content generating new template for "terraform-provider-scaffolding" rendering static website @@ -31,7 +34,6 @@ rendering "resources/example.md.tmpl" --- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "scaffolding Provider" -subcategory: "" description: |- Example provider --- 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 deleted file mode 100644 index 8ac9b9ad..00000000 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar +++ /dev/null @@ -1,278 +0,0 @@ -# Copyright (c) HashiCorp, Inc. -# SPDX-License-Identifier: MPL-2.0 - -# 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 -cmp stdout expected-output.txt -cmp docs/index.md expected-index.md -cmp docs/data-sources/example.md expected-datasource.md -cmp docs/resources/example.md expected-resource.md -cmp docs/functions/example.md expected-function.md - --- expected-output.txt -- -rendering website for provider "terraform-provider-scaffolding" (as "terraform-provider-scaffolding") -exporting schema from JSON file -getting provider schema -generating missing templates -generating missing resource content -generating new template for "scaffolding_example" -generating missing data source content -generating new template for data-source "scaffolding_example" -generating missing function content -generating new template for function "example" -generating missing provider content -generating new template for "terraform-provider-scaffolding" -rendering static website -cleaning rendered website dir -rendering templated website to static markdown -rendering "data-sources/example.md.tmpl" -rendering "functions/example.md.tmpl" -rendering "index.md.tmpl" -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" -subcategory: "" -description: |- - Example data source ---- - -# scaffolding_example (Data Source) - -Example data source - -## Example Usage - -```terraform -data "scaffolding_example" "example" { - configurable_attribute = "some-value" -} -``` - - -## Schema - -### Optional - -- `configurable_attribute` (String) Example configurable attribute - -### Read-Only - -- `id` (String) Example identifier --- expected-function.md -- ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "example function - terraform-provider-scaffolding" -subcategory: "" -description: |- - Echo a string ---- - -# function: example - -Given a string value, returns the same value. - -## Example Usage - -```terraform -output "test" { - value = provider::scaffolding::example("testvalue1", "testvalue2") -} -``` - -## Signature - - -```text -example(input string, variadicInput string...) string -``` - -## Arguments - - -1. `input` (String) Value to echo. - -1. `variadicInput` (Variadic, String) Variadic input to echo. --- expected-index.md -- ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "scaffolding Provider" -subcategory: "" -description: |- - Example provider ---- - -# scaffolding Provider - -Example provider - -## Example Usage - -```terraform -provider "scaffolding" { - # example configuration here -} -``` - - -## Schema - -### Optional - -- `endpoint` (String) Example provider attribute --- expected-resource.md -- ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "scaffolding_example Resource - terraform-provider-scaffolding" -subcategory: "" -description: |- - Example resource ---- - -# scaffolding_example (Resource) - -Example resource - -## Example Usage - -```terraform -resource "scaffolding_example" "example" { - configurable_attribute = "some-value" -} -``` - - -## Schema - -### Optional - -- `configurable_attribute` (String) Example configurable attribute -- `defaulted` (String) Example configurable attribute with default value - -### Read-Only - -- `id` (String) Example identifier --- 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/functions/example/function.tf -- -output "test" { - value = provider::scaffolding::example("testvalue1", "testvalue2") -} --- examples/provider/provider.tf -- -provider "scaffolding" { - # example configuration here -} --- examples/resources/scaffolding_example/resource.tf -- -resource "scaffolding_example" "example" { - configurable_attribute = "some-value" -} - --- 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" - } - } - }, - "functions": { - "example": { - "description": "Given a string value, returns the same value.", - "summary": "Echo a string", - "return_type": "string", - "parameters": [ - { - "name": "input", - "description": "Value to echo.", - "type": "string" - } - ], - "variadic_parameter": { - "name": "variadicInput", - "description": "Variadic input to echo.", - "type": "string" - } - } - } - } - } -} \ No newline at end of file diff --git a/internal/schemamd/testdata/framework_types.md b/internal/schemamd/testdata/framework_types.md index 7041fe64..8607a931 100644 --- a/internal/schemamd/testdata/framework_types.md +++ b/internal/schemamd/testdata/framework_types.md @@ -34,6 +34,7 @@ - `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) - `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) - `string_attribute` (String) example string attribute +- `write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example write only string attribute ### Read-Only @@ -45,8 +46,11 @@ Optional: +> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. + - `list_nested_block_attribute` (String) example list nested block attribute - `list_nested_block_attribute_with_default` (String) example list nested block attribute with default +- `list_nested_block_write_only_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example list nested block write-only attribute - `nested_list_block` (Block List) (see [below for nested schema](#nestedblock--list_nested_block--nested_list_block)) diff --git a/internal/schemamd/testdata/framework_types_blocks_section.md b/internal/schemamd/testdata/framework_types_blocks_section.md index 6601fab6..83fa9ab5 100644 --- a/internal/schemamd/testdata/framework_types_blocks_section.md +++ b/internal/schemamd/testdata/framework_types_blocks_section.md @@ -1,7 +1,15 @@ ## Schema +### Required Attributes + +> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. + +- `required_write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example required write-only string attribute + ### Optional Attributes +> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. + - `bool_attribute` (Boolean) example bool attribute - `float64_attribute` (Number) example float64 attribute - `int64_attribute` (Number) example int64 attribute @@ -21,9 +29,12 @@ - `sensitive_string_attribute` (String, Sensitive) example sensitive string attribute - `set_attribute` (Set of String) example set attribute - `string_attribute` (String) example string attribute +- `write_only_string_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example write only string attribute ### Blocks +> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. + - `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) - `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) @@ -73,8 +84,11 @@ Optional Attributes: Optional Attributes: +> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. + - `list_nested_block_attribute` (String) example list nested block attribute - `list_nested_block_attribute_with_default` (String) example list nested block attribute with default +- `list_nested_block_write_only_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example list nested block write-only attribute Blocks: @@ -103,7 +117,10 @@ Optional Attributes: Optional Attributes: +> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later. + - `set_nested_block_attribute` (String) example set nested block attribute +- `set_nested_block_write_only_attribute` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) example set nested block write-only attribute From dd790f2fd4c7710451fc50cf776d2327ebbd8c07 Mon Sep 17 00:00:00 2001 From: Toni Kangas Date: Tue, 17 Mar 2026 20:20:52 +0200 Subject: [PATCH 5/5] Remove type label from single nested blocks Parsing optionality does not work for resources implemented with plugin framework. --- ...rovider_success_all_framework_types_blocks_section.txtar | 5 +++-- internal/provider/generate.go | 2 +- internal/schemamd/render.go | 6 +++--- .../schemamd/testdata/framework_types_blocks_section.md | 4 ++-- internal/schemamd/write_block_type_description.go | 4 +++- internal/schemamd/write_block_type_description_test.go | 2 +- 6 files changed, 13 insertions(+), 10 deletions(-) diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar index 61b4c820..109ba208 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types_blocks_section.txtar @@ -22,6 +22,7 @@ generating new template for function "scaffolding" generating missing ephemeral resource content generating missing action content generating missing list resource content +generating missing state store content generating missing provider content generating new template for "terraform-provider-scaffolding" rendering static website @@ -95,8 +96,8 @@ example resource - `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) - `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) -- `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) -- `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) +- `single_nested_block` (Block) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) +- `single_nested_block_sensitive_nested_attribute` (Block) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) ### Read-Only diff --git a/internal/provider/generate.go b/internal/provider/generate.go index b68ea501..a6c32cd9 100644 --- a/internal/provider/generate.go +++ b/internal/provider/generate.go @@ -1001,7 +1001,7 @@ func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema, b slices.Sort(exampleFiles) tmpl := resourceTemplate(tmplData) - render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "State Store", exampleFilePath, exampleFiles, "", "", "", resSchema, nil) + render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "State Store", exampleFilePath, exampleFiles, "", "", "", resSchema, nil, blocksSection) if err != nil { return fmt.Errorf("unable to render state store template %q: %w", rel, err) } diff --git a/internal/schemamd/render.go b/internal/schemamd/render.go index 821f7c87..053d45ea 100644 --- a/internal/schemamd/render.go +++ b/internal/schemamd/render.go @@ -293,7 +293,7 @@ func writeAttribute(w io.Writer, path []string, att *tfjson.SchemaAttribute, gro return nestedTypes, nil } -func writeBlockType(w io.Writer, path []string, block *tfjson.SchemaBlockType) ([]nestedType, error) { +func writeBlockType(w io.Writer, path []string, block *tfjson.SchemaBlockType, blocksSection bool) ([]nestedType, error) { name := path[len(path)-1] _, err := io.WriteString(w, "- `"+name+"` ") @@ -301,7 +301,7 @@ func writeBlockType(w io.Writer, path []string, block *tfjson.SchemaBlockType) ( return nil, err } - err = WriteBlockTypeDescription(w, block) + err = WriteBlockTypeDescription(w, block, blocksSection) if err != nil { return nil, fmt.Errorf("unable to write block description for %q: %w", name, err) } @@ -482,7 +482,7 @@ nameLoop: path = append(path, name) if childBlock, ok := block.NestedBlocks[name]; ok { - nt, err := writeBlockType(w, path, childBlock) + nt, err := writeBlockType(w, path, childBlock, blocksSection) if err != nil { return fmt.Errorf("unable to render block %q: %w", name, err) } diff --git a/internal/schemamd/testdata/framework_types_blocks_section.md b/internal/schemamd/testdata/framework_types_blocks_section.md index 83fa9ab5..ed55634a 100644 --- a/internal/schemamd/testdata/framework_types_blocks_section.md +++ b/internal/schemamd/testdata/framework_types_blocks_section.md @@ -38,8 +38,8 @@ - `list_nested_block` (Block List) example list nested block (see [below for nested schema](#nestedblock--list_nested_block)) - `list_nested_block_sensitive_nested_attribute` (Block List) (see [below for nested schema](#nestedblock--list_nested_block_sensitive_nested_attribute)) - `set_nested_block` (Block Set) example set nested block (see [below for nested schema](#nestedblock--set_nested_block)) -- `single_nested_block` (Block, Optional) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) -- `single_nested_block_sensitive_nested_attribute` (Block, Optional) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) +- `single_nested_block` (Block) example single nested block (see [below for nested schema](#nestedblock--single_nested_block)) +- `single_nested_block_sensitive_nested_attribute` (Block) example sensitive single nested block (see [below for nested schema](#nestedblock--single_nested_block_sensitive_nested_attribute)) ### Read-Only diff --git a/internal/schemamd/write_block_type_description.go b/internal/schemamd/write_block_type_description.go index 65e784cb..0757aa4d 100644 --- a/internal/schemamd/write_block_type_description.go +++ b/internal/schemamd/write_block_type_description.go @@ -11,7 +11,7 @@ import ( tfjson "github.com/hashicorp/terraform-json" ) -func WriteBlockTypeDescription(w io.Writer, block *tfjson.SchemaBlockType) error { +func WriteBlockTypeDescription(w io.Writer, block *tfjson.SchemaBlockType, noSingleNestedType bool) error { _, err := io.WriteString(w, "(Block") if err != nil { return err @@ -41,6 +41,8 @@ func WriteBlockTypeDescription(w io.Writer, block *tfjson.SchemaBlockType) error if block.NestingMode == tfjson.SchemaNestingModeSingle { switch { + case noSingleNestedType: + // Omit required, optional or read-only label. case childBlockIsRequired(block): _, err = io.WriteString(w, ", Required") if err != nil { diff --git a/internal/schemamd/write_block_type_description_test.go b/internal/schemamd/write_block_type_description_test.go index 9f6d7d91..1b4b63d5 100644 --- a/internal/schemamd/write_block_type_description_test.go +++ b/internal/schemamd/write_block_type_description_test.go @@ -223,7 +223,7 @@ func TestWriteBlockTypeDescription(t *testing.T) { t.Parallel() b := &strings.Builder{} - err := schemamd.WriteBlockTypeDescription(b, c.bt) + err := schemamd.WriteBlockTypeDescription(b, c.bt, false) if err != nil { t.Fatal(err) }