Hand-written README and interactive API documentation - #96
Merged
Conversation
The README had grown into a 2,800-line generated document because the examples CI executes and diffs lived inside it. They are a test asset, so they now live at src/test/example_queries.md, verbatim, under a header saying what consumes them. readme_parser and the (renamed) update_examples.py/fix_examples.py point at the fixture; extraction parity checked — 5 python and 4 json blocks, identical to the old README, with the parser regenerating byte-identical test files. The examples workflow's sed still reads README.md until the companion .github/workflows/examples.yml change lands separately (the release PAT cannot push workflow files); the new README's quick-start block is runnable, so the job stays green either way.
What VFBquery is, the stores it fans out over, install, a short quick start, the HTTP API with its interactive documentation page, and where the deeper documentation lives. The worked examples it used to carry are now the validated fixture in src/test/.
GET / is now a self-contained page in the style of the hosted-CATMAID /apis/ pages and virtualflybrain.org (vfb-nova palette, light and dark): every endpoint with its parameters, pre-filled runnable examples, and live results fetched from the same origin. GET /docs.json is the machine-readable catalogue; the run_query query types and the CATMAID command registry are injected from their own modules so the page cannot drift from the server. Tests pin the docs to ALLOWED_PATHS in both directions and require an example on every required parameter.
Companion to the fixture move: the sed extraction and the step names now read src/test/example_queries.md instead of README.md.
|
The fixture-markdown stopgap kept the whole old pipeline alive: a sed extraction executing code blocks, readme_parser regenerating three throwaway modules, and test_examples_diff — a script, not a pytest module, whose deepdiff comparison was never actually wired up, so the recorded JSON had drifted unnoticed (Synonyms left two term reports; nobody was told). src/test/test_example_queries.py replaces all of it: the same five canonical calls run live, the old structure assertions preserved, and each result compared shape-not-content against recordings in src/test/example_expected/ — content may change freely, a key or type disappearing fails. Integer dict keys survive the JSON round trip, and 'python -m src.test.test_example_queries --record' refreshes the recordings (the successor to update_readme.py). Recordings re-recorded from live as the new baseline. examples.yml now just runs pytest on the file; python-test.yml ignores it so the live load is not doubled; deepdiff/colorama leave tests/requirements.txt; the markdown fixture, parser, generated modules and orphaned one-off helpers are deleted.
Robbie1977
added a commit
that referenced
this pull request
Aug 30, 2026
The examples workflow's move to pytest (PR #96) broke it on Python 3.8: pytest resolves ignore::<class> filters at startup and exits 4 when the class does not exist, and that job's older marshmallow predates ChangedInMarshmallow4Warning. Both classes subclass DeprecationWarning, so filter DeprecationWarning from the marshmallow module instead — version-proof, and user-code DeprecationWarnings still show. Verified the suite still runs with zero marshmallow warnings leaking.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
The README was a 2,800-line generated document because the examples CI executes and diffs lived inside it. Those examples are now a real test,
src/test/test_example_queries.py: the same five canonical calls run live against the backend, the old structure assertions are preserved, and each result is compared shape-not-content against recordings insrc/test/example_expected/— content may change freely, a key or type disappearing fails, andpython -m src.test.test_example_queries --recordrefreshes the recordings when a schema change is intentional. The whole old pipeline (the sed extraction,readme_parser.py, the generated modules,test_examples_diff.py— whose deepdiff comparison was never actually wired up, so the recordings had drifted unnoticed) is deleted,examples.ymljust runs pytest, andpython-test.ymlignores the file so the live load is not doubled. The README is replaced by a hand-written page: what VFBquery is, how it works, install, quick start, and where the deeper documentation lives.The HA API now serves interactive documentation at its root, in the style of the hosted-CATMAID
/apis/pages and virtualflybrain.org: every endpoint with its parameters, pre-filled runnable examples, and live results fetched from the same origin, plus a machine-readable catalogue at/docs.json. Therun_queryquery types and CATMAID command registry are injected from their own modules, and tests pin the docs toALLOWED_PATHSin both directions so the page cannot drift from the server.How to test
pytest tests/test_api_docs.py src/test/test_example_queries.py, thenpython -m vfbquery.ha_apiand openhttp://localhost:8080/.Follow-ups left
No proxy change is needed: the v3-cached nginx already passes
/and/docs.jsonthrough (and does not cache the 404s the current release returns for them), so the page appears as soon as this release is deployed and is then cached like every other response. After each vfbquery upgrade the two URLs should be refreshed the same way other entries are — one whitelistedX-Force-Refreshrequest each, worth adding to the post-release precache list.