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 c027d0d2..3f6010cd 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 @@ -49,7 +49,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -102,7 +102,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute @@ -149,7 +149,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 bffc2df1..e4b3d497 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 @@ -49,7 +49,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -102,7 +102,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute @@ -149,7 +149,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 e8a4057e..01e3829e 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 @@ -56,7 +56,7 @@ data "scaffolding_example" "example" { ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -87,7 +87,7 @@ provider "scaffolding" { ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -114,7 +114,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 bff443ea..0c8fa4eb 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 @@ -228,7 +228,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. @@ -339,7 +339,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. @@ -456,7 +456,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. @@ -577,7 +577,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. @@ -663,7 +663,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. @@ -758,7 +758,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 45910e19..040d727b 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 @@ -45,7 +45,7 @@ Example provider ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -66,12 +66,14 @@ example resource ## Schema -### Optional Attributes +### Optional - `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 +- `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)) @@ -86,88 +88,80 @@ 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 - -### 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 - `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 @@ -175,7 +169,7 @@ Optional Attributes: ### Nested Schema for `single_nested_block` -Optional Attributes: +Optional: - `single_nested_block_attribute` (String) example single nested block attribute @@ -183,7 +177,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 a3c21946..187ea8b9 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 @@ -48,7 +48,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -148,7 +148,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute @@ -195,7 +195,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 7fb56ae8..15680887 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 @@ -47,7 +47,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `configurable_attribute` (String) Example configurable attribute @@ -147,7 +147,7 @@ RenderedProviderName: terraform-provider-scaffolding SchemaMarkdown: ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute @@ -194,7 +194,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_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 cba81a8e..943c54c8 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 @@ -42,7 +42,7 @@ Example provider ## Schema -### Optional Attributes +### Optional - `endpoint` (String) Example provider attribute -- expected-resource.md -- @@ -63,18 +63,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)) @@ -91,31 +88,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) @@ -123,7 +120,7 @@ Required Attributes: ### Nested Schema for `set_nested_block_optional_id` -Optional Attributes: +Optional: - `id` (String) @@ -131,7 +128,7 @@ Optional Attributes: ### Nested Schema for `set_nested_block_required_id` -Required Attributes: +Required: - `id` (String) @@ -139,7 +136,7 @@ Required Attributes: ### Nested Schema for `single_nested_block_optional_id` -Optional Attributes: +Optional: - `id` (String) @@ -147,7 +144,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 8678d227..91597c24 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 @@ -203,7 +203,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. @@ -314,7 +314,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. @@ -431,7 +431,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. @@ -552,7 +552,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. @@ -638,7 +638,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. @@ -733,7 +733,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 77dbc96f..c7ba9370 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 d0c3c965..1325d781 100644 --- a/internal/provider/generate.go +++ b/internal/provider/generate.go @@ -79,6 +79,7 @@ var ( ) type generator struct { + blocksSection bool ignoreDeprecated bool tfVersion string @@ -104,7 +105,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() @@ -136,6 +137,7 @@ func Generate(ui cli.Ui, providerDir, providerName, providersSchemaPath, rendere } g := &generator{ + blocksSection: blocksSection, ignoreDeprecated: ignoreDeprecated, tfVersion: tfVersion, @@ -231,7 +233,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) } @@ -442,7 +444,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) { @@ -532,7 +534,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, "Data Source", exampleFilePath, "", resSchema) + render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "Data Source", exampleFilePath, "", resSchema, blocksSection) if err != nil { return fmt.Errorf("unable to render data source template %q: %w", rel, err) } @@ -550,7 +552,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, "Resource", exampleFilePath, importFilePath, resSchema) + render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "Resource", exampleFilePath, importFilePath, resSchema, blocksSection) if err != nil { return fmt.Errorf("unable to render resource template %q: %w", rel, err) } @@ -583,7 +585,7 @@ func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema) e if relFile == "index.md.tmpl" { tmpl := providerTemplate(tmplData) exampleFilePath := filepath.Join(g.ProviderExamplesDir(), "provider", "provider.tf") - render, err := tmpl.Render(g.providerDir, g.providerName, g.renderedProviderName, exampleFilePath, providerSchema.ConfigSchema) + render, err := tmpl.Render(g.providerDir, g.providerName, g.renderedProviderName, exampleFilePath, 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 58766489..63baa591 100644 --- a/internal/provider/template.go +++ b/internal/provider/template.go @@ -120,9 +120,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, schema *tfjson.Schema) (string, error) { +func (t providerTemplate) Render(providerDir, providerName, renderedProviderName, exampleFile 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) } @@ -158,9 +158,9 @@ func (t providerTemplate) Render(providerDir, providerName, renderedProviderName }) } -func (t resourceTemplate) Render(providerDir, name, providerName, renderedProviderName, typeName, exampleFile, importFile string, schema *tfjson.Schema) (string, error) { +func (t resourceTemplate) Render(providerDir, name, providerName, renderedProviderName, typeName, exampleFile, importFile 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) } diff --git a/internal/provider/template_test.go b/internal/provider/template_test.go index 82bcc3b5..cdd0af36 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", "provider.tf", &schema) + result, err := tpl.Render("testdata/test-provider-dir", "testTemplate", "test-provider", "test-provider", "Resource", "provider.tf", "provider.tf", &schema, 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", &schema) + result, err := tpl.Render("testdata/test-provider-dir", "testTemplate", "test-provider", "provider.tf", &schema, false) if err != nil { t.Error(err) } diff --git a/internal/schemamd/render.go b/internal/schemamd/render.go index aedccc8d..3cf20ec4 100644 --- a/internal/schemamd/render.go +++ b/internal/schemamd/render.go @@ -21,13 +21,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) } @@ -49,7 +49,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}, @@ -57,6 +64,14 @@ var ( } ) +func getGroupFilters(blocksSection bool) []groupFilter { + if blocksSection { + return blocksSectionGroupFilters + } + + return defaultGroupFilters +} + type nestedType struct { anchorID string pathTitle string @@ -180,8 +195,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: @@ -211,7 +226,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) @@ -222,6 +237,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 { @@ -337,7 +353,7 @@ nameLoop: } } - err := writeNestedTypes(w, nestedTypes) + err := writeNestedTypes(w, nestedTypes, blocksSection) if err != nil { return err } @@ -345,7 +361,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 { @@ -359,17 +375,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 } @@ -451,7 +467,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 @@ -484,7 +500,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 } @@ -492,13 +508,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] @@ -543,7 +560,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 1770be42..f698ea31 100644 --- a/internal/schemamd/render_test.go +++ b/internal/schemamd/render_test.go @@ -19,40 +19,60 @@ 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, }, } { c := c @@ -77,7 +97,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 6601fab6..06c04261 100644 --- a/internal/schemamd/testdata/framework_types.md +++ b/internal/schemamd/testdata/framework_types.md @@ -1,11 +1,13 @@ ## Schema -### Optional Attributes +### Optional - `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 +- `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)) @@ -20,88 +22,80 @@ - `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)) +- `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 @@ -109,7 +103,7 @@ Optional Attributes: ### Nested Schema for `single_nested_block` -Optional Attributes: +Optional: - `single_nested_block_attribute` (String) example single nested block attribute @@ -117,7 +111,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