Add docs-tests.yml workflow; carve test_doc_snippets.py out of rust-test.yml

PR igerber#389 (Batch A) shipped six broken HAD doc snippets in 2026-04 that
no CI run caught because rust-test.yml only triggers on
rust/, diff_diff/, tests/, pyproject.toml, and the workflow file —
none of which include docs/. PR igerber#396 patched the snippets but did not
address the structural gap. This PR addresses it.

Two changes:

1. New .github/workflows/docs-tests.yml — separate workflow that
   runs `pytest tests/test_doc_snippets.py -v` on a single
   ubuntu-latest / py3.14 / pure-Python runner. Triggers on
   docs/, diff_diff/, tests/test_doc_snippets.py, pyproject.toml,
   and the workflow file itself; same ready-for-ci label gate as
   rust-test.yml / notebooks.yml. Mirrors notebooks.yml's shape
   (the existing precedent for `pytest`-validated docs assets) so
   the two doc-validation workflows look like siblings.

2. .github/workflows/rust-test.yml: add
   --ignore=tests/test_doc_snippets.py to all three pytest
   invocations so doc snippets stop riding the code workflow.

   The Pure Python Fallback edit (line 193) is the only one that
   changes CI signal: that job runs from the repo root and was the
   ONLY place where test_doc_snippets.py actually executed. The two
   Rust-matrix edits (lines 158, 165) are defensive consistency: the
   matrix copies tests/ to /tmp/tests (rust-test.yml:138, 142)
   without docs/, so DOCS_DIR resolves to /tmp/docs/ which doesn't
   exist; the test collector silently skips every RST file via the
   guard at tests/test_doc_snippets.py:129. Adding --ignore there
   prevents the no-op from becoming a real run if anyone later adds
   `cp -r docs ...` to the copy steps. Each invocation now carries
   an in-YAML comment documenting which case it's the defensive vs
   behavior-changing edit.

Verification:
- python -c "import yaml; yaml.safe_load(open('.github/workflows/
  docs-tests.yml')); yaml.safe_load(open('.github/workflows/
  rust-test.yml'))" — both files well-formed.
- pytest tests/ --ignore=tests/test_doc_snippets.py
  --ignore=tests/test_rust_backend.py --collect-only — 0 occurrences
  of test_doc_snippets in the collected set (was 115 cases collected
  when not ignored), confirming pytest accepts repeated --ignore
  flags as the existing line-193 pattern with --ignore=tests/
  test_rust_backend.py already showed.

After this PR opens, the workflow file itself triggers docs-tests.yml
on its own change, providing the first end-to-end CI validation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

.github/workflows/docs-tests.yml

@@ -0,0 +1,56 @@
+name: Documentation Tests
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'diff_diff/**'
+      - 'tests/test_doc_snippets.py'
+      - 'pyproject.toml'
+      - '.github/workflows/docs-tests.yml'
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+    paths:
+      - 'docs/**'
+      - 'diff_diff/**'
+      - 'tests/test_doc_snippets.py'
+      - 'pyproject.toml'
+      - '.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

.github/workflows/rust-test.yml

@@ -155,14 +155,18 @@ jobs:
       - name: Run tests with Rust backend (Unix)
         if: runner.os != 'Windows'
         working-directory: /tmp
-        run: DIFF_DIFF_BACKEND=rust pytest tests/ -q -n auto --dist worksteal -m ''
+        # Doc snippet tests own .github/workflows/docs-tests.yml; ignore
+        # them here to keep one workflow per surface and avoid double
+        # execution (the matrix copies tests/ to /tmp/tests without
+        # docs/, so this ignore is defensive on the Rust path).
+        run: DIFF_DIFF_BACKEND=rust pytest tests/ --ignore=tests/test_doc_snippets.py -q -n auto --dist worksteal -m ''
 
       - name: Run tests with Rust backend (Windows)
         if: runner.os == 'Windows'
         working-directory: ${{ runner.temp }}
         run: |
           $env:DIFF_DIFF_BACKEND="rust"
-          pytest tests/ -q -n auto --dist worksteal -m ''
+          pytest tests/ --ignore=tests/test_doc_snippets.py -q -n auto --dist worksteal -m ''
         shell: pwsh
 
   # Test pure Python fallback (without Rust extension)
@@ -190,4 +194,8 @@ jobs:
           PYTHONPATH=. python -c "from diff_diff import HAS_RUST_BACKEND; print(f'HAS_RUST_BACKEND: {HAS_RUST_BACKEND}'); assert not HAS_RUST_BACKEND"
 
       - name: Run tests in pure Python mode
-        run: PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest tests/ -q --ignore=tests/test_rust_backend.py -n auto --dist worksteal
+        # Doc snippet tests own .github/workflows/docs-tests.yml; ignore
+        # them here to keep one workflow per surface (this is the only
+        # invocation that actually executes test_doc_snippets.py since
+        # this job runs from the repo root, not /tmp/tests).
+        run: PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest tests/ -q --ignore=tests/test_rust_backend.py --ignore=tests/test_doc_snippets.py -n auto --dist worksteal