Find alternative way to create AWS CloudFormation/SAM doc index

[pitkley]

Following the announcement of "Retiring the AWS Documentation on GitHub", the aws-cloudformation-user-guide was finally removed of its content last week (2023-12-08). The aws-sam-developer-guide hasn't had content since June 2023.

We now need an alternative way of creating an index for the CFN docs. The AWS CloudFormation resource specification is a potential candidate for programmatically identifying resources that exist. The main challenge is going to be generating valid URLs out of it -- from what I recall, the naming scheme of the URLs for the individual pages in the CFN docs was not consistent. It also does not solve the problem of getting a summary into ASE, but we could worst-case just skip out on that.

I don't yet know if something similar for SAM exists.

• AWS CloudFormation resources
  feat: generate CFN index from CloudFormation specs #201
• AWS CloudFormation intrinsic functions
  feat: generate CFN index from CloudFormation specs #201
• AWS SAM resources
  Add last state of documentation-based SAM items #209

[pitkley]

The CFN resource specification is likely the way to go, since it does contain links to docs. We would likely lose the summary though.

We do need something else to get the intrinsic-function docs, though.

[pitkley]

#201 gets the CFN-related content, including data on intrinsic functions, from the CFN-specs stored in the aws-cloudformation/cfn-lint repository. #209 "hardcodes" the last SAM status from before the documentation shutdown.

Issues currently remaining:

• No summaries for any CloudFormation resources
• No summaries for any CloudFormation intrinsics
• SAM resources are now static and won't update if they change

I did a little further digging and stumbled upon these additional structured sources:

• https://github.com/cdklabs/awscdk-service-spec/tree/main/sources/CloudFormationDocumentation: contains an automatically updated JSON file that contains all CFN resources with at least a summary documentation, in a structured form. It does not contain any details on intrinsics, and it also does not contain links to the docs. This would make this strictly additive to using the cfn-lint-source we currently use.
• https://github.com/aws/serverless-application-model/blob/develop/schema_source/sam.schema.json: contains some data on SAM resources, although not in the format we probably need.
• https://github.com/aws/serverless-application-model/blob/develop/samtranslator/validator/sam_schema/schema.json: also contains some data on SAM resources, but again: probably not in the format we need.