Default id to "Read-Only" + allow for empty blocks/nested attributes to be documented

.go-version

@@ -1 +1 @@
-1.17.8
+1.17.9

CHANGELOG.md

@@ -3,21 +3,26 @@
 ENHANCEMENTS:
 
 * template functions: Added `split` to help separating a string into substrings ([#70](https://github.com/hashicorp/terraform-plugin-docs/pull/70)).
+
+BUG FIXES:
+
+* cmd/tflugindocs: Support for schemas containing empty nested attributes or empty nested blocks ([#99](https://github.com/hashicorp/terraform-plugin-docs/pull/99), [#134](https://github.com/hashicorp/terraform-plugin-docs/pull/134)).
+* schemamd: Attribute `ID` is considered "Read Only", unless there's a description defined, in which case it's handled like any other attribute in the schema ([#46](https://github.com/hashicorp/terraform-plugin-docs/pull/46), [#134](https://github.com/hashicorp/terraform-plugin-docs/pull/134)).
 
 # 0.7.0 (March 15, 2022)
 
 ENHANCEMENTS:
 
-* cmd/tfplugindocs: Use existing Terraform CLI binary if available on PATH, otherwise download latest Terraform CLI binary (https://github.com/hashicorp/terraform-plugin-docs/pull/124)
-* cmd/tfplugindocs: Added `tf-version` flag for specifying Terraform CLI binary version to download, superseding the PATH lookup (https://github.com/hashicorp/terraform-plugin-docs/pull/124)
+* cmd/tfplugindocs: Use existing Terraform CLI binary if available on PATH, otherwise download latest Terraform CLI binary (https://github.com/hashicorp/terraform-plugin-docs/pull/124).
+* cmd/tfplugindocs: Added `tf-version` flag for specifying Terraform CLI binary version to download, superseding the PATH lookup (https://github.com/hashicorp/terraform-plugin-docs/pull/124).
 
 BUG FIXES:
 
-* cmd/tfplugindocs: Swapped `.Type` and `.Name` resource and data source template fields so they correctly align (https://github.com/hashicorp/terraform-plugin-docs/pull/44)
-* schemamd: Switched attribute name rendering from bold text to code blocks so the Terraform Registry treats them as anchor links (https://github.com/hashicorp/terraform-plugin-docs/pull/59)
+* cmd/tfplugindocs: Swapped `.Type` and `.Name` resource and data source template fields so they correctly align (https://github.com/hashicorp/terraform-plugin-docs/pull/44).
+* schemamd: Switched attribute name rendering from bold text to code blocks so the Terraform Registry treats them as anchor links (https://github.com/hashicorp/terraform-plugin-docs/pull/59).
 
 # 0.6.0 (March 14, 2022)
 
 NOTES:
 
-* The `github.com/hashicorp/terraform-exec` dependency has been updated to match `terraform-plugin-sdk`, which replaced the removed `tfinstall` package with `github.com/hashicorp/hc-install`. This will resolve Go build errors for projects that import both `terraform-plugin-docs` and `terraform-plugin-sdk`.
+* dependencies: `github.com/hashicorp/terraform-exec` dependency has been updated to match `terraform-plugin-sdk`, which replaced the removed `tfinstall` package with `github.com/hashicorp/hc-install`. This will resolve Go build errors for projects that import both `terraform-plugin-docs` and `terraform-plugin-sdk`.

README.md

@@ -21,6 +21,27 @@ When you run `tfplugindocs` from root directory of the provider the tool takes t
 
 You can see an example of the templates and output in [paultyng/terraform-provider-unifi](https://github.com/paultyng/terraform-provider-unifi) and browse the generated docs in the [Terraform Registry](https://registry.terraform.io/providers/paultyng/unifi/latest/docs).
 
+#### About the `id` attribute
+
+If the provider schema didn't set `id` for the given resource/data-source, the documentation generated
+will place it under the "Read Only" section and provide a simple description.
+
+Otherwise, the provider developer can set an arbitrary description like this:
+
+```golang
+    // ...
+    Schema: map[string]*schema.Schema{
+        // ...
+        "id": {
+            Type:     schema.TypeString,
+            Computed: true,
+            Description: "Unique identifier for this resource",
+		},
+        // ...
+    }
+    // ...
+```
+
 ### Conventional Paths
 
 The generation of missing documentation is based on a number of assumptions / conventional paths:

schemamd/behaviors.go

@@ -16,12 +16,17 @@ func childAttributeIsOptional(att *tfjson.SchemaAttribute) bool {
 	return att.Optional
 }
 
-// childBlockIsOptional returns true for blocks with with min items 0 and any required or optional children.
+// childBlockIsOptional returns true for blocks with with min items 0
+// which are either empty or have any required or optional children.
 func childBlockIsOptional(block *tfjson.SchemaBlockType) bool {
 	if block.MinItems > 0 {
 		return false
 	}
 
+	if len(block.Block.NestedBlocks) == 0 && len(block.Block.Attributes) == 0 {
+		return true
+	}
+
 	for _, childBlock := range block.Block.NestedBlocks {
 		if childBlockIsRequired(childBlock) {
 			return true

schemamd/behaviors_test.go

@@ -324,6 +324,16 @@ func TestChildBlockIsOptional(t *testing.T) {
 			},
 			false,
 		},
+		{
+			"empty block",
+			&tfjson.SchemaBlockType{
+				NestingMode: tfjson.SchemaNestingModeSingle,
+				Block: &tfjson.SchemaBlock{
+					Description: "This is an empty block.",
+				},
+			},
+			true,
+		},
 	} {
 		t.Run(c.name, func(t *testing.T) {
 			actual := childBlockIsOptional(c.block)

schemamd/render.go

@@ -70,10 +70,6 @@ func writeAttribute(w io.Writer, path []string, att *tfjson.SchemaAttribute, gro
 		return nil, err
 	}
 
-	if name == "id" && att.Description == "" {
-		att.Description = "The ID of this resource."
-	}
-
 	if att.AttributeNestedType == nil {
 		err = WriteAttributeDescription(w, att, false)
 	} else {
@@ -225,7 +221,18 @@ nameLoop:
 			}
 		} else if childAtt, ok := block.Attributes[n]; ok {
 			for i, gf := range groupFilters {
-				if gf.filterAttribute(childAtt) {
+				// By default, the attribute `id` is place in the "Read-Only" group
+				// if the provider schema contained no `.Description` for it.
+				//
+				// If a `.Description` is provided instead, the behaviour will be the
+				// same as for every other attribute.
+				if strings.ToLower(n) == "id" && childAtt.Description == "" {
+					if strings.Contains(gf.topLevelTitle, "Read-Only") {
+						childAtt.Description = "The ID of this resource."
+						groups[i] = append(groups[i], n)
+						continue nameLoop
+					}
+				} else if gf.filterAttribute(childAtt) {
 					groups[i] = append(groups[i], n)
 					continue nameLoop
 				}

schemamd/testdata/aws_acm_certificate.md

@@ -6,7 +6,6 @@
 - `certificate_body` (String)
 - `certificate_chain` (String)
 - `domain_name` (String)
-- `id` (String) The ID of this resource.
 - `options` (Block List, Max: 1) (see [below for nested schema](#nestedblock--options))
 - `private_key` (String, Sensitive)
 - `subject_alternative_names` (Set of String)
@@ -18,6 +17,7 @@
 
 - `arn` (String)
 - `domain_validation_options` (Set of Object) (see [below for nested schema](#nestedatt--domain_validation_options))
+- `id` (String) The ID of this resource.
 - `status` (String)
 - `validation_emails` (List of String)
 
@@ -37,4 +37,4 @@ Read-Only:
 - `domain_name` (String)
 - `resource_record_name` (String)
 - `resource_record_type` (String)
-- `resource_record_value` (String)
+- `resource_record_value` (String)

schemamd/testdata/aws_route_table_association.md

@@ -7,5 +7,8 @@
 ### Optional
 
 - `gateway_id` (String)
+- `subnet_id` (String)
+
+### Read-Only
+
 - `id` (String) The ID of this resource.
-- `subnet_id` (String)