Skip to content

section-underline-not-over-indented (D215)#

Derived from the pydocstyle linter.

Fix is always available.

What it does#

Checks for over-indented section underlines in docstrings.

Why is this bad?#

Multi-line docstrings are typically composed of a summary line, followed by a blank line, followed by a series of sections, each with a section header and a section body.

Some docstring formats (like reStructuredText) use underlines to separate section bodies from section headers.

Avoid over-indenting the section underlines, as this can cause syntax errors in reStructuredText.

This rule is enabled when using the numpy convention, and disabled when using the google or pep257 conventions.

Example#

def calculate_speed(distance: float, time: float) -> float:
    """Calculate speed as distance divided by time.

    Parameters
        ----------
    distance : float
        Distance traveled.
    time : float
        Time spent traveling.

    Returns
    -------
    float
        Speed as distance divided by time.

    Raises
    ------
    FasterThanLightError
        If speed is greater than the speed of light.
    """
    try:
        return distance / time
    except ZeroDivisionError as exc:
        raise FasterThanLightError from exc

Use instead: 

def calculate_speed(distance: float, time: float) -> float:
    """Calculate speed as distance divided by time.

    Parameters
    ----------
    distance : float
        Distance traveled.
    time : float
        Time spent traveling.

    Returns
    -------
    float
        Speed as distance divided by time.

    Raises
    ------
    FasterThanLightError
        If speed is greater than the speed of light.
    """
    try:
        return distance / time
    except ZeroDivisionError as exc:
        raise FasterThanLightError from exc

Options#

References#