Repository navigation
Run the Python quick start in CI #215
Description
Problem
The Python quick start has three
Python blocks that build up one session: build and search, measure recall, then save and
load. Nothing runs them in CI, so an API change can break the page without failing a test.
Task
Add a Python test that reads docs/docs/quick_start.md, extracts the ```python
blocks in order and executes them in one shared namespace against the installed package.
Done when
- The test reads the Markdown file; it does not keep a second copy of the example.
- All three blocks run in order, and the save/load block's assertions pass.
- No files are left behind (the save/load block already uses
TemporaryDirectory). - Breaking a block (for example renaming
nprobeton_probe) makes the test fail.
Where to start
docs/docs/quick_start.md- Existing Python tests in
tests/python/;tests/python/test_examples.pyruns the sample
scripts and is a useful reference. - Setup and checks: contribution guide, Python changes.
Comment here before starting so two people don't take the same task.
Activity
OptiSolvD commentedon Nov 7, 2026
Hi @gouyt13, I’d like to work on this issue. Could you please assign it to me?
My plan:
Add tests/python/test_quick_start.py, which reads docs/docs/quick_start.md (no second copy of the example) and extracts the ```python blocks in order.
Run them in one shared namespace, compiled with a per-block filename so a failure points to the exact block. The test runs from a temporary working directory so nothing is left behind.
Assert that blocks were actually found, so a change in the fence format can’t make the test silently run nothing.
Verify that renaming nprobe to n_probe makes the test fail, then run ./scripts/check-python.sh and the Python test suite.
Two quick questions:
Should the test assert exactly three blocks, or only that at least one exists, so that adding a block to the quick start doesn’t require editing the test?
Is there any block you’d want skipped or treated differently (for example a block with a non-runnable snippet), or should every ```python block be run?
I’ll follow the contribution guide and wait for the assignment before opening a PR. Thanks!
OptiSolvD commentedon Nov 7, 2026
Hi @gouyt13!
I've completed the implementation and submitted PR #224.
The test reads the Python code blocks directly from
docs/docs/quick_start.mdand executes them sequentially in a shared namespace against the installed package.I've verified the implementation with:
bash scripts/check-python.shscript (all checks passed).I've also requested your review on the PR.
Whenever you get a chance, please review PR #224 and let me know if any changes are needed.
Thank you for assigning this issue to me!
gouyt13 commentedon Nov 8, 2026
Fixed by #224 (merge d6c7e25). Thanks @OptiSolvD!
On top of the new test, 6501fae makes CI run it when a PR changes only
docs/docs/quick_start.md. Such PRs used to run only the documentation build; they now also run the Linux source-install job, whose smoke tests includetests/python/test_quick_start.py.