Generate metadata to allow documentation tooling to include data not included in the Terraform schema.

[breathingdust]

Community Note

• Please vote on this pull request by adding a 👍 reaction to the original pull request comment to help the community and maintainers prioritize this request
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for pull request followers and do not help prioritize the request
• The resources and data sources in this provider are generated from the CloudFormation schema, so they can only support the actions that the underlying schema supports. For this reason submitted bugs should be limited to defects in the generation and runtime code of the provider. Customizing behavior of the resource, or noting a gap in behavior are not valid bugs and should be submitted as enhancements to AWS via the CloudFormation Open Coverage Roadmap.

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.

Tasks

• Update resource level templates to include category
• Include regenerated resources and documentation
• Update and publish forked version of terraform-plugin-docs

[breathingdust]

Adds generic resource/data-source templates to expect and pull in metadata. The existing resource level custom templates will need to be updated as well.

[breathingdust]

After discussion with members of the terraform-devex team, its likely this will be offered natively through framework/plugin-docs in the near future. So rather than adopt a workaround we will wait for the native solution.