prefer-fenced-code-blocks

Part of: Enrichment Check

Check	enrichment
Category	recommended
Applies to	any symbol
Since	v1.0.0

Examples section uses doctest format instead of fenced code blocks

What it detects

This rule flags Examples: sections that use doctest >>> format instead of triple-backtick fenced code blocks with a python language marker.

Why is this a problem?

mkdocs-material renders fenced code blocks with syntax highlighting, copy buttons, and line numbers. Doctest >>> format renders as plain, unhighlighted text, resulting in a noticeably worse reading experience on your documentation site. Fenced blocks also support annotations and other material theme features.

Example

ViolationFix

def add(a: int, b: int) -> int:
    """Add two numbers.

    Args:
        a: First number.
        b: Second number.

    Returns:
        Sum of a and b.

    Examples:
        >>> add(1, 2)
        3
        >>> add(-1, 1)
        0
    """
    return a + b

def add(a: int, b: int) -> int:
    """Add two numbers.

    Args:
        a: First number.
        b: Second number.

    Returns:
        Sum of a and b.

    Examples:
        ```python
        add(1, 2)  # returns 3
        add(-1, 1)  # returns 0
        ```
    """
    return a + b