docs.yml

name: Docs

on:
  push:
    branches:
      - master
  pull_request:
    types: [opened, edited, reopened, synchronize, ready_for_review]

permissions:
  contents: read

jobs:
  build:
    name: Build documentation
    runs-on: ubuntu-latest
    steps:
      # 7.0.0
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
        with:
          persist-credentials: false

      # 6.3.0
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
        with:
          # Same as RTD workflow
          python-version: '3.11'
          cache: 'pip'
          cache-dependency-path: '**/requirements*.txt'

      - name: Install dependencies
        run: |
          python3 -m pip install -U pip
          pip install -U -r requirements.txt

      - name: Sphinx build
        run: |
          echo "::add-matcher::.github/matchers/sphinx.json"
          make -C docs/ html SPHINXOPTS="${SPHINXOPTS}"
          echo "::remove-matcher owner=sphinx::"
        env:
          SPHINXOPTS: -n -W -a --keep-going

      - name: Upload docs as artifacts
        # 7.0.1
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: Documentation
          path: docs/_build/**/html

  linkcheck:
    name: Linkcheck
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      # 7.0.0
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
        with:
          persist-credentials: false

      # 6.3.0
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
        with:
          python-version: '3.13'
          cache: 'pip'
          cache-dependency-path: '**/requirements*.txt'

      - name: Install dependencies
        run: |
          python3 -m pip install -U pip
          pip install -U -r requirements.txt

      - name: Sphinx linkcheck
        run: |
          make -C docs/ linkcheck SPHINXOPTS="${SPHINXOPTS}"
        env:
          SPHINXOPTS: -n -W -a --keep-going

      - name: Sphinx linkcheck collect
        if: always()
        run: |
          echo "::add-matcher::.github/matchers/sphinx-linkcheck.json"
          echo "::add-matcher::.github/matchers/sphinx-linkcheck-warn.json"
          sed 's@^@docs/@' docs/_build/linkcheck/output.txt
          echo "::remove-matcher owner=sphinx::"
          echo "::remove-matcher owner=sphinx-warn::"

      # 7.0.1
      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        if: always()
        with:
          name: Linkcheck report
          path: docs/_build/**/linkcheck/output.txt