generate: Add hyperlinks to user documentation and version callouts for write-only attribute documentation (#451)

* Add link to write-only user documentation in markdown

* Add write-only version callout to all relevant sections

Author: SBGoods

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

@@ -67,8 +67,16 @@ example resource
 <!-- schema generated by tfplugindocs -->
 ## 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
@@ -93,7 +101,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
 
@@ -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": {

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
+}

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)

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))
 
 <a id="nestedatt--level_one--level_two"></a>
 ### 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))
 
 <a id="nestedatt--level_one--level_two--level_three"></a>
 ### 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))
 
 <a id="nestedatt--level_one--level_two--level_three--level_four_primary"></a>
 ### 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.
 
 <a id="nestedatt--level_one--level_two--level_three--level_four_primary--level_five"></a>
 ### 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.

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
@@ -26,7 +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) 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
 
@@ -38,9 +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) 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))
 
 <a id="nestedblock--list_nested_block--nested_list_block"></a>
@@ -99,8 +109,10 @@ 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) 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
 
 
 <a id="nestedblock--single_nested_block"></a>

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": {

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
 		}

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,

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
 		}

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{