docs.yml

name: Documentation

on:
  push:
    branches: [ main, develop, "release/**" ]
  pull_request:
    branches: [ main, develop, "release/**" ]
  workflow_call:
    inputs:
      ref:
        description: Ref (for example a release tag) to check out and document
        required: false
        type: string
        default: ""

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ inputs.ref || github.ref }}
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"
      - name: Check the tag matches the documented version
        run: |
          # Python 3.10 (matched to Read the Docs) predates the TOML parser in
          # the standard library, so read [project] version with pathlib/re.
          version=$(python -c 'import pathlib, re; text = pathlib.Path("pyproject.toml").read_text(encoding="utf-8"); project = re.search(r"(?ms)^\[project\].*?(?=^\[|\Z)", text).group(0); print(re.search(r"(?m)^version\s*=\s*\"([^\"]+)\"", project).group(1))')
          if [[ "$GITHUB_REF_NAME" == v* ]] && [ "$GITHUB_REF_NAME" != "v${version}" ]; then
            echo "Tag $GITHUB_REF_NAME does not match version v${version}"
            exit 1
          fi
      - name: Build the documentation without executing examples
        env:
          SIMIND_GALLERY_BACKEND: ""
        run: |
          python -m sphinx -b html -W --keep-going docs docs/_build/html
      - name: Check the generated gallery indexes are committed
        run: |
          git status --porcelain -- docs/auto_examples
          test -z "$(git status --porcelain -- docs/auto_examples)"
      - name: Upload the built documentation
        uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: docs/_build/html