Hand-written README and interactive API documentation

.github/workflows/examples.yml

@@ -8,7 +8,7 @@ on:
   schedule:
     - cron: '0 0 1 * *'  # Runs at 00:00 UTC on the 1st day of every month
 
-# One live run per branch — the README examples run real queries against the
+# One live run per branch — the example queries run against the
 # production VFB backend, so superseded runs are cancelled rather than left to
 # pile up alongside the other live-backend workflows.
 concurrency:
@@ -49,21 +49,10 @@ jobs:
                   f.write('SOLR_AVAILABLE=false\n')
               exit(1)
           "
-      - name: Run examples from README.md
+      - name: Run the example queries against the live backend
         run: |
-          cat README.md | grep -e '```python' -e '```' -e '^[^`]*$' | sed -e '/^```python/,/^```/!d' -e '/^```/d' -e 's/\(vfb\.[^(]*([^)]*)\)/print(\1)/g' > test_examples.py
-          cat test_examples.py
           export VFBQUERY_CACHE_ENABLED=false
-          python test_examples.py
-      - name: Parse README.md and generate test files
-        run: |
-          python -m src.test.readme_parser
-        env:
-          PYTHONPATH: ${{ github.workspace }}
-        if: env.SOLR_AVAILABLE == 'true'
-      - name: Run examples from README.md and validate structure
-        run: |
-          python -m src.test.test_examples_diff
+          python -m pytest -v src/test/test_example_queries.py
         env:
           PYTHONPATH: ${{ github.workspace }}
         if: env.SOLR_AVAILABLE == 'true'

.github/workflows/python-test.yml

@@ -66,19 +66,18 @@ jobs:
           # step turns any skips into a PR-visible warning.
           # Excludes: test_query_performance.py — wall-clock threshold
           # assertions that flap under parallel load, already gated by the
-          # dedicated "Performance Test" workflow; and test_examples_diff.py /
-          # test_examples_code.py — README-example scripts (no pytest tests,
-          # pull in deepdiff/colorama) run by the "Test VFBquery examples"
-          # workflow instead.
+          # dedicated "Performance Test" workflow; and
+          # test_example_queries.py — the canonical worked examples, run
+          # by the "Test VFBquery examples" workflow instead so this job
+          # does not double the live load they put on production.
           # -n 4 rather than -n auto: an explicit cap on how many concurrent
           # query streams one run points at production. `auto` happens to be 4
           # on today's GitHub-hosted ubuntu runner, so this is not a slowdown —
           # it just stops the load on VFB infra changing silently if the hosted
           # runner spec grows.
           pytest -v -ra -n 4 --dist loadscope \
             --ignore=src/test/test_query_performance.py \
-            --ignore=src/test/test_examples_diff.py \
-            --ignore=src/test/test_examples_code.py \
+            --ignore=src/test/test_example_queries.py \
             src/test tests 2>&1 | tee pytest_output.log
       - name: Flag skipped tests (backend unavailable)
         if: always()