docs.yml

# Docs — documentation build and deploy
#
# Scope:    Runs on push to main (deploys dev alias) and version tags (deploys stable).
#           Uses the pixi docs environment for reproducible builds.
# Jobs:     deploy (mike + mkdocs)
name: Docs

on:
  push:
    branches:
      - main
    tags:
      - "v*"

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions: {}

jobs:
  deploy:
    name: Deploy Docs
    runs-on: ubuntu-latest

    permissions:
      contents: write # mike pushes the built docs to the gh-pages branch

    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: 🔧 Set up pixi
        uses: prefix-dev/setup-pixi@5185adfbffb4bd703da3010310260805d89ebb11 # v0.9.6
        with:
          environments: docs

      - name: Deploy docs
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # Checkout uses persist-credentials: false; authenticate the push that
          # mike performs to the gh-pages branch via the gh credential helper.
          gh auth setup-git
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"

          # A stable release is a tag starting with "v" and containing only
          # numbers and dots; everything else from main publishes the dev docs.
          VERSION="${GITHUB_REF_NAME}"
          echo "Deploying version ${VERSION}"
          if [[ "${GITHUB_REF_TYPE}" == "tag" && "${VERSION}" =~ ^v[0-9.]+$ ]]; then
            pixi run -e docs mike deploy --push --update-aliases "${VERSION}" stable
            pixi run -e docs mike set-default --push stable
            echo "Deployed stable version ${VERSION} (stable)"

          elif [[ "${GITHUB_REF_NAME}" == "main" ]]; then
            pixi run -e docs mike deploy --push dev
            pixi run -e docs mike set-default --push dev
            echo "Deployed development version (dev) from main"
          fi