Group nested attributes by optional, required and read-only

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.13.0 (TBD)
+
+ENHANCEMENTS:
+
+* Group nested attributes by optional, required and read-only ([#163](https://github.com/hashicorp/terraform-plugin-docs/pull/163)).
+
 # 0.12.0 (June 29, 2022)
 
 BUG FIXES:

schemamd/render.go

@@ -475,36 +475,55 @@ func writeObjectChildren(w io.Writer, parents []string, ty cty.Type, group group
 }
 
 func writeNestedAttributeChildren(w io.Writer, parents []string, nestedAttributes *tfjson.SchemaNestedAttributeType, group groupFilter) error {
-	_, err := io.WriteString(w, group.nestedTitle+"\n\n")
-	if err != nil {
-		return err
-	}
-
 	sortedNames := []string{}
 	for n := range nestedAttributes.Attributes {
 		sortedNames = append(sortedNames, n)
 	}
 	sort.Strings(sortedNames)
-	nestedTypes := []nestedType{}
 
+	groups := map[int][]string{}
 	for _, name := range sortedNames {
 		att := nestedAttributes.Attributes[name]
-		path := append(parents, name)
 
-		nt, err := writeAttribute(w, path, att, group)
+		for i, gf := range groupFilters {
+			if gf.filterAttribute(att) {
+				groups[i] = append(groups[i], name)
+			}
+		}
+	}
+
+	nestedTypes := []nestedType{}
+
+	for i, gf := range groupFilters {
+		names, ok := groups[i]
+		if !ok || len(names) == 0 {
+			continue
+		}
+
+		_, err := io.WriteString(w, gf.nestedTitle+"\n\n")
 		if err != nil {
-			return fmt.Errorf("unable to render attribute %q: %w", name, err)
+			return err
 		}
 
-		nestedTypes = append(nestedTypes, nt...)
-	}
+		for _, name := range names {
+			att := nestedAttributes.Attributes[name]
+			path := append(parents, name)
 
-	_, err = io.WriteString(w, "\n")
-	if err != nil {
-		return err
+			nt, err := writeAttribute(w, path, att, group)
+			if err != nil {
+				return fmt.Errorf("unable to render attribute %q: %w", name, err)
+			}
+
+			nestedTypes = append(nestedTypes, nt...)
+		}
+
+		_, err = io.WriteString(w, "\n")
+		if err != nil {
+			return err
+		}
 	}
 
-	err = writeNestedTypes(w, nestedTypes)
+	err := writeNestedTypes(w, nestedTypes)
 	if err != nil {
 		return err
 	}

schemamd/testdata/awscc_acmpca_certificate.md

@@ -49,23 +49,26 @@ Optional:
 <a id="nestedatt--api_passthrough--extensions--certificate_policies"></a>
 ### Nested Schema for `api_passthrough.extensions.certificate_policies`
 
-Optional:
+Required:
 
 - `cert_policy_id` (String) String that contains X.509 ObjectIdentifier information.
+
+Optional:
+
 - `policy_qualifiers` (Attributes List) (see [below for nested schema](#nestedatt--api_passthrough--extensions--certificate_policies--policy_qualifiers))
 
 <a id="nestedatt--api_passthrough--extensions--certificate_policies--policy_qualifiers"></a>
 ### Nested Schema for `api_passthrough.extensions.certificate_policies.policy_qualifiers`
 
-Optional:
+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))
 
 <a id="nestedatt--api_passthrough--extensions--certificate_policies--policy_qualifiers--qualifier"></a>
 ### Nested Schema for `api_passthrough.extensions.certificate_policies.policy_qualifiers.qualifier`
 
-Optional:
+Required:
 
 - `cps_uri` (String)
 
@@ -135,7 +138,7 @@ Optional:
 <a id="nestedatt--api_passthrough--extensions--subject_alternative_names--edi_party_name"></a>
 ### Nested Schema for `api_passthrough.extensions.subject_alternative_names.uniform_resource_identifier`
 
-Optional:
+Required:
 
 - `name_assigner` (String)
 - `party_name` (String)
@@ -144,7 +147,7 @@ Optional:
 <a id="nestedatt--api_passthrough--extensions--subject_alternative_names--other_name"></a>
 ### Nested Schema for `api_passthrough.extensions.subject_alternative_names.uniform_resource_identifier`
 
-Optional:
+Required:
 
 - `type_id` (String) String that contains X.509 ObjectIdentifier information.
 - `value` (String)
@@ -177,7 +180,7 @@ Optional:
 <a id="nestedatt--validity_not_before"></a>
 ### Nested Schema for `validity_not_before`
 
-Optional:
+Required:
 
 - `type` (String)
 - `value` (Number)