Demonstrate generated SDK API reference on GitHub Pages

.github/workflows/reference-docs.yml

@@ -0,0 +1,69 @@
+# API reference docs (pilot).
+#
+# Builds the SignalWire Python SDK API reference (MkDocs Material + mkdocstrings)
+# and publishes it to this repo's OWN GitHub Pages via mike (versioned):
+#   https://signalwire.github.io/signalwire-python/
+#
+# PILOT triggers: workflow_dispatch + push to the pilot branch. This is NOT
+# gated on releases yet.
+#   PRODUCTION (later): switch the trigger to `v*` tags so each release version
+#   is deployed and `latest` is re-aliased. See the commented block below.
+#
+# MANUAL REPO SETTING REQUIRED to go live (one-time, in the GitHub UI):
+#   Settings -> Pages -> Build and deployment -> Source = "Deploy from a branch"
+#   -> Branch = `gh-pages` / `(root)`. mike pushes the built site there.
+name: reference-docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - docs/api-reference-pilot
+
+  # --- PRODUCTION trigger (enable when promoting out of the pilot) ------------
+  # push:
+  #   tags:
+  #     - "v*"
+
+permissions:
+  contents: write   # mike pushes the built site to the gh-pages branch
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # mike needs full history + the gh-pages branch
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install SDK (editable) + doc toolchain
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r reference/requirements.txt
+          pip install -e .
+
+      - name: Configure git for mike
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Generate API pages
+        run: bash reference/gen.sh --no-build
+
+      - name: Resolve version
+        id: ver
+        run: |
+          # Pilot: use the package version. Production: derive from the v* tag,
+          # e.g. VERSION="${GITHUB_REF_NAME#v}".
+          VERSION=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Deploy with mike (versioned) to gh-pages
+        run: |
+          mike deploy --config-file reference/mkdocs.yml --push --update-aliases \
+            "${{ steps.ver.outputs.version }}" latest
+          mike set-default --config-file reference/mkdocs.yml --push latest

.gitignore

@@ -247,3 +247,5 @@ Anaconda3-2024.02-1-Linux-x86_64.sh
 chunks.json
 my_chunks
 *.swsearch
+reference/_docs/
+reference/_site/

reference/README.md

@@ -0,0 +1,96 @@
+# API reference (pilot)
+
+Language-native API reference for the SignalWire Python SDK, generated from
+docstrings with **MkDocs Material + mkdocstrings**, wrapped in the SignalWire
+**Fern navbar**, and versioned with **mike**. Published to this repo's own
+GitHub Pages:
+
+> https://signalwire.github.io/signalwire-python/
+
+This is self-contained under `reference/` and does **not** touch the repo's
+existing top-level `docs/` directory (owned by `doc-audit.yml`).
+
+## Layout
+
+```
+reference/
+  mkdocs.yml          MkDocs Material + mkdocstrings config (docs_dir = _docs)
+  gen.sh              installs the SDK editable, generates the API pages, builds
+  overrides/main.html extends Material's base.html; injects the Fern navbar
+  assets/             Fern tokens/CSS/JS + logo/favicon (committed; no shared host yet)
+  _docs/              GENERATED docs tree (one page per signalwire.<subpackage>)  [gitignored]
+  _site/              local `mkdocs build` output                                  [gitignored]
+  README.md           this file
+```
+
+The `signalwire` package is nested (`signalwire/signalwire/`). mkdocstrings
+resolves imports from the **editable install**, so `gen.sh` runs `pip install -e .`
+first — keep that.
+
+## Build & serve locally
+
+From the repo root, in a virtualenv:
+
+```bash
+pip install -e .
+pip install mkdocs-material "mkdocstrings[python]" mike
+
+# Generate API pages + build the static site into reference/_site
+bash reference/gen.sh
+
+# Live preview (regenerates pages first, then serves with autoreload)
+bash reference/gen.sh --no-build
+mkdocs serve --config-file reference/mkdocs.yml
+```
+
+`use_directory_urls: false`, so every page is a real `.html` file and the site
+works under the `/signalwire-python/` base path.
+
+## Versioning (mike)
+
+`extra.version.provider: mike` in `mkdocs.yml` turns on Material's version
+selector; it reads `versions.json` from the site root at runtime. mike commits
+each deployed version to a local `gh-pages` branch.
+
+```bash
+bash reference/gen.sh --no-build                      # generate pages first
+
+# Deploy a version and (re)point the `latest` alias at it; set it as default.
+mike deploy  --config-file reference/mkdocs.yml --update-aliases 3.0.2 latest
+mike set-default --config-file reference/mkdocs.yml latest
+mike list    --config-file reference/mkdocs.yml       # -> 3.0.2 [latest], 3.0.1
+
+mike serve   --config-file reference/mkdocs.yml       # preview all versions + selector
+```
+
+Add `--push` to push the `gh-pages` branch to the remote (CI does this; do not
+locally).
+
+## CI
+
+`.github/workflows/reference-docs.yml` (plain `actions/setup-python`, no Docker):
+
+- **Pilot triggers:** `workflow_dispatch` + push to `docs/api-reference-pilot`.
+- Installs the SDK editable + `mkdocs-material`, `mkdocstrings[python]`, `mike`,
+  runs `gen.sh --no-build`, then `mike deploy --push --update-aliases <version> latest`.
+- **Production trigger (later):** `v*` tags (commented in the workflow), so each
+  release deploys its version and re-aliases `latest`.
+
+## Manual repo setting required to go live
+
+One-time, in the GitHub UI:
+
+> **Settings → Pages → Build and deployment → Source = "Deploy from a branch" →
+> Branch = `gh-pages` / `(root)`.**
+
+mike pushes the built site to `gh-pages`; Pages then serves it at
+`https://signalwire.github.io/signalwire-python/`.
+
+## Pilot simplifications
+
+- **Language switcher:** cross-site links with Python marked active; other
+  languages point at the POC demo (no per-language hosted site exists yet).
+- **Theme toggle:** drives Material's own light/dark color scheme. No
+  cross-origin `localStorage` theme sync with signalwire.com/docs (different
+  origin — out of scope).
+- Out of scope: llms.txt/markdown emission, Docker, other languages, custom domain.