name: Reusable Docs

on:
  workflow_call:
  workflow_dispatch:

permissions:
  contents: read

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

jobs:
  build-doc:
    name: 'Docs'
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
    - name: 'Check out latest PR branch commit'
      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        persist-credentials: false
    - name: 'Set up Python'
      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
      with:
        python-version: '3'
        cache: 'pip'
        cache-dependency-path: 'Doc/requirements.txt'
    - name: 'Install build dependencies'
      run: make -C Doc/ venv

    # To annotate PRs with Sphinx nitpicks (missing references)
    - name: 'Build HTML documentation'
      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
    - name: 'Upload'
      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
      with:
        name: doc-html
        path: Doc/build/html

  # This build doesn't use problem matchers or check annotations
  build_doc_oldest_supported_sphinx:
    name: 'Docs (Oldest Sphinx)'
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    - name: 'Set up Python'
      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
      with:
        python-version: '3.11'  # known to work with Sphinx 4.2
        cache: 'pip'
        cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
    - name: 'Install build dependencies'
      run: make -C Doc/ venv REQUIREMENTS="requirements-oldest-sphinx.txt"
    - name: 'Build HTML documentation'
      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html

  # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
  doctest:
    name: 'Doctest'
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        persist-credentials: false
    - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
      with:
        path: ~/.cache/pip
        key: ubuntu-doc-${{ hashFiles('Doc/requirements.txt') }}
        restore-keys: |
          ubuntu-doc-
    - name: 'Install Dependencies'
      run: sudo ./.github/workflows/posix-deps-apt.sh && sudo apt-get install wamerican
    - name: 'Configure CPython'
      run: ./configure --with-pydebug
    - name: 'Build CPython'
      run: make -j4
    - name: 'Install build dependencies'
      run: make -C Doc/ PYTHON=../python venv
    # Use "xvfb-run" since some doctest tests open GUI windows
    - name: 'Run documentation doctest'
      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" doctest