Publish API docs to GitHub pages

.github/workflows/docs.yaml

@@ -0,0 +1,49 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "src/**"
+      - zensical.toml
+      - ".github/workflows/docs.yaml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "src/**"
+      - zensical.toml
+      - ".github/workflows/docs.yaml"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    environment:
+      name: ${{ github.event_name != 'pull_request' && 'github-pages' || null }}
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+
+      - uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+
+      - run: uv run --group docs --no-dev zensical build --clean
+
+      - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        if: github.event_name != 'pull_request'
+        with:
+          path: site
+
+      - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
+        if: github.event_name != 'pull_request'
+        id: deployment

docs/api.md

@@ -0,0 +1,17 @@
+# API Reference
+
+::: connectrpc.client
+::: connectrpc.server
+
+::: connectrpc.code
+::: connectrpc.errors
+
+::: connectrpc.method
+::: connectrpc.request
+
+::: connectrpc.interceptor
+
+::: connectrpc.compression
+::: connectrpc.compression.brotli
+::: connectrpc.compression.gzip
+::: connectrpc.compression.zstd

docs/index.md

@@ -0,0 +1,6 @@
+# ConnectRPC
+
+Welcome to ConnectRPC!
+
+View our [main documentation](https://connectrpc.com/docs/python/getting-started)
+or the generated [API reference](./api.md).

justfile

@@ -65,3 +65,6 @@ checkgenerate: generate
 bump semver:
     uv version --bump={{ semver }}
     uv version --bump={{ semver }} --directory protoc-gen-connect-python
+
+serve-docs:
+    uv run --group docs zensical serve

pyproject.toml

@@ -63,6 +63,8 @@ dev = [
     "pytest-timeout",
 ]
 
+docs = ["zensical==0.0.27", "mkdocstrings-python==2.0.3"]
+
 [build-system]
 requires = ["uv_build>=0.10.0,<0.11.0"]
 build-backend = "uv_build"

src/connectrpc/_response_metadata.py

@@ -64,12 +64,13 @@ class ResponseMetadata:
     for the invocation made within the context.
 
     Example:
-
+        ```python
         with ResponseMetadata() as resp_data:
             resp = client.MakeHat(Size(inches=10))
             do_something_with_response_payload(resp)
             check_response_headers(resp_data.headers())
             check_response_trailers(resp_data.trailers())
+        ```
     """
 
     _headers: Headers | None = None

src/connectrpc/compression/__init__.py

@@ -13,8 +13,8 @@ class Compression(Protocol):
     used by specifying implementations of this protocol. We provide standard
     implementations for
 
-    - br (connectrpc.compression.brotli.BrotliCompression) - requires the brotli dependency
-    - zstd (connectrpc.compression.zstd.ZstdCompression) - requires the zstandard dependency
+    - br (connectrpc.compression.brotli.BrotliCompression) - requires the `brotli` dependency
+    - zstd (connectrpc.compression.zstd.ZstdCompression) - requires the `zstandard` dependency
     """
 
     def name(self) -> str:

src/connectrpc/compression/gzip.py

@@ -10,6 +10,7 @@ class GzipCompression(Compression):
 
     def __init__(self, level: int = 6) -> None:
         """Creates a new GzipCompression.
+
         Args:
             level: Compression level to use.
         """

zensical.toml

@@ -0,0 +1,44 @@
+[project]
+site_name = "connectrpc"
+site_url = "https://connectrpc.github.io/connect-python/"
+site_description = "The Python implementation of Connect: Protobuf RPC that works"
+site_author = "Connect Authors"
+copyright = "© The Connect Authors"
+repo_url = "https://github.com/connectrpc/connect-python"
+nav = ["api.md"]
+
+[project.theme]
+favicon = "img/favicon.png"
+
+[project.theme.icon]
+repo = "fontawesome/brands/github"
+
+[project.markdown_extensions.attr_list]
+[project.markdown_extensions.md_in_html]
+[project.markdown_extensions.pymdownx.blocks.caption]
+[project.markdown_extensions.pymdownx.highlight]
+anchor_linenums = true
+line_spans = "__span"
+pygments_lang_class = true
+[project.markdown_extensions.pymdownx.inlinehilite]
+[project.markdown_extensions.pymdownx.snippets]
+[project.markdown_extensions.pymdownx.superfences]
+[project.markdown_extensions.pymdownx.tabbed]
+alternate_style = true
+
+[project.plugins.mkdocstrings.handlers.python]
+inventories = ["https://docs.python.org/3/objects.inv"]
+paths = ["."]
+
+[project.plugins.mkdocstrings.handlers.python.options]
+docstring_options = { ignore_init_summary = true }
+docstring_style = "google"
+inherited_members = false
+members_order = "source"
+merge_init_into_class = true
+relative_crossrefs = true
+scoped_crossrefs = true
+signature_crossrefs = true
+show_root_heading = true
+show_signature = false
+show_source = false