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)`.
#
# Versioning (the switcher in the site header reads mike's versions.json):
#   - A final release tag (`v1.2.3`) publishes that release under its version and
#     moves the `latest` alias, which the bare site URL 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 docs are in-progress docs, already covered by the `dev`
#     alias, and publishing them only adds throwaway entries to the version
#     switcher that then have to be deleted by hand.
#   - A push to `main` publishes the in-progress docs under the `dev` alias.
#   - `workflow_dispatch` re-runs the current ref manually.

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.
permissions:
  contents: write

# Serialize deploys so two runs never race on pushing gh-pages.
concurrency:
  group: docs-deploy
  cancel-in-progress: false

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

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          # mike needs full history plus the gh-pages branch it maintains.
          fetch-depth: 0
          # The site logo and other assets (docs/assets/*.png) are LFS-tracked;
          # without this the build embeds LFS pointer files and the logo breaks
          # (Pages serves the ~130-byte pointer instead of the image).
          lfs: true

      - name: Install uv
        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1

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

      - name: Make the gh-pages branch available to mike
        run: git fetch origin gh-pages --depth=1 || true

      - name: Deploy docs
        run: |
          set -euo pipefail
          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
            version="${GITHUB_REF_NAME#v}"
            # The tag filter already keeps pre-releases out, but workflow_dispatch
            # can be pointed at any ref -- so refuse here too rather than relying
            # on 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)"
            uv run --with mkdocs-material --with mike \
              mike deploy --push --update-aliases "${version}" latest
            uv run --with mkdocs-material --with mike \
              mike set-default --push latest
          else
            echo "Publishing development docs (alias: dev)"
            uv run --with mkdocs-material --with mike \
              mike deploy --push --update-aliases dev
          fi