name: Python

on:
  push:
    branches:
      - master
  pull_request:
    branches:
      - master

# Cancel previous CI runs when new commits are added to a PR.
concurrency:
  group: ${{ github.head_ref || github.run_id }}-python
  cancel-in-progress: true

jobs:
  build:
    # NOTE: runner strategy is to split across os and python version, but test multiple
    # sphinx versions on a single runner.  So do not add a matrix.sphinx-version.
    name: ${{ matrix.os }} / ${{ matrix.python-version }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: true
      matrix:
        os: [macos-latest, ubuntu-latest, windows-latest]
        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
    steps:
      - uses: actions/checkout@v4
      ##################################################################################
      - name: Install Doxygen (macOS)
        if: contains(matrix.os, 'macos')
        run: |
          HOMEBREW_NO_AUTO_UPDATE=1 brew install doxygen
      - name: Install Doxygen (Ubuntu)
        if: contains(matrix.os, 'ubuntu')
        run: |
          sudo apt-get install -y doxygen
      - name: Install Doxygen (Windows)
        if: contains(matrix.os, 'windows')
        uses: ssciwr/doxygen-install@v1
          with:
          version: "1.9.6"
      ##################################################################################
      - name: Doxygen Version Dump
        run: doxygen --version
      ##################################################################################
      - name: Use Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install Python Tools
        run: |
          pip install tox codecov coverage
      # Sphinx 4.3.2 ###################################################################
      - name: Test Python ${{ matrix.python-version }} / sphinx==4.3.2
        env:
          # NOTE: this is the current minimum supported.
          SPHINX_VERSION: '==4.3.2'
        run: |
          tox -e py -- --cov-report xml:coverage.xml --cov
      - name: Upload Code Coverage for Python ${{ matrix.python-version }} / sphinx==4.3.2
        run: |
          codecov --required -X gcov -f coverage.xml --name "[GHA] ${{ matrix.os }}-py${{ matrix.python-version }}-sphinx4.3.2"
      # Don't let code coverage utilities share anything, force clean it all.
      - name: Cleanup Python ${{ matrix.python-version }} Testing / Coverage Artifacts
        run: |
          mv .gitignore nolongerignored
          git clean -n
          git clean -f
          git reset --hard
      # Sphinx 5.x #####################################################################
      - name: Test Python ${{ matrix.python-version }} / sphinx 5.x
        env:
          # Test sphinx 5.x.
          SPHINX_VERSION: '>=5,<6'
        run: |
          tox -e py -- --cov-report xml:coverage.xml --cov
      - name: Upload Code Coverage for Python ${{ matrix.python-version }} / sphinx 5.x
        run: |
          codecov --required -X gcov -f coverage.xml --name "[GHA] ${{ matrix.os }}-py${{ matrix.python-version }}-sphinx5.x"
      # Don't let code coverage utilities share anything, force clean it all.
      - name: Cleanup Python ${{ matrix.python-version }} Testing / Coverage Artifacts
        run: |
          mv .gitignore nolongerignored
          git clean -n
          git clean -f
          git reset --hard
      # Sphinx 6.x #####################################################################
      - name: Test Python ${{ matrix.python-version }} / sphinx 6.x
        env:
          # Test sphinx 6.x.
          SPHINX_VERSION: '>=6,<7'
        run: |
          tox -e py -- --cov-report xml:coverage.xml --cov
      - name: Upload Code Coverage for Python ${{ matrix.python-version }} / sphinx 6.x
        run: |
          codecov --required -X gcov -f coverage.xml --name "[GHA] ${{ matrix.os }}-py${{ matrix.python-version }}-sphinx6.x"
      # Sphinx 7.x #####################################################################
      - name: Test Python ${{ matrix.python-version }} / sphinx 7.x
        env:
          # Test sphinx 7.x.
          # TODO: breathe does not currently support later sphinx.
          # https://github.com/svenevs/exhale/issues/203#issuecomment-1773060684
          SPHINX_VERSION: '>=7,<7.2'
        run: |
          tox -e py -- --cov-report xml:coverage.xml --cov
      - name: Upload Code Coverage for Python ${{ matrix.python-version }} / sphinx 7.x
        run: |
          codecov --required -X gcov -f coverage.xml --name "[GHA] ${{ matrix.os }}-py${{ matrix.python-version }}-sphinx7.x"

