docs-tests.yml

name: Documentation Tests

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'diff_diff/**'
      - 'tests/test_doc_snippets.py'
      # tests/conftest.py is auto-loaded by pytest for the snippet
      # test run and mutates sys.path + MPLBACKEND (conftest.py:14, 18);
      # changes there can break snippet exec without touching the test
      # file itself.
      - 'tests/conftest.py'
      - 'pyproject.toml'
      # sphinx-build job mirrors RTD setup; trigger when RTD config drifts
      # (Python version, apt packages, post_install docs deps).
      - '.readthedocs.yaml'
      - '.github/workflows/docs-tests.yml'
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened, labeled, unlabeled]
    paths:
      - 'docs/**'
      - 'diff_diff/**'
      - 'tests/test_doc_snippets.py'
      - 'tests/conftest.py'
      - 'pyproject.toml'
      # sphinx-build job mirrors RTD setup; trigger when RTD config drifts
      # (Python version, apt packages, post_install docs deps).
      - '.readthedocs.yaml'
      - '.github/workflows/docs-tests.yml'
  schedule:
    # Weekly Sunday 6am UTC - smoke test that snippets still execute
    # against current upstream deps (mirrors notebooks.yml schedule).
    - cron: '0 6 * * 0'

permissions:
  contents: read

jobs:
  doc-snippets:
    name: Validate RST code snippets
    if: >-
      github.event_name != 'pull_request'
      || contains(github.event.pull_request.labels.*.name, 'ready-for-ci')
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          # 3.14 to mirror Pure Python Fallback (the only existing job
          # that actually ran these tests). notebooks.yml uses 3.11 for
          # nbmake compat, not relevant here.
          python-version: '3.14'

      - name: Install dependencies
        # Keep in sync with pyproject.toml [project.dependencies] and [project.optional-dependencies.dev]
        run: pip install numpy pandas scipy pytest

      - name: Run doc snippet tests in pure Python mode
        # PYTHONPATH=. lets the test import diff_diff directly from
        # source without invoking the maturin/Rust build (mirrors Pure
        # Python Fallback at rust-test.yml:189-193).
        run: PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest tests/test_doc_snippets.py -v

  sphinx-build:
    name: Sphinx HTML build (-W warnings as errors)
    if: >-
      github.event_name != 'pull_request'
      || contains(github.event.pull_request.labels.*.name, 'ready-for-ci')
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Install pandoc
        # nbsphinx invokes pandoc to render notebook markdown cells.
        run: sudo apt-get update && sudo apt-get install -y pandoc

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          # Match the RTD build (.readthedocs.yaml:9) so CI catches drift
          # against what users actually see on diff-diff.readthedocs.io.
          python-version: '3.11'

      - name: Install docs dependencies
        # Keep in sync with pyproject.toml [project.optional-dependencies.docs]
        # and .readthedocs.yaml post_install. Skips the maturin/Rust build:
        # docs/conf.py imports diff_diff via sys.path from checked-out source.
        # ipython provides the 'ipython3' Pygments lexer that nbsphinx uses
        # for notebook code cells; without it -W fires highlighting_failure.
        run: pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.7.0" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "matplotlib>=3.5" "ipython>=8.0"

      - name: Build docs with warnings as errors
        # SPHINXOPTS="-W" turns every Sphinx warning into a build failure.
        # PR #410 brought make html to 0 warnings; -W keeps it that way by
        # blocking any new warning from sneaking in.
        run: make -C docs html SPHINXOPTS="-W"

  docs-deps-py39-smoke:
    name: Validate docs deps install on Python 3.9 (floor compat)
    if: >-
      github.event_name != 'pull_request'
      || contains(github.event.pull_request.labels.*.name, 'ready-for-ci')
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.9
        uses: actions/setup-python@v6
        with:
          # 3.9 is the project's declared floor (pyproject.toml requires-python
          # >=3.9). The sphinx-build job above runs on 3.11; this job verifies
          # the docs dependency set actually installs on the floor Python so
          # we catch drift like pydata-sphinx-theme>=0.17.1 (which requires
          # Python>=3.10) before it lands.
          python-version: '3.9'

      - name: Install docs dependencies
        # Same pip install line as sphinx-build above. Just installs - does
        # not run a Sphinx build (sphinx-build covers full rendering on 3.11).
        # Failure here means the docs floor declared in pyproject.toml /
        # .readthedocs.yaml / above is not installable on Python 3.9.
        run: pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.7.0" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "matplotlib>=3.5" "ipython>=8.0"

      - name: Confirm pydata-sphinx-theme version
        # Surface the resolved version in the log for future debugging.
        # Avoid `pip show ... | head -3`: `head` closes the pipe after 3
        # lines and `pip show` exits non-zero under bash -o pipefail
        # (GitHub Actions default), failing the step despite a clean install.
        run: python -c "import importlib.metadata as m; print('pydata-sphinx-theme', m.version('pydata-sphinx-theme'))"