docs.yaml

#
name: Docs

on:
  push:
    branches:
      # NOTE: the workflow runs from the current branch
      # only the branch name matching the current branch actually matters
      # but we list them all to minimise the diff across branches
      - 'main'
      - '*-maintenance'
  pull_request:
  workflow_call:
  workflow_dispatch:

permissions: {}

# Disable concurrency for convenience while the link checker is disabled.
# concurrency:
#   group: ${{ github.workflow }}-${{ github.ref }}
#   cancel-in-progress: true

jobs:
  docchecks:
    name: Checks
    runs-on: ubuntu-22.04
    outputs:
      spellcheck-result: ${{ steps.spellcheck-step.outcome }}
      linkcheck-result: ${{ steps.linkcheck-step.outcome }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
      - name: Install uv
        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
      - name: Spelling
        id: spellcheck-step
        if: success() || failure()
        continue-on-error: true
        run: uvx --from=rust-just just docs spelling
      # Disable link checking until we get a more robust solution.
      # The current approach often fails due to rate limiting and timeouts.
      # - name: Links
      #   id: linkcheck-step
      #   if: success() || failure()
      #   run: |
      #     set -xueo pipefail
      #     uvx --from rust-just just docs linkcheck ${{ github.event_name != 'pull_request' && '--tag check-github-links' || '' }}
      - name: Local Sphinx extensions static analysis
        if: success() || failure()
        run: uvx --from=rust-just just docs ext-static
      - name: Local Sphinx extensions unit tests
        if: success() || failure()
        run: uvx --from=rust-just just docs ext-unit