docs.yml

name: Docs

# Deploy API documentation to GitHub Pages via GitHub Actions.
#
# Versioning strategy
# ───────────────────
# • Push to master  → docs deployed under  /main/
# • Push of v* tag  → docs deployed under  /{tag}/   (e.g. /v0.1.0/)
#                     AND /latest/  is updated to point at the new tag
# • Older versions are never removed — the gh-pages branch acts as a
#   persistent version store.  The deploy job checks it out, merges the
#   new version in, then uploads the whole tree with upload-pages-artifact
#   so GitHub Pages (Actions mode) serves it.
# • Root index.html and versions.json are regenerated on every deploy.
# • Each page carries a JS version-switcher that reads versions.json.
#
# GitHub Pages setup (one-time, in repo Settings → Pages):
#   Source → GitHub Actions   (NOT "Deploy from a branch")

on:
  push:
    branches: [master, main]
    tags: ["v*.*.*"]
  workflow_dispatch:
    inputs:
      version_override:
        description: "Version label (leave blank to derive from branch/tag)"
        required: false
        default: ""

concurrency:
  group: docs-deploy
  cancel-in-progress: false   # never cancel a running deploy mid-flight

# ── Job 1: Build ──────────────────────────────────────────────────────────────
#
# Generates pdoc HTML for the current commit and uploads it as a workflow
# artifact.  No write permissions needed here.

jobs:
  build:
    name: Build Docs
    runs-on: ubuntu-latest

    outputs:
      version-label: ${{ steps.version.outputs.label }}
      is-release:    ${{ steps.version.outputs.is_release }}

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install pdoc and project
        run: |
          pip install pdoc
          pip install -e ".[dev,django,websockets]"

      - name: Determine version label
        id: version
        run: |
          if [ -n "${{ github.event.inputs.version_override }}" ]; then
            LABEL="${{ github.event.inputs.version_override }}"
            IS_RELEASE="false"
          elif [[ "$GITHUB_REF" == refs/tags/* ]]; then
            LABEL="${GITHUB_REF#refs/tags/}"
            IS_RELEASE="true"
          else
            LABEL="main"
            IS_RELEASE="false"
          fi
          echo "label=${LABEL}"       >> "$GITHUB_OUTPUT"
          echo "is_release=${IS_RELEASE}" >> "$GITHUB_OUTPUT"
          echo "Building docs for version: ${LABEL}"

      - name: Generate docs
        run: python docs/make.py --output-dir generated

      # Upload only the new version's output — the deploy job merges it
      # with the existing version store.
      - uses: actions/upload-artifact@v4
        with:
          name: docs-${{ steps.version.outputs.label }}
          path: generated/
          retention-days: 7

# ── Job 2: Deploy ─────────────────────────────────────────────────────────────
#
# 1. Checks out the gh-pages branch (version store).
# 2. Downloads the artifact from the build job.
# 3. Copies the new version into the store.
# 4. Regenerates versions.json and root index.html.
# 5. Uploads the full store with upload-pages-artifact.
# 6. Deploys via actions/deploy-pages (OIDC — no PAT needed).
# 7. Pushes the updated store back to gh-pages so future runs see all versions.

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest

    permissions:
      contents: write   # push updated version store to gh-pages branch
      pages: write      # upload Pages artifact
      id-token: write   # OIDC token for Pages deployment

    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}

    steps:
      # ── Checkout source (for docs/ scripts) ───────────────────────────
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # ── Prepare the gh-pages version-store worktree ───────────────────
      - name: Prepare gh-pages version store
        run: |
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          git fetch origin gh-pages:gh-pages 2>/dev/null || true

          if git show-ref --quiet refs/heads/gh-pages; then
            git worktree add gh-pages-dir gh-pages
          else
            # First run: create the orphan branch
            git worktree add --orphan -b gh-pages gh-pages-dir
            cd gh-pages-dir
            git commit --allow-empty -m "chore: initialise gh-pages version store"
            cd ..
          fi

      # ── Merge new version into the store ──────────────────────────────
      - uses: actions/download-artifact@v4
        with:
          name: docs-${{ needs.build.outputs.version-label }}
          path: downloaded-docs/

      - name: Copy new version into store
        run: |
          LABEL="${{ needs.build.outputs.version-label }}"
          DEST="gh-pages-dir/${LABEL}"
          rm -rf "${DEST}"
          mkdir -p "${DEST}"
          cp -r downloaded-docs/. "${DEST}/"

      - name: Update latest symlink (releases only)
        if: needs.build.outputs.is-release == 'true'
        run: |
          cd gh-pages-dir
          rm -rf latest
          ln -sfn "${{ needs.build.outputs.version-label }}" latest

      - name: Regenerate versions.json and root index
        run: |
          python docs/update_gh_pages.py --pages-dir gh-pages-dir

      # ── Upload full store as the Pages artifact ────────────────────────
      - uses: actions/configure-pages@v5

      - uses: actions/upload-pages-artifact@v3
        with:
          path: gh-pages-dir/

      # ── Deploy to GitHub Pages (OIDC) ──────────────────────────────────
      - name: Deploy
        id: deploy
        uses: actions/deploy-pages@v4

      # ── Persist the updated version store ─────────────────────────────
      # Push the merged gh-pages branch back so the next run can check it
      # out and see all previously deployed versions.
      - name: Persist version store
        run: |
          LABEL="${{ needs.build.outputs.version-label }}"
          COMMIT_SHA="${GITHUB_SHA:0:7}"
          cd gh-pages-dir
          git add -A
          if git diff --cached --quiet; then
            echo "Version store unchanged — nothing to push."
          else
            git commit -m "docs: add ${LABEL} (${COMMIT_SHA})"
            git push origin gh-pages
          fi