Skip to content

docs: convert fenced pycon examples to doctests in boxes.py and draw/utils.py#2425

Draft
shaoming11 wants to merge 6 commits into
roboflow:developfrom
shaoming11:docs/convert-boxes-examples-to-doctests
Draft

docs: convert fenced pycon examples to doctests in boxes.py and draw/utils.py#2425
shaoming11 wants to merge 6 commits into
roboflow:developfrom
shaoming11:docs/convert-boxes-examples-to-doctests

Conversation

@shaoming11

Copy link
Copy Markdown

Summary

  • Converts all fenced ```pycon / ```python example blocks in src/supervision/detection/utils/boxes.py and src/supervision/draw/utils.py to bare >>> doctest format
  • Examples are now automatically verified by the test suite via --doctest-modules
  • No logic changes — purely docstring formatting

Addresses the project preference stated in CONTRIBUTING.md:

when an example uses only supervision, NumPy, and the standard library … prefer >>> doctest format so it is automatically verified by the test suite

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 passed
  • uv run pytest --doctest-modules src/supervision/draw/utils.py — all passed

🤖 Generated with Claude Code

shaoming11 and others added 2 commits July 12, 2026 15:17
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
shaoming11 requested a review from SkalskiP as a code owner July 12, 2026 21:02
@CLAassistant

CLAassistant commented Jul 12, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@Borda

Borda commented Jul 13, 2026

Copy link
Copy Markdown
Member

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

@shaoming11 ^^ pls 🦝

@Borda
Borda marked this pull request as draft July 13, 2026 07:31

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 in draw/utils.py with runnable doctest prompts and simple assertions (e.g., result.shape).
  • Removed fenced block markers in detection/utils/boxes.py so 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

codecov Bot commented Jul 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87%. Comparing base (206adc0) to head (5439751).
⚠️ Report is 1 commits behind head on develop.

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:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@Borda
Borda marked this pull request as ready for review July 14, 2026 10:30
@Borda

Borda commented Jul 14, 2026

Copy link
Copy Markdown
Member
  • Converts all fenced ```pycon / ```python example blocks in src/supervision/detection/utils/boxes.py and src/supervision/draw/utils.py to bare >>> doctest format

Have you tried to build the docs and see the output?

  • Examples are now automatically verified by the test suite via --doctest-modules

That was the before, so what is the difference?

within the frame resolution.

Examples:
```pycon

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this removal breaks the docs

@Borda
Borda marked this pull request as draft July 18, 2026 23:27
Borda and others added 2 commits July 20, 2026 13:36
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
shaoming11 marked this pull request as ready for review July 20, 2026 17:53
@Borda
Borda marked this pull request as draft July 20, 2026 20:01
@Borda

Borda commented Jul 20, 2026

Copy link
Copy Markdown
Member

@shaoming11 pls do not turn it ready for review until you address my requested changes 🦝

shaoming11 and others added 2 commits July 20, 2026 18:43
- 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants