[Proposal] Prototype of metadata generation to improve docs #2024
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Community Note
The AWSCC provider relies on terraform-plugin-docs to generate Terraform Registry documentation from resource/data source schema. This limits the information we are able to use during documentation configuration to what is included in the resource schema. In some cases this isn't enough to do what we would like with the documentation. For example, currently we are not able to specify a service category in the Cloud Control documentation which leads to poor navigability of the resources within a service. If we were able to include additional metadata in the schema, we would have more flexibility. Unfortunately this is not something that is likely to be included in the short term in terraform-plugin-docs (hashicorp/terraform-plugin-docs#156).
As a potential workaround, this PR modifies the resource generation code to also emit a metadata file which can include whatever information about a resource you would like to include. A modified version of terraform-plugin-docs (currently fully working in an unpublished fork f-metadata-function) would look for these metadata files during documentation generation, and allow the data to be used in the templates. This PR includes the CloudFormation name for a resource, as well as the service name which can be used to specify a subcategory in the template frontmatter.
Currently only supports resources, will need to extend to data-sources if general shape of the solution accepted.