docs: convert fenced pycon examples to doctests in boxes.py and draw/utils.py#2425
docs: convert fenced pycon examples to doctests in boxes.py and draw/utils.py#2425shaoming11 wants to merge 6 commits into
Conversation
Convert all fenced ```python and ```pycon examples in draw/utils.py to >>> doctest format so they are automatically verified by the test suite via --doctest-modules. Also normalises 'Examples:' to 'Example:' for Google-style consistency. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace all ```pycon fenced blocks with bare >>> doctest format so examples are automatically verified by the test suite via --doctest-modules. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@shaoming11 ^^ pls 🦝 |
There was a problem hiding this comment.
Pull request overview
This PR converts fenced code blocks in docstring examples to plain >>> doctest format for two core modules, so examples are automatically executed and validated by the existing --doctest-modules test configuration.
Changes:
- Replaced fenced
python /pycon docstring blocks indraw/utils.pywith runnable doctest prompts and simple assertions (e.g.,result.shape). - Removed fenced block markers in
detection/utils/boxes.pyso existing examples are parsed as doctests. - Standardized docstring example headings (e.g.,
Example:) where blocks were converted.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| src/supervision/draw/utils.py | Converts drawing utility docstring examples to runnable doctests (using result = ... and lightweight checks). |
| src/supervision/detection/utils/boxes.py | Removes fenced markers so existing >>> examples become active doctests. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #2425 +/- ##
=======================================
Coverage 87% 87%
=======================================
Files 84 84
Lines 11797 11797
=======================================
Hits 10209 10209
Misses 1588 1588 🚀 New features to boost your workflow:
|
Have you tried to build the docs and see the output?
That was the before, so what is the difference? |
| within the frame resolution. | ||
|
|
||
| Examples: | ||
| ```pycon |
mkdocstrings only recognizes `Examples:` (plural) as a Google-style docstring section and renders bare `>>>` lines as pycon code blocks. With `Example:` (singular) the content fell through to raw Markdown, causing `>>>` to be parsed as nested blockquotes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
@shaoming11 pls do not turn it ready for review until you address my requested changes 🦝 |
- Revert boxes.py to develop: the pycon fences there were already correct and the new check-doctest-fences CI hook requires them - Wrap all converted draw/utils.py doctest blocks in ```pycon fences to satisfy the hook while keeping them executable by --doctest-modules Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Fixes check-doctest-fences CI hook failure — this example was added after the normalization pass and was missing the fence. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Summary
```pycon/```pythonexample blocks insrc/supervision/detection/utils/boxes.pyandsrc/supervision/draw/utils.pyto bare>>>doctest format--doctest-modulesAddresses the project preference stated in CONTRIBUTING.md:
Files changed
src/supervision/detection/utils/boxes.py— 9 fenced blocks converted (clip_boxes,pad_boxes,denormalize_boxes,move_boxes,move_oriented_boxes,xyxyxyxy_to_xyxy,_oriented_box_anchors,scale_boxes,spread_out_boxes)src/supervision/draw/utils.py— 7 fenced blocks converted (draw_line,draw_rectangle,draw_filled_rectangle,draw_rounded_rectangle,draw_polygon,draw_filled_polygon,draw_image)Test plan
uv run pytest --doctest-modules src/supervision/detection/utils/boxes.py— 10 passeduv run pytest --doctest-modules src/supervision/draw/utils.py— all passed🤖 Generated with Claude Code