empty-section (PDF406)¶

Part of the PDF rule category.

View source · View documentation source · Search issues

Fix is not available.

Rule is disabled if docstring-convention is none or pep257.

What it does¶

PDF406 reports recognized Google and NumPy sections, plus reST fields under the reST convention, that contain no meaningful body content after their header or field marker. Header-only sections, sections containing only blank lines, and empty reST fields are findings.

Any non-blank section body content counts as content, including entries, prose, doctests, code fences, lists, block quotes, directives, literal blocks, tables, reST-looking text, and verbatim blocks. The rule is diagnostic-only and leaves source unchanged.

Why is this useful?¶

Empty sections imply documentation exists where readers will find none.

Ruff compatibility¶

This rule is intended to replace Ruff's D414.

Examples¶

PDF406 reports empty Google sections:

docstring-convention = "google"

def value(arg):
    """Return the value.

    Args:
    """

PDF406: Line 4: Docstring section 'Args' should not be empty

Adjacent header-only sections are separate findings:

docstring-convention = "google"

def value(arg):
    """Return the value.

    Args:
    Returns:
    """

PDF406: Line 4: Docstring section 'Args' should not be empty
PDF406: Line 5: Docstring section 'Returns' should not be empty

NumPy sections are checked after their underline:

docstring-convention = "numpy"

def value(arg):
    """Return the value.

    Parameters
    ----------
    """

PDF406: Line 4: Docstring section 'Parameters' should not be empty

Any non-blank section body counts as content, including protected or structured content:

docstring-convention = "google"

def example():
    """Show an example.

    Examples:
        ```python
        example()
        ```

    Args:
        :param value: Ordinary section body content also counts.
    """

Empty reST fields are checked under the reST convention:

docstring-convention = "rest"

def value(arg):
    """Return the value.

    :param arg:
    :returns: The value.
    """

PDF406: Line 4: Docstring field ':param arg:' should not be empty

Section-like text is ignored when section parsing is disabled:

docstring-convention = "none"

def value(arg):
    """Return the value.

    Args:
    """

Options¶

None.