Docstring Validation Gate

Build a small utility that runs docstring style validation with error codes, reports results, and hooks into a documentation build to stop on configured failures.

Capabilities

Validate modules for error codes

• Running validation on a module with a short summary missing punctuation and an undocumented return value yields codes such as GL08 and RT02, and the results include the fully qualified object name plus line numbers. @test
• When the caller provides an ignore list containing GL08, that code is filtered out of the results while other codes (for example, RT02) remain. @test

Honor inline ignores

• A docstring that contains an inline ignore marker like numpydoc ignore=GL08,RT02 suppresses those codes, but unrelated codes (for example, SS01) are still reported. @test

Sphinx build hook

• Registering the validation hook on a Sphinx app emits warnings for codes outside fail_on, and raises a build error when any code in fail_on is present. @test

Summary report

• The summary helper aggregates counts per error code, lists failing objects, and returns an overall status of failed when any fail_on code is found and passed otherwise. @test

Implementation

@generates

API

from typing import Iterable, Mapping

def validate_modules(module_paths: Iterable[str], ignore: list[str] | None = None, fail_on: list[str] | None = None) -> dict[str, list[dict]]:
    """Run docstring validation for each module path and return structured results with codes, messages, and line numbers."""

def summarize_results(results: Mapping[str, list[dict]], fail_on: list[str] | None = None) -> dict[str, object]:
    """Return aggregate counts per error code, ordered list of failing objects, and overall status string."""

def register_sphinx(app, fail_on: list[str] | None = None, warn_on: list[str] | None = None) -> None:
    """Attach validation to a Sphinx app so builds warn or fail based on validation codes."""

Dependencies { .dependencies }

numpydoc { .dependency }

Docstring parsing, rendering, and validation with error code reporting.

sphinx { .dependency }

Documentation builder that hosts the validation hook.