Smithy Python Documentation

[jonathan343]

Summary

This PR establishes a complete documentation infrastructure for the Smithy Python project using Material for MkDocs. The changes create a modern, automated documentation site that includes both API documentation and design documents.

Preview

Tip

See live docs here: https://jonathan343.github.io/smithy-python/

Key Changes

Content

• Index Page: Configured to include README.md content as the main landing page
• Package API References: Integrated mkdocstrings-python plugin to auto-generate API docs from package source code for the following core smithy packages:
  • smithy-core, smithy-http, smithy-json, smithy-aws-core, smithy-aws-event-stream, aws-sdk-signers
• Design Documents: Moved existing design docs from root /designs folder into /docs/designs for better organization

Automated Publishing

• GitHub Actions Workflow: Added automated docs deployment to GitHub Pages
• Trigger: Publishes documentation on every push to smithy-python-docs branch
• Caching: Optimized build times with weekly cache rotation for MkDocs Material
• Dependencies: Uses uv for fast, reliable Python package management

Extras

• Theme Features: Navigation paths, top navigation, footer, and code copy functionality
• Markdown Extensions: Added support for admonitions, syntax highlighting, code snippets, and table of contents
• Social Links: Integrated GitHub repository links in the documentation footer

Testing

The documentation can be previewed locally using:

uv sync --group docs
uv run mkdocs serve

Next Steps

After this PR is merged to main (in the next Smithy Python release), the documentation site will be automatically published and accessible via GitHub Pages. Future package documentation will be automatically generated from docstrings in the source code.

---

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

[JordonPhillips]

where does this come from?

[jonathan343]

For publishing I copied this over from the Publishing your site docs from Material for MkDocs. It uses outdated action tags so I updated those.

As for the git config commands specifically, I believe that's what's recommend by actions/checkout.