docs.yml

name: docs.yml

permissions:
  contents: read

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
  UV_VERSION: "0.11.21"
  UV_PROJECT_ENVIRONMENT: venv

concurrency:
  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.ref }}
  cancel-in-progress: true

on:
  # Only run on pushes to master for documentation-related changes
  # This prevents running on every commit, only when docs actually change
  push:
    branches:
      - master
    paths:
      - 'docs/**'
      - '.readthedocs.yaml'
  # Manual trigger for immediate updates (e.g., after releases)
  workflow_dispatch: {}

jobs:
  build-and-deploy:
    name: Build and deploy documentation
    defaults:
      run:
        shell: bash
    runs-on: ubuntu-latest
    if: github.event_name == 'workflow_dispatch' || github.ref == 'refs/heads/master'
    permissions:
      contents: read
      pages: write  # Required for actions/deploy-pages to deploy to GitHub Pages
      id-token: write  # Required for OIDC token for GitHub Pages deployment
    environment:
      name: github-pages

    steps:
      - name: Check out GitHub repository
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 1
          ref: ${{ (github.event_name == 'workflow_dispatch' && github.ref) || github.sha }}
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        id: setup_python
        with:
          python-version-file: '.python-version'

      - name: Set up uv
        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
        with:
          version: ${{ env.UV_VERSION }}

      - name: Sync dependencies (locked)
        run: uv sync --locked --extra docs

      - name: Build documentation
        run: uv run --directory docs make builddocs

      - name: Check for documentation warnings
        run: |
          uv run --directory docs make strict || {
            echo "Documentation build failed with warnings/errors:"
            echo "This indicates potential issues that should be fixed."
            exit 1
          }

      - name: Setup Pages
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

      - name: Upload to GitHub Pages
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: docs/build/html

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0