docs.yml

name: Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
    paths:
      - "docs/**"

permissions:
  contents: read

jobs:
  build-docs:
    permissions:
      contents: write  # mkdocs gh-deploy pushes the site branch
      pages: write  # GitHub Pages deployment
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      with:
        persist-credentials: false

    - name: Set up Python
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
      with:
        python-version: '3.11'

    - name: Install uv
      uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
      with:
        version: "0.8.4"
        python-version: "3.13"
        enable-cache: false

    - name: Install dependencies
      run: uv sync --group docs

    - name: Build docs
      if: github.event_name == 'pull_request'
      run: uv run -- mkdocs build

    - name: Deploy docs
      if: github.event_name == 'push'
      env:
        GITHUB_TOKEN: ${{ github.token }}
      run: |
        git config user.name "github-actions[bot]"
        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
        git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
        uv run -- mkdocs gh-deploy --force