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:
      # 6.0.2
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd

      # 6.2.0
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
        with:
          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
        uses: actions/upload-artifact@v4
        with:
          name: Documentation
          path: docs/_build/**/html

  linkcheck:
    name: Linkcheck
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      # 6.0.2
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd

      # 6.2.0
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
        with:
          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.0
      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
        if: always()
        with:
          name: Linkcheck report
          path: docs/_build/**/linkcheck/output.txt