`prefer-fenced-code-blocks`¶

Part of: Enrichment Check


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

Examples section uses doctest (>>>) or reStructuredText (::) indented code blocks instead of fenced code blocks

What it detects¶

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

Why is this a problem?¶

mkdocs-material renders fenced code blocks with syntax highlighting, copy buttons, and line numbers. Doctest >>> format and rST :: indented blocks render as plain, unhighlighted text with no copy button or annotations, resulting in a noticeably worse reading experience on your documentation site. The :: literal may even render as visible text.

How to Fix¶

Replace doctest >>> format or rST :: indented blocks with triple-backtick fenced code blocks and a language marker:

Doctest >>> format:

Examples:
    ```python
    add(1, 2)  # returns 3
    add(-1, 1)  # returns 0
    ```

rST :: indented block — remove :: from the directive line and wrap the code in fenced backticks:

Examples:
    Run the check:

    ```bash
    $ docvet check --all
    ```

Examples¶

Doctest `>>>` format¶

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

rST `::` indented block¶