Skip to content

Smithy Python Documentation #564

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: develop
Choose a base branch
from
Open

Smithy Python Documentation #564

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3ce5050
Add mkdocs-material dependency and create new site
jonathan343 Sep 24, 2025
2bf5a91
Add smithy logo asset
jonathan343 Sep 24, 2025
865164f
move designs into docs folder
jonathan343 Sep 24, 2025
ba3b0ac
add mkdocstrings-python dependency
jonathan343 Sep 24, 2025
656b518
Document designs and packages
jonathan343 Sep 24, 2025
e80b533
add docs publishing workflow
jonathan343 Sep 24, 2025
7e17663
update workflow branch to main
jonathan343 Sep 24, 2025
4afc8cb
add search plugin
jonathan343 Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: docs
on:
push:
branches:
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Configure Git Credentials
run: |
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

where does this come from?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- uses: actions/setup-python@v6
with:
python-version: 3.12.x
- name: Install uv
uses: astral-sh/setup-uv@v6
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- uses: actions/cache@v4
with:
key: mkdocs-material-${{ env.cache_id }}
path: .cache
restore-keys: |
mkdocs-material-
- run: uv sync --group docs
- run: uv run mkdocs gh-deploy --force
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,6 @@ htmlcov
*.egg-info
dist
.venv

# mkdocs documentation
docs/site
1 change: 1 addition & 0 deletions docs/assets/smithy-anvil.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
0 designs/auth.md → docs/designs/auth.md
View file
Open in desktop
File renamed without changes.
0 designs/documents.md → docs/designs/documents.md
View file
Open in desktop
File renamed without changes.
0 designs/event-streams.md → docs/designs/event-streams.md
View file
Open in desktop
File renamed without changes.
0 designs/exceptions.md → docs/designs/exceptions.md
View file
Open in desktop
File renamed without changes.
0 designs/http-interfaces.md → docs/designs/http-interfaces.md
View file
Open in desktop
File renamed without changes.
0 designs/retries.md → docs/designs/retries.md
View file
Open in desktop
File renamed without changes.
0 designs/serialization.md → docs/designs/serialization.md
View file
Open in desktop
File renamed without changes.
0 designs/shapes.md → docs/designs/shapes.md
View file
Open in desktop
File renamed without changes.
1 change: 1 addition & 0 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
--8<-- "README.md"
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Image

1 change: 1 addition & 0 deletions docs/packages/aws-sdk-signers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
::: aws_sdk_signers
1 change: 1 addition & 0 deletions docs/packages/smithy-aws-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
::: smithy_aws_core
1 change: 1 addition & 0 deletions docs/packages/smithy-aws-event-stream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
::: smithy_aws_event_stream
1 change: 1 addition & 0 deletions docs/packages/smithy-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
::: smithy_core
1 change: 1 addition & 0 deletions docs/packages/smithy-http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
::: smithy_http
1 change: 1 addition & 0 deletions docs/packages/smithy-json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
::: smithy_json
93 changes: 93 additions & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Project Information
site_name: Smithy Python
watch: [README.md]

# Copyright
copyright: Copyright &copy; 2025, Amazon Web Services, Inc

# Repository
repo_name: smithy-lang/smithy-python
repo_url: https://github.com/smithy-lang/smithy-python

# Theme
theme:
name: material
logo: assets/smithy-anvil.svg
Copy link

@arandito arandito Oct 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

palette:
# Palette toggle for automatic mode
- media: "(prefers-color-scheme)"
toggle:
icon: material/brightness-auto
name: Switch to light mode

# Palette toggle for light mode
- media: "(prefers-color-scheme: light)"
scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
primary: black
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Image


# Palette toggle for dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
toggle:
icon: material/brightness-4
name: Switch to system preference
primary: black
features:
- navigation.path
- navigation.top
- navigation.footer
- content.code.copy

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Image

# Plugins
plugins:
- search
- mkdocstrings:
handlers:
python:
paths: [packages/*/src]
options:
show_submodules: true
show_symbol_type_heading: true
show_symbol_type_toc: true

# Navigation
nav:
- index.md
- Packages:
- smithy-core: packages/smithy-core.md
- smithy-http: packages/smithy-http.md
- smithy-json: packages/smithy-json.md
- smithy-aws-core: packages/smithy-aws-core.md
- smithy-aws-event-stream: packages/smithy-aws-event-stream.md
- aws-sdk-signers: packages/aws-sdk-signers.md
- Designs:
- Auth: designs/auth.md
- Documents: designs/documents.md
- "Event Streams": designs/event-streams.md
- Exceptions: designs/exceptions.md
- "HTTP Interfaces": designs/http-interfaces.md
- Retries: designs/retries.md
- Serialization: designs/serialization.md
- Shapes: designs/shapes.md

# Extensions
markdown_extensions:
- admonition
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- toc:
permalink: true

# Extras
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/smithy-lang/smithy-python
4 changes: 4 additions & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@ typing = [
changelog = [
"jinja2>=3.1.6"
]
docs = [
"mkdocs-material~=9.6.20",
"mkdocstrings-python~=1.18.2"
]

[tool.uv]
required-version = ">=0.7.2"
Expand Down
Loading
Loading