feat(docs): Publish pdoc-generated API reference to GitHub Pages (#651)

Author: gjtorikian

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Publish API Docs
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: false
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version-file: pyproject.toml
+      - run: ./scripts/docs.sh
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - name: Archive site
+        run: |
+          tar \
+            --dereference --hard-dereference \
+            --directory docs/_site \
+            -cvf "$RUNNER_TEMP/artifact.tar" \
+            --exclude=.git \
+            --exclude=.github \
+            .
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: github-pages
+          path: ${{ runner.temp }}/artifact.tar
+          retention-days: 1
+          if-no-files-found: error
+  deploy:
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+        id: deployment

.gitignore

@@ -72,6 +72,9 @@ instance/
 # Sphinx documentation
 docs/_build/
 
+# pdoc documentation
+docs/_site/
+
 # PyBuilder
 target/
 

pyproject.toml

@@ -36,6 +36,7 @@ test = [
 lint = ["ruff~=0.15"]
 type_check = ["pyright~=1.1"]
 nox = ["nox~=2026.2", "nox-uv~=0.7"]
+docs = ["pdoc>=14", "pydoc-markdown>=4"]
 
 
 [tool.pytest.ini_options]

scripts/docs-serve.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")/.."
+if [ "${1:-}" = "--live" ]; then
+  exec uv run --group docs pdoc workos -p 4000 --docformat google
+fi
+if [ ! -d docs/_site ]; then
+  ./scripts/docs.sh
+fi
+exec python3 -m http.server 4000 --directory docs/_site

scripts/docs.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")/.."
+rm -rf docs/_site
+uv run --group docs pdoc workos -o docs/_site --docformat google
+if [ ! -f docs/_site/index.html ] && [ -f docs/_site/workos.html ]; then
+  cp docs/_site/workos.html docs/_site/index.html
+fi
+uv run --group docs pydoc-markdown -p workos --render-toc > docs/_site/workos.md
+cp docs/_site/workos.md docs/_site/index.md
+
+version=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+cat > docs/_site/llms.txt <<EOF
+# WorkOS Python SDK
+
+> Official Python client for the WorkOS API. Provides synchronous and
+> asynchronous clients for SSO, Directory Sync, User Management, Audit Logs,
+> Organizations, Events, Webhooks, and more. Current version: ${version}.
+
+The full API reference is available as markdown at [index.md](index.md).
+HTML documentation is at [index.html](index.html).
+
+## Docs
+
+- [Full API reference (markdown)](index.md): every public class and function in the \`workos\` package
+- [HTML API reference](index.html): browsable pdoc-rendered site
+- [WorkOS product documentation](https://workos.com/docs): guides, concepts, and REST API reference
+- [Python SDK guide](https://workos.com/docs/sdks/python): installation and getting started
+
+## Source
+
+- [GitHub repository](https://github.com/workos/workos-python)
+- [PyPI package](https://pypi.org/project/workos/)
+EOF