Smithy Python Documentation

.github/workflows/docs.yml

@@ -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
+      - 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

.gitignore

@@ -34,3 +34,6 @@ htmlcov
 *.egg-info
 dist
 .venv
+
+# mkdocs documentation
+docs/site

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/packages/aws-sdk-signers.md

@@ -0,0 +1 @@
+::: aws_sdk_signers

docs/packages/smithy-aws-core.md

@@ -0,0 +1 @@
+::: smithy_aws_core

docs/packages/smithy-aws-event-stream.md

@@ -0,0 +1 @@
+::: smithy_aws_event_stream

docs/packages/smithy-core.md

@@ -0,0 +1 @@
+::: smithy_core

docs/packages/smithy-http.md

@@ -0,0 +1 @@
+::: smithy_http

docs/packages/smithy-json.md

@@ -0,0 +1 @@
+::: smithy_json

mkdocs.yml

@@ -0,0 +1,93 @@
+# Project Information
+site_name: Smithy Python
+watch: [README.md]
+
+# Copyright
+copyright: Copyright © 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
+  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
+
+    # 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
+
+# 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

pyproject.toml

@@ -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"