Switch to Google-style docstrings with Markdown and remove Sphinx/RST generation

[arandito]

Description

This PR updates the generated docstring format to use the Google style with Markdown descriptions for all services (AWS and non-AWS).

This PR also removes the Sphinx-based reStructuredText (RST) documentation generation system introduced in #418. All documentation stubs will now be generated at build time in the awslabs/aws-sdk-python repo. This will prevent static doc stubs from bloating the repo when 400+ services are supported.

Key changes:

• Updates all code generators (Client, Structure, Config, Enum, Union) to generate Google style docstrings with Markdown descriptions using the new MarkdownConverter class
• Adds pandoc CLI tool as a required build dependency to convert Smithy model documentation strings to Markdown
• Updates README with new pandoc dependency
• Removes the AwsRstDocFileGenerator plugin that generates .rst files for Sphinx doc gen
• Remove docs dependencies and Sphinx configuration files from generated clients
• Removes RST-to-Markdown conversion logic

Note

The new docstring format in AWS clients enables us to generate documentation using Material for MkDocs. We will generate MkDocs stubs in awslabs/aws-sdk-python that work with the mkdocstrings tool. This will automatically create documentation from docstrings for all clients.

Testing

• Added unit tests
• Generated aws-sdk-bedrock-runtime client and confirmed all docstrings were updated
  • PR for updated client: Update Bedrock Runtime client to support Material for MkDocs awslabs/aws-sdk-python#24

Important

For local testing, please install pandoc v3.8.2 before running code generator.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[jonathan343]

Thanks Antonio, this is a great start!

This PR can really be broken down into two main components:

1. Formatting docstrings to comply with the requirements of MkDocs
2. Generating the MkDocs specific files and static .md

The first 100% needs to happen at codegen time. However, the more I look at this, the more I feel like doing 2 during codegen time and committing all the static files will really bloat our SDK repo when we're working with 400+ clients. This open PR is adding 4000+ lines for one client. The more scalable approach here might be to do all this generation on the fly when needed like we do with botocore.

I don't see anything in the generated files in https://github.com/awslabs/aws-sdk-python/pull/24/files that would make it difficult to do the approach mentioned above. The generated clients themselves have all the information we need.

[jonathan343]

nit - We should probably start pinning to commit SHAs instead of tags.

I'd recommend updating that here and then we can replace others in a separate PR

[arandito]

Updated!

[jonathan343]

Can we change the default heading_level to 1 so we don't need to specify this case? Then if we need to go lower, we can be explicit

Related Docs: https://mkdocstrings.github.io/python/usage/configuration/headings/#heading_level