From 8f314c79f9582824229bd3a9451d76a4f4efc477 Mon Sep 17 00:00:00 2001 From: Selena Goods Date: Thu, 20 Feb 2025 11:08:54 -0500 Subject: [PATCH 1/2] Add link to write-only user documentation in markdown --- ...work_provider_success_all_framework_types.txtar | 2 +- .../testdata/deep_nested_write_only_attributes.md | 14 +++++++------- internal/schemamd/testdata/framework_types.md | 6 +++--- internal/schemamd/write_attribute_description.go | 2 +- .../schemamd/write_attribute_description_test.go | 2 +- .../write_nested_attribute_type_description.go | 2 +- ...write_nested_attribute_type_description_test.go | 2 +- 7 files changed, 15 insertions(+), 15 deletions(-) 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 e98192bb..af2cc9d5 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 @@ -93,7 +93,7 @@ example resource - `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) example write-only 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/internal/schemamd/testdata/deep_nested_write_only_attributes.md b/internal/schemamd/testdata/deep_nested_write_only_attributes.md index b421fad2..428fe7e5 100644 --- a/internal/schemamd/testdata/deep_nested_write_only_attributes.md +++ b/internal/schemamd/testdata/deep_nested_write_only_attributes.md @@ -13,34 +13,34 @@ Optional: -- `level_two` (Attributes, Write-only) (see [below for nested schema](#nestedatt--level_one--level_two)) +- `level_two` (Attributes, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) (see [below for nested schema](#nestedatt--level_one--level_two)) ### Nested Schema for `level_one.level_two` Optional: -- `level_three` (Attributes, Write-only) (see [below for nested schema](#nestedatt--level_one--level_two--level_three)) +- `level_three` (Attributes, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) (see [below for nested schema](#nestedatt--level_one--level_two--level_three)) ### Nested Schema for `level_one.level_two.level_three` Optional: -- `level_four_primary` (Attributes, Write-only) (see [below for nested schema](#nestedatt--level_one--level_two--level_three--level_four_primary)) -- `level_four_secondary` (String, Write-only) +- `level_four_primary` (Attributes, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) (see [below for nested schema](#nestedatt--level_one--level_two--level_three--level_four_primary)) +- `level_four_secondary` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) ### Nested Schema for `level_one.level_two.level_three.level_four_primary` Optional: -- `level_five` (Attributes, Write-only) 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, Write-only) Parent should be level_one.level_two.level_three.level_four_primary. +- `level_five` (Attributes, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) 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, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) 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: -- `level_five_string` (String, Write-only) Parent should be level_one.level_two.level_three.level_four_primary.level_five. +- `level_five_string` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) 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 781b5bd2..38c0314c 100644 --- a/internal/schemamd/testdata/framework_types.md +++ b/internal/schemamd/testdata/framework_types.md @@ -26,7 +26,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) example write only 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 @@ -40,7 +40,7 @@ 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 -- `list_nested_block_write_only_attribute` (String, Write-only) example list nested block write-only attribute +- `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)) @@ -100,7 +100,7 @@ Optional: Optional: - `set_nested_block_attribute` (String) example set nested block attribute -- `set_nested_block_write_only_attribute` (String, Write-only) example set nested block write-only 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 diff --git a/internal/schemamd/write_attribute_description.go b/internal/schemamd/write_attribute_description.go index f31cccfe..26db2a8c 100644 --- a/internal/schemamd/write_attribute_description.go +++ b/internal/schemamd/write_attribute_description.go @@ -59,7 +59,7 @@ func WriteAttributeDescription(w io.Writer, att *tfjson.SchemaAttribute, include } if att.WriteOnly { - _, err := io.WriteString(w, ", Write-only") + _, err := io.WriteString(w, ", [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)") if err != nil { return err } diff --git a/internal/schemamd/write_attribute_description_test.go b/internal/schemamd/write_attribute_description_test.go index ee09d4ca..34bade4e 100644 --- a/internal/schemamd/write_attribute_description_test.go +++ b/internal/schemamd/write_attribute_description_test.go @@ -31,7 +31,7 @@ func TestWriteAttributeDescription(t *testing.T) { }, }, { - "(String, Required, Write-only) This is an attribute.", + "(String, Required, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) This is an attribute.", &tfjson.SchemaAttribute{ AttributeType: cty.String, Required: true, diff --git a/internal/schemamd/write_nested_attribute_type_description.go b/internal/schemamd/write_nested_attribute_type_description.go index c2f0c117..a45bdb1e 100644 --- a/internal/schemamd/write_nested_attribute_type_description.go +++ b/internal/schemamd/write_nested_attribute_type_description.go @@ -98,7 +98,7 @@ func WriteNestedAttributeTypeDescription(w io.Writer, att *tfjson.SchemaAttribut } if att.WriteOnly { - _, err := io.WriteString(w, ", Write-only") + _, err := io.WriteString(w, ", [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)") if err != nil { return err } diff --git a/internal/schemamd/write_nested_attribute_type_description_test.go b/internal/schemamd/write_nested_attribute_type_description_test.go index 81a12bf4..9b48ea10 100644 --- a/internal/schemamd/write_nested_attribute_type_description_test.go +++ b/internal/schemamd/write_nested_attribute_type_description_test.go @@ -39,7 +39,7 @@ func TestWriteNestedAttributeTypeDescription(t *testing.T) { }, }, { - "(Attributes, Optional, Write-only) This is an attribute.", + "(Attributes, Optional, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) This is an attribute.", &tfjson.SchemaAttribute{ Description: "This is an attribute.", AttributeNestedType: &tfjson.SchemaNestedAttributeType{ From 80940bfe456b5ed3ce0027cc428e4cfed7b22da5 Mon Sep 17 00:00:00 2001 From: Selena Goods Date: Thu, 20 Feb 2025 12:10:34 -0500 Subject: [PATCH 2/2] Add write-only version callout to all relevant sections --- ...provider_success_all_framework_types.txtar | 15 +++++++++++++ internal/schemamd/behaviors.go | 21 ++++++++++++++++++ internal/schemamd/render.go | 22 +++++++++++++++++++ internal/schemamd/testdata/framework_types.md | 12 ++++++++++ .../testdata/framework_types.schema.json | 7 ++++++ 5 files changed, 77 insertions(+) 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 af2cc9d5..813b5c6f 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 @@ -67,8 +67,16 @@ 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. + - `bool_attribute` (Boolean) example bool attribute - `float64_attribute` (Number) example float64 attribute - `int64_attribute` (Number) example int64 attribute @@ -426,6 +434,13 @@ scaffolding(stringInput string, boolInput bool, float64Input number, int64Input "description_kind": "markdown", "optional": true, "write_only": true + }, + "required_write_only_string_attribute": { + "type": "string", + "description": "example required write-only string attribute", + "description_kind": "markdown", + "required": true, + "write_only": true } }, "block_types": { diff --git a/internal/schemamd/behaviors.go b/internal/schemamd/behaviors.go index 561f34c1..969f1d40 100644 --- a/internal/schemamd/behaviors.go +++ b/internal/schemamd/behaviors.go @@ -11,6 +11,10 @@ func childAttributeIsRequired(att *tfjson.SchemaAttribute) bool { return att.Required } +func childAttributeIsWriteOnly(att *tfjson.SchemaAttribute) bool { + return att.WriteOnly +} + func childBlockIsRequired(block *tfjson.SchemaBlockType) bool { return block.MinItems > 0 } @@ -77,3 +81,20 @@ func childBlockIsReadOnly(block *tfjson.SchemaBlockType) bool { return true } + +// childBlockContainsWriteOnly returns true for blocks that contain any write-only attributes. +func childBlockContainsWriteOnly(block *tfjson.SchemaBlockType) bool { + for _, childBlock := range block.Block.NestedBlocks { + if childBlockContainsWriteOnly(childBlock) { + return true + } + } + + for _, childAtt := range block.Block.Attributes { + if childAttributeIsWriteOnly(childAtt) { + return true + } + } + + return false +} diff --git a/internal/schemamd/render.go b/internal/schemamd/render.go index a459d0ba..5033c6ac 100644 --- a/internal/schemamd/render.go +++ b/internal/schemamd/render.go @@ -304,6 +304,28 @@ nameLoop: return err } + for _, name := range sortedNames { + if childBlock, ok := block.NestedBlocks[name]; ok { + if childBlockContainsWriteOnly(childBlock) { + _, err := io.WriteString(w, + "> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.\n\n") + if err != nil { + return err + } + break + } + } else if childAtt, ok := block.Attributes[name]; ok { + if childAttributeIsWriteOnly(childAtt) { + _, err := io.WriteString(w, + "> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.\n\n") + if err != nil { + return err + } + break + } + } + } + for _, name := range sortedNames { path := make([]string, len(parents), len(parents)+1) copy(path, parents) diff --git a/internal/schemamd/testdata/framework_types.md b/internal/schemamd/testdata/framework_types.md index 38c0314c..8607a931 100644 --- a/internal/schemamd/testdata/framework_types.md +++ b/internal/schemamd/testdata/framework_types.md @@ -1,7 +1,15 @@ ## 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. + - `bool_attribute` (Boolean) example bool attribute - `float64_attribute` (Number) example float64 attribute - `int64_attribute` (Number) example int64 attribute @@ -38,6 +46,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 @@ -99,6 +109,8 @@ Optional: Optional: +> **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 diff --git a/internal/schemamd/testdata/framework_types.schema.json b/internal/schemamd/testdata/framework_types.schema.json index eb7d810a..91f73508 100644 --- a/internal/schemamd/testdata/framework_types.schema.json +++ b/internal/schemamd/testdata/framework_types.schema.json @@ -175,6 +175,13 @@ "description_kind": "markdown", "optional": true, "write_only": true + }, + "required_write_only_string_attribute": { + "type": "string", + "description": "example required write-only string attribute", + "description_kind": "markdown", + "required": true, + "write_only": true } }, "block_types": {