Generate top-level and individual API reference docs for all SDK clients

[arandito]

Description

This PR adds documentation generation for all AWS clients in the aws-sdk-python repo. Users can either generate a single top-level documentation site for all clients or independently for individual clients (see Testing).

Documentation is built using:

• Material for Mkdocs - The Markdown theme to generate the static html files for the documentation site
• mkdocstrings - Auto-documents python modules using Markdown docstrings
• griffe - Parses client packages to generate stub files used by mkdocstrings to generate documentation

Testing

For top-level client docs, execute these commands in the root level of this repo. For individual client documentation, execute these commands in each client's directory.

# Install docs dependencies
make docs-install

# Build static HTML to site/
make docs

# Serve documentation locally to port 8000
make docs-serve

# Clean up artifacts
make docs-clean

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. I've left some initial comments around the configuration of the documentation. I'll get to the generation scripts later tonight, but wanted to comment on what I've seen so far.

Additionally, I have some high-level comment around the top-level clients page:

1. We need to remove the None links and replace them with individual client links.
2. The individual client links throw 404 - Not found.
3. We need to avoid including folders like .ruff_cache

[jonathan343]

More (mostly minor) comments after reviewing the generate_doc_stubs.py script. I know some of the navbar stuff is WIP, so I'll probably wait to review that file

[jonathan343]

Why is this needed?

[arandito]

This was left over from the individual client mkdocs.yml. Each client's docs/ directory has a README.md and a warning gets thrown since it conflicts with index.md:
WARNING - Excluding 'README.md' from the site because it conflicts with 'index.md'.

This isn't required in the top-level configuration since there isn't a README.md inside of the root docs directory. Will remove.

[jonathan343]

Can you explain this SUMMARY.md file and how it's used?

[arandito]

SUMMARY.md is a file generated by the generate_nav.py script. It contains the navigation structure for the site.

For example:

* [Overview](index.md)
* [Contributing](contributing.md)
* [Available Clients](clients/index.md)
    * [Bedrock Runtime](clients/bedrock-runtime/index.md)
    * [Sagemaker Runtime Http2](clients/sagemaker-runtime-http2/index.md)
    * [Transcribe Streaming](clients/transcribe-streaming/index.md)

The mkdocs-literate-nav plugin reads this file and builds the navigation structure as part of the mkdocs build.

This replaces the manual nav configuration inside of mkdocs.yml and allows us to generate navigation dynamically for all clients. This file gets cleaned up as part of make docs-clean so it gets regenerated each build.

[jonathan343]

We may have discussed this before, but why not use something like uv run mkdocs serve --dev-addr 127.0.0.1:$(DOCS_PORT)?

[arandito]

The issue with mkdocs serve is that it forces a rebuild of the entire docs site each time you run it. It doesn't create a site/ directory like mkdocs build. If an engineer accidentally interrupts or exists the server process, running mkdocs serve again forces a rebuild. As the documentation grows, this makes rebuilds longer.

This allows us to always serve the site/ directory if it exists and builds the site if it doesn't.

[jonathan343]

Looks good to merge to the feature branch