name: Docs

on:
  #push:
  #  branches:
  #  - master
  #  - 3.9
  #  - 3.8
  #  - 3.7
  #  paths:
  #  - 'Doc/**'
  pull_request:
    branches:
    - master
    - 3.10
    - 3.9
    - 3.8
    - 3.7
    paths:
    - 'Doc/**'
    - 'Misc/**'

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
    steps:
    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
    - name: Register Sphinx problem matcher
      run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
    - name: 'Set up Python'
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
      with:
        python-version: '3.12'
        cache: 'pip'
        cache-dependency-path: 'Doc/requirements.txt'
    - name: 'Install build dependencies'
      run: make -C Doc/ venv
    - name: 'Build HTML documentation'
      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
    - name: 'Upload'
      uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
      with:
        name: doc-html
        path: Doc/build/html
        include-hidden-files: true
        overwrite: true

  # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
  doctest:
    name: 'Doctest'
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
    - name: Register Sphinx problem matcher
      run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
    - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
      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