section-underline-after-name (D408)#
Derived from the pydocstyle linter.
Fix is always available.
What it does#
Checks for section underlines in docstrings that are not on the line immediately following the section name.
Why is this bad?#
This rule enforces a consistent style for multiline numpy-style docstrings, and helps prevent incorrect syntax in docstrings using reStructuredText.
Multiline numpy-style docstrings are typically composed of a summary line, followed by a blank line, followed by a series of sections. Each section has a header and a body. There should be a series of underline characters in the line immediately below the header.
This rule enforces a consistent style for multiline numpy-style docstrings with sections. If your docstring uses reStructuredText, the rule also helps protect against incorrect reStructuredText syntax, which would cause errors if you tried to use a tool such as Sphinx to generate documentation from the docstring.
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