linkcheck.yaml

# This is a separate documentation build just to check links. We don't check
# links as part of the normal documentation build since, unlike Sphinx errors
# and warnings, we don't want broken links to block a merge. (Sometimes they
# will be fixed by the same merge, sometimes they're temporary rate limit
# issues.) It also takes about 30 minutes to run the link check due to GitHub
# throttling.
#
# Instead, we only run link checking when explicitly requested and once per
# week to catch any links that have gone stale or were broken.

name: Link Check

"on":
  schedule:
    - cron: "0 12 * * 1"
  workflow_dispatch: {}

jobs:
  linkcheck:
    runs-on: ubuntu-latest

    # Takes about 35m to run with rate limiting from GitHub as of 2025-07-14.
    timeout-minutes: 60

    steps:
      - uses: actions/checkout@v6
        with:
          # Ensure the documentation gets the right version.
          fetch-depth: 0

      - uses: astral-sh/setup-uv@v7

      - name: Install graphviz
        run: |
          sudo apt-get update
          sudo apt-get install -y graphviz

      - name: Check links
        run: uv run --only-group=tox tox run -e docs-linkcheck