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.

[arandito]

Thanks Jonathan! This looks great!

Just some general questions:

1. Do we plan on supporting versioned docs?
2. Can we include a release notes/changelog page in the future? This can helpful for developers looking for changes in specific versions.
3. Are we going to enforce the Google docstring style or have we considered any other formats?

Lastly, generating the package documentation into one page is not a great UI experience for large packages such as smithy-core. Can we reorganize the package documentation using a nested structure for sub pages? Should we be intentional in what we choose to document for users?

[arandito]

Can we remove the "Home" that gets rendered at the top of the page and replace it with a "Smithy Python" title.

We'll need to explicitly ignore the first line of the README.md to avoid the duplication of the title.

Something like this:

# Smithy Python

<!-- Includes everything from README except the first heading -->
--8<-- "README.md:3:"

We'll also need to change this in mkdocs.yml to remove the duplication in the sidebar:

# Navigation
nav:
  - Getting Started: index.md  # Add Getting Started to sidebar

The change renders:

[arandito]

We should remove the dropdown menu for "Packages" and "Designs" and convert them to sections displaying all the sublinks directly. This removes the extra click needed to access package references. I don't think we expect these sections to grow by that much either.

Suggested change

	- navigation.sections

This renders:

[arandito]

nit: Switching the header to white makes light mode more uniform. Don't feel too strong about this though!

[arandito]

We should also add the smithy logo as a favicon.

Suggested change

	logo: assets/smithy-anvil.svg
	logo: assets/smithy-anvil.svg
	favicon: assets/smithy-anvil.svg