docs.yml

name: Docs

on:
  push:
    branches: [main, doc-rst, github.io-docs-rst]
  workflow_dispatch: {}

# OIDC permissions: id-token:write lets GitHub exchange an OIDC token for
# Pages deployment auth; pages:write allows uploading to the Pages service.
permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:

  build:
    runs-on: ubuntu-24.04
    steps:

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

      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: '3.12'

      - name: Install Sphinx + sphinx_rtd_theme
        run: |
          python -m pip install --upgrade pip
          pip install -r docs/requirements.txt

      - name: Build documentation (strict)
        run: sphinx-build -W --keep-going docs/ docs/_build/html

      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: 'docs/_build/html'

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-24.04
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:

      # NOTE: the `enablement` input is intentionally omitted (defaults to
      # false). Setting it true triggers a GET /pages -> POST /pages bootstrap
      # path that intermittently fails: the GET hits "Bad credentials" and the
      # fallback POST fails because GITHUB_TOKEN lacks `administration:write`.
      # Pages is enabled out-of-band as a one-time manual setup step (see
      # project docs); this action only needs to READ the existing Pages
      # config, which works reliably with the `pages: write` scope declared
      # above.
      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

      - id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0