ci.yml

# This file invokes Nox sessions to run tests, build documentation, and
# perform other continuous integration (CI) checks. The Nox sessions are
# defined in noxfile.py.

name: CI

on:
  push:
    branches:
    - main
    - stable
    - v*.*.*
    tags:
    - v*
  pull_request:
  workflow_dispatch:

env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

jobs:

  tests:
    name: ${{ matrix.name }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 20

    strategy:
      fail-fast: false

      matrix:
        include:

        - name: Tests, Python 3.12, Ubuntu
          os: ubuntu-latest
          python: '3.12'
          nox_session: tests

        - name: Documentation, Python 3.12, Ubuntu
          os: ubuntu-latest
          python: '3.12'
          nox_session: docs

        - name: Packaging, Python 3.12, Ubuntu
          os: ubuntu-latest
          python: '3.12'
          nox_session: build

    steps:

    - name: Checkout code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python }}
        cache: pip

    - name: Install graphviz and pandoc for documentation builds
      if: startsWith(matrix.name, 'Documentation')
      run: sudo apt-get install graphviz pandoc

    - name: Install Nox and uv
      run: python -m pip install --progress-bar off --upgrade nox uv

    - name: Cache .nox to shorten virtual environment creation time
      uses: actions/cache@v4
      with:
        path: |
          .nox
        # Changing pyproject.toml or requirements invalidates the cache
        key: ${{ matrix.nox_session }}-${{ matrix.python }}-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}

    - name: Run Nox session
      run: nox -s '${{ matrix.nox_session }}'

    - name: Upload coverage reports to Codecov
      if: ${{ contains(matrix.nox_session, 'cov') }}
      uses: codecov/codecov-action@v4
      with:
        file: ./coverage.xml
        fail_ci_if_error: false
      env:
        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}