Convert docstring examples to functional doctests

[Copilot]

Converted all method/function-level Python code examples from markdown blocks to executable doctest format. This enables automatic validation of documentation examples against the actual codebase.

Changes

36 files converted with 151 doctests (98 executable, 53 skipped for external dependencies):

• Utils: file, iterables, internal, image, notebook, video
• Draw: color, utils
• Detection: core, line_zone, utils/, tools/
• Annotators: core, utils
• Metrics: detection, precision, recall, f1_score, MAP, MAR
• Dataset: core, utils
• Key Points: core, annotators
• Classification, Tracker, Assets, Geometry

Format conversion

Before:

def from_hex(cls, color_hex: str) -> Color:
    """
    Example:
        ```python
        import supervision as sv
        
        sv.Color.from_hex('#ff00ff')
        # Color(r=255, g=0, b=255)
        ```
    """

After:

def from_hex(cls, color_hex: str) -> Color:
    """
    Example:
        >>> import supervision as sv
        >>> sv.Color.from_hex('#ff00ff')
        Color(r=255, g=0, b=255)
    """

Handling external dependencies

Examples requiring non-core dependencies (ultralytics, transformers, inference) use # doctest: +SKIP:

>>> model = YOLO("yolov8n.pt")  # doctest: +SKIP

Intentionally not converted

Class-level overview documentation in detection/core.py and key_points/core.py retains markdown format. These use MkDocs tab syntax (=== "Framework") for multi-framework integration examples and serve documentation purposes, not testing.

Validation

pytest supervision/ --doctest-modules -v
# 98 passed, 53 skipped

Original prompt

Converting Docstrings to Functional Doctests
The primary objective was to convert all Python code examples in the supervision package docstrings into functional doctests.
Core Requirements:

1. Standard Formatting: Convert python blocks into the standard doctest format using >>> for code and ... for continuations.
2. Self-Contained Examples: Ensure examples are runnable without external files. Replace path placeholders with synthetic data like np.zeros.
3. Accuracy and Precision: Fix floating-point discrepancies and type mismatches (e.g., np.float64 vs float) to ensure the "Expected" output matches the "Got" output exactly.
4. Selective Skipping: Use # doctest: +SKIP for examples requiring external heavy libraries like ultralytics or transformers.
5. Validation: All changes must be verified by running "pytest supervision/ -v".

Current Status: All major modules including core, annotators, datasets, metrics, and utils have been updated. Existing errors in original examples were fixed, and all doctests are currently passing.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.