Docstring Style Scanner

Build a focused docstring style checker that enforces whitespace, formatting, quote usage, and punctuation rules for Python docstrings. The checker should rely on the dependency to evaluate only the D2xx–D4xx rule family and present results through a callable API and a CLI entry point.

Capabilities

Focused whitespace and punctuation linting

• Scanning a file with a docstring missing a terminal period reports a violation with its line number, while missing-docstring issues are not reported because only whitespace/formatting/quote/punctuation rules are enforced. @test
• Selecting an alternative convention (e.g., Google) still applies the whitespace/formatting/quote/punctuation checks and reports summary punctuation issues when present. @test

Inline suppression toggle

• Inline # noqa: D4xx comments suppress the corresponding violation when honor_noqa=True. @test
• Suppression is ignored when honor_noqa=False, so the same violation is emitted. @test

Output customization

• When include_source=True, each violation output includes the offending docstring lines beneath the message. @test
• When include_count=True, the scan appends the total number of whitespace/formatting/quote/punctuation violations after the detailed messages. @test

Implementation

@generates

API

from typing import Sequence

def run_docstring_style_scan(
    paths: Sequence[str],
    *,
    convention: str | None = None,
    honor_noqa: bool = True,
    include_source: bool = False,
    include_explanations: bool = True,
    include_count: bool = False,
) -> list[str]:
    """Return formatted violation messages for whitespace/formatting/quote/punctuation docstring rules (D2xx–D4xx) only."""


def main(argv: Sequence[str] | None = None) -> int:
    """CLI entry that accepts paths plus flags (--convention, --no-noqa, --source, --no-explain, --count) and exits 0 when clean, 1 when violations are found, and 2 on invalid options."""

Dependencies { .dependencies }

pydocstyle { .dependency }

Docstring style checker providing whitespace, formatting, quote, and punctuation validation for the D2xx–D4xx rule family.