docs.yaml

name: Docs

# deploy versioned docs to the gh-pages branch on pushes to main and new tags
on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
  workflow_dispatch:

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

permissions:
  contents: write

env:
  TAG: ${{ contains(github.ref, 'tags') && 'latest' || 'dev' }}

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # setuptools-scm needs tags to determine the version

      - uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Configure git
        if: github.event_name == 'push'
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git fetch origin gh-pages --depth=1 || true

      - id: get_version
        if: github.event_name == 'push'
        uses: battila7/get-version-action@v2

      # on push, deploy the docs to the gh-pages branch with mike
      - name: Deploy docs
        if: github.event_name == 'push'
        run: uv run --group docs mike deploy ${{ steps.get_version.outputs.version }} $TAG -u -p

      # on pull request, just check that the docs build cleanly
      - name: Build docs
        if: github.event_name == 'pull_request'
        run: uv run --group docs mkdocs build --strict