From 0a567c5969f0e854268b6125c6011aeaf6396252 Mon Sep 17 00:00:00 2001 From: Oleg Andriyanov Date: Thu, 2 Dec 2021 19:36:37 +0300 Subject: [PATCH 1/5] Treat empty blocks with MinItems == 0 as optional --- schemamd/behaviors.go | 7 ++++++- schemamd/behaviors_test.go | 10 ++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/schemamd/behaviors.go b/schemamd/behaviors.go index 88fd7b01..954225ea 100644 --- a/schemamd/behaviors.go +++ b/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 diff --git a/schemamd/behaviors_test.go b/schemamd/behaviors_test.go index d9142950..3bdb087f 100644 --- a/schemamd/behaviors_test.go +++ b/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) From e78907e1b92473e20698fa6d3098df4266e21423 Mon Sep 17 00:00:00 2001 From: Ivan De Marino Date: Tue, 3 May 2022 10:14:21 +0100 Subject: [PATCH 2/5] Adding CHANGELOG entry for the work done in https://github.com/hashicorp/terraform-plugin-docs/pull/99 and cherry-picked here --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 69cbeb08..52909c3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,10 @@ 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: Allow documentation generation for schemas containing empty nested attributes or empty nested blocks ([#99](https://github.com/hashicorp/terraform-plugin-docs/pull/99), [#XX](https://github.com/hashicorp/terraform-plugin-docs/pull/XX)) # 0.7.0 (March 15, 2022) From f146f8469a46cc64d9d3ffcf9da96771252c45b0 Mon Sep 17 00:00:00 2001 From: Ivan De Marino Date: Tue, 3 May 2022 16:28:26 +0100 Subject: [PATCH 3/5] Place `id` attribute in documentation "Read-Only" group by default This still allows arbitrary definition of `id` where a tailor-made `.Description` can be provided: it's just the default that is changing to something more sensible. Also, updated README to guide developers. Co-authored-by: Nicholas Muesch Co-authored-by: Oliver Ford --- .go-version | 2 +- CHANGELOG.md | 13 +++++++------ README.md | 21 +++++++++++++++++++++ schemamd/render.go | 17 ++++++++++++----- 4 files changed, 41 insertions(+), 12 deletions(-) diff --git a/.go-version b/.go-version index a23a1564..19fb7bd9 100644 --- a/.go-version +++ b/.go-version @@ -1 +1 @@ -1.17.8 +1.17.9 diff --git a/CHANGELOG.md b/CHANGELOG.md index 52909c3a..e8b59446 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,22 +6,23 @@ ENHANCEMENTS: BUG FIXES: -* cmd/tflugindocs: Allow documentation generation for schemas containing empty nested attributes or empty nested blocks ([#99](https://github.com/hashicorp/terraform-plugin-docs/pull/99), [#XX](https://github.com/hashicorp/terraform-plugin-docs/pull/XX)) +* cmd/tflugindocs: Support for schemas containing empty nested attributes or empty nested blocks ([#99](https://github.com/hashicorp/terraform-plugin-docs/pull/99), [#XX](https://github.com/hashicorp/terraform-plugin-docs/pull/XX)). +* 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), [#XX](https://github.com/hashicorp/terraform-plugin-docs/pull/XX)). # 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`. diff --git a/README.md b/README.md index a3530b14..93300f50 100644 --- a/README.md +++ b/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: diff --git a/schemamd/render.go b/schemamd/render.go index 68568c6d..9415aa08 100644 --- a/schemamd/render.go +++ b/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 } From d8e70fbaed2d4f6b67f9a896d9a0890230d26676 Mon Sep 17 00:00:00 2001 From: Ivan De Marino Date: Tue, 3 May 2022 16:30:59 +0100 Subject: [PATCH 4/5] Add correct link to PR that implements the bugfix --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e8b59446..871c0e00 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,8 +6,8 @@ ENHANCEMENTS: 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), [#XX](https://github.com/hashicorp/terraform-plugin-docs/pull/XX)). -* 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), [#XX](https://github.com/hashicorp/terraform-plugin-docs/pull/XX)). +* 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) From 08f8848029176901b34ad23e501a2ee6f905a97f Mon Sep 17 00:00:00 2001 From: Ivan De Marino Date: Tue, 3 May 2022 16:36:27 +0100 Subject: [PATCH 5/5] Fixing test fixtures --- schemamd/testdata/aws_acm_certificate.md | 4 ++-- schemamd/testdata/aws_route_table_association.md | 5 ++++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/schemamd/testdata/aws_acm_certificate.md b/schemamd/testdata/aws_acm_certificate.md index 82f37392..7ead0c69 100644 --- a/schemamd/testdata/aws_acm_certificate.md +++ b/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) \ No newline at end of file +- `resource_record_value` (String) diff --git a/schemamd/testdata/aws_route_table_association.md b/schemamd/testdata/aws_route_table_association.md index c332d6f1..279d6c19 100644 --- a/schemamd/testdata/aws_route_table_association.md +++ b/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) \ No newline at end of file