docs.yml

# Docs: build the versioned documentation site with mike (Material for MkDocs)
# and publish it to the `gh-pages` branch, which GitHub Pages serves.
#
# One-time repository setup (Settings -> Pages):
#   Source: "Deploy from a branch" -> branch `gh-pages`, folder `/ (root)`.
#
# This replaced an `upload-pages-artifact` + `deploy-pages` pair, and with it the
# "Source: GitHub Actions" setting. mike needs a branch it owns: it keeps one
# built site per version there and maintains the `versions.json` the header
# switcher reads, neither of which survives a model where every deploy replaces
# the whole artifact.
#
# Versioning:
#   - A final release tag (`v1.2.3`) publishes that release under its bare
#     version number and moves the `latest` alias, which the site root redirects
#     to.
#   - A PRE-RELEASE tag (`v1.2.3-rc.1`, or any tag with a `-` qualifier)
#     publishes nothing. Release candidates are cut from `develop` to exercise
#     the release pipeline; their documentation is in-progress documentation,
#     already covered by `dev`, and publishing it only adds throwaway entries to
#     the switcher that someone then has to delete by hand.
#   - A push to `main` publishes the in-progress documentation under `dev`.
#   - `workflow_dispatch` re-runs whatever ref it is pointed at.
#
# The strict build also runs in `ci.yml` on every pull request, so documentation
# breakage is caught before it reaches main rather than at the deploy.

name: Docs

on:
  push:
    branches:
      - main
    tags:
      # Final releases only: the negative pattern excludes any pre-release tag
      # (a `-` qualifier), so an RC never starts this workflow at all.
      - "v*"
      - "!v*-*"
  workflow_dispatch:

# mike pushes commits to the gh-pages branch. No `pages: write` or
# `id-token: write` any more -- nothing here talks to the Pages deployment API.
permissions:
  contents: write

# Serialize deploys so two runs never race on pushing gh-pages. Not cancelled
# in progress: an interrupted mike run can leave the branch with a site
# committed and its `versions.json` not yet updated.
concurrency:
  group: docs-deploy
  cancel-in-progress: false

jobs:
  deploy:
    name: Build and deploy versioned docs
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          # mike reads and rewrites the gh-pages branch, so it needs history
          # rather than the default shallow clone of one ref.
          fetch-depth: 0
          # The icons are tracked through git-lfs, and the build hook copies them
          # into the docs tree. Without this the published site would carry a
          # pointer file where the logo goes -- which renders as a broken image
          # rather than failing the build.
          lfs: true

      # Pinned to an exact release, unlike every other action here. astral-sh
      # publishes `v9.0.0` but stopped publishing the sliding major tag after
      # `v7`, so `@v9` resolves to nothing and the job fails before it runs.
      - name: Install uv
        uses: astral-sh/setup-uv@v9.0.0

      - name: Configure git identity for mike
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

      # `|| true`: the branch does not exist before the first deploy, and mike
      # creates it. A missing branch is not a failure here.
      - name: Make the gh-pages branch available to mike
        run: git fetch origin gh-pages --depth=1 || true

      - name: Deploy
        run: |
          set -euo pipefail
          mike() {
            uv run --with-requirements docs/requirements.txt mike "$@"
          }

          if [ "${GITHUB_REF_TYPE}" != "tag" ]; then
            echo "Publishing development docs (alias: dev)"
            mike deploy --push --update-aliases dev
            exit 0
          fi

          version="${GITHUB_REF_NAME#v}"
          # The tag filter above already keeps pre-releases out, but
          # workflow_dispatch can be pointed at any ref -- so refuse here too
          # rather than trusting the trigger alone.
          case "${version}" in
            *-*)
              echo "${version} is a pre-release; skipping docs publication."
              exit 0
              ;;
          esac

          echo "Publishing release docs ${version} (alias: latest)"
          mike deploy --push --update-aliases "${version}" latest
          # Idempotent, and cheap enough to repeat: it writes the redirect at the
          # site root. Doing it on every release means a gh-pages branch that was
          # ever rebuilt by hand does not need this done separately.
          mike set-default --push latest