test-userguide.yml

# When a Pull Request is opened that modifies
# the User Guide source, build the User Guide
# with Sphinx and let the contributor know of
# any errors.
name: Test User Guide

on:
  pull_request:
    paths:
      - 'user_guide_src/**'
      - '.github/workflows/test-userguide.yml'

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  syntax_check:
    name: Check User Guide syntax
    runs-on: ubuntu-24.04

    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Setup Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: '3.12'

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

      - name: Detect usage of tabs in RST files
        run: php utils/check_tabs_in_rst.php

      - name: Build Docs with Sphinx
        run: make html SPHINXOPTS="-W --keep-going -w /tmp/sphinx-log"
        working-directory: user_guide_src