Publish API docs to GitHub pages (#172)

Signed-off-by: Anuraag Agrawal <anuraaga@gmail.com>

Author: anuraaga

.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/img/favicon.png

@@ -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).

docs/index.md

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

justfile

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

pyproject.toml

@@ -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/_response_metadata.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/__init__.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.
         """