Make the documented examples executable - #88
Open
tschm wants to merge 2 commits into
Open
Conversation
interrogate reported 100% docstring coverage while nothing checked whether any docstring was true: the examples were markdown ```python fences, which doctest never sees. rhiza's own test_docstrings.py said as much by skipping with "No doctests were found in any module". The fences are now >>> doctests. Those that can run, do — find_free_port, stop_server, get_server_status, and new examples on validate_input, DataManager and DataManager.get_chunk, which are pure and had no examples at all despite being the data contract. Those that cannot are marked # doctest: +SKIP with the reason stated in prose: plot() starts a server and opens a browser, run_server() blocks until the server stops. Their data-preparation lines still execute, so the setup stays honest even where the call is illustrative. This turned up one example that was already broken: plot()'s referenced an `sma` name that was never defined, so it would have raised NameError had anyone run it. It now passes a defined array. In the README, the stop_server and get_server_status examples were self-contained, so +RHIZA_SKIP is removed and they execute. The remaining four skips carry an HTML comment saying why — three reference series the reader supplies, and the `plot` block is an annotated signature that is not valid Python at a call site. make rhiza-test now runs 49 doctest assertions instead of skipping; check_doc_examples.py reports 56 examples across 9 objects, up from 0, and executes the README's Python fences with returncode 0. Closes alihaskar#84 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This pull request converts previously non-executable documentation examples (markdown ```python fences) into real doctest examples (>>> ...) so that docstrings and selected README examples are machine-verified during CI.
Changes:
- Replaced docstring markdown fences with executable doctests across the public API and server utilities, adding skips where execution would be side-effectful (browser/server blocking).
- Added new doctest coverage for core data-contract utilities (
validate_input,DataManager,DataManager.get_chunk). - Updated README examples by removing unnecessary
+RHIZA_SKIPwhere examples are self-contained, and documenting skip reasons where execution isn’t feasible.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/pycharting/data/ingestion.py | Adds doctest examples for input validation and data slicing, increasing executable documentation coverage for the data contract. |
| src/pycharting/core/server.py | Converts find_free_port and run_server doc examples to doctests, using skips for blocking calls. |
| src/pycharting/api/interface.py | Converts plot, stop_server, and get_server_status examples to doctests with appropriate +SKIP on side-effectful calls. |
| src/pycharting/init.py | Replaces the module-level usage fence with doctests to make the top-level API description executable. |
| README.md | Un-skips self-contained examples and adds explicit skip rationale comments for examples that cannot be executed. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| # input("Press Enter to stop...") | ||
| # stop_server() | ||
| ``` | ||
| The public surface is three functions, re-exported at the top level: |
Comment on lines
+77
to
+81
| Scan a preferred range instead: | ||
|
|
||
| # Scan a preferred range instead. | ||
| port = find_free_port(8000, 8010) | ||
| ``` | ||
| >>> port = find_free_port(8000, 8010) | ||
| >>> 8000 <= port < 8010 | ||
| True |
The previous commit un-skipped the stop_server and get_server_status fences so they run, but left no ```result block. test_readme_runs concatenates every result block and compares it to the merged stdout of every executed python block, so it compared two printed lines against the empty string and failed in CI. Both lines are now documented where they belong: the "no active server" notice under stop_server, the status dict under get_server_status. Document order matches stdout order, so the concatenation lines up. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
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.
Closes #84
Problem
interrogatereported 100% docstring coverage while nothing checked whether any docstring was true: the examples were markdown```pythonfences, whichdoctestnever sees. rhiza's own check said so by skipping:Change
The fences are now
>>>doctests.Those that can run, do —
find_free_port,stop_server,get_server_status, plus new examples onvalidate_input,DataManagerandDataManager.get_chunk. Those three had no examples at all despite being the data contract, and they are pure, so they doctest cleanly.Those that cannot are
# doctest: +SKIP, with the reason in prose —plot()starts a server and opens a browser;run_server()blocks until the server stops. Their data-preparation lines still execute, so the setup stays honest even where the call is illustrative.One example was already broken
plot()'s example passedoverlays={"SMA 20": sma}wheresmawas never defined — it would have raisedNameErrorfor anyone who ran it. That is precisely the failure mode this issue is about. It now passes a defined array.README
stop_serverandget_server_statuswere self-contained, so+RHIZA_SKIPis removed and they execute. The remaining four skips carry an HTML comment saying why: three reference series the reader supplies, and theplotblock is an annotated signature that is not valid Python at a call site.Verification
make rhiza-test— 116 passed, 2 skipped (was 115/3);test_doctestsnow runs 49 assertions instead of skippingcheck_doc_examples.py --source-root src --run— 56 examples across 9 objects (was 0), README Python fences execute with returncode 0make test— 172 passed, coverage 100%;make typecheck,make fmtcleanThe one remaining checker note is the untagged fence at the project-structure tree, which is #85's fix on its own branch.
🤖 Generated with Claude Code