Feature: NumPy-style section recognition (`Notes`, `References`, `Warnings`)

[Alberto-Codes]

Problem Statement

NumPy/SciPy style is the standard for the scientific Python ecosystem: numpy, scipy, pandas, scikit-learn, matplotlib, xarray, astropy, and hundreds of domain-specific libraries. Napoleon (Sphinx extension) recognizes it natively.

NumPy defines 15 sections, of which docvet currently recognizes 10 (the ones shared with Google style). The 5 unrecognized sections cause section-boundary parsing issues — content under Notes may bleed into the previous section during _extract_section_content.

Current Behavior

Section	Purpose	Recognized by docvet?
Notes	Algorithm details, mathematical background	❌ No
References	Academic citations	❌ No
Warnings	Free-text cautions (NOT warnings.warn)	❌ No
Extended Summary	Longer description after one-line summary	❌ No
Methods	Class method listing (rare)	❌ No

The Notes section is significant

Scientific libraries use Notes to document mathematical formulas (LaTeX), algorithm complexity, implementation details, numerical stability, and comparison with alternatives.

Example from numpy:

def fft(a, n=None, axis=-1, norm=None):
    """Compute the one-dimensional discrete Fourier Transform.

    Parameters
    ----------
    a : array_like
        Input array, can be complex.

    Returns
    -------
    complex ndarray
        The truncated or zero-padded input.

    Notes
    -----
    FFT (Fast Fourier Transform) refers to a way the discrete
    Fourier Transform (DFT) can be calculated efficiently, by
    using symmetries in the calculated terms.

    References
    ----------
    .. [1] Cooley, James W., and John W. Tukey, 1965, "An algorithm
           for the machine calculation of complex Fourier series,"
           Math. Comput. 19: 297-301.
    """

Proposed Solution

Phase 1: Recognition only (no enforcement)

Add Notes, References, Warnings, Extended Summary, and Methods to recognized section headers. This prevents content bleed in section-boundary parsing.

_SECTION_HEADERS = frozenset({
    # Existing
    "Args", "Returns", "Raises", "Yields", "Receives",
    "Warns", "Other Parameters", "Attributes", "Examples", "See Also",
    # New: NumPy sections
    "Notes", "References", "Warnings", "Extended Summary",
    # Napoleon aliases
    "Parameters", "Keyword Args", "Keyword Arguments", "Methods",
})

NumPy underline format detection

NumPy uses underline-delimited sections:

Parameters
----------
x : type
    The input.

Parser should detect both Google colon-style and NumPy underline-style:

_NUMPY_SECTION_PATTERN = re.compile(
    r"^\s*(Parameters|Returns|Raises|Yields|Notes|References"
    r"|Warnings|Extended Summary|Methods|Keyword Args)"
    r"\s*\n\s*-{3,}\s*$",
    re.MULTILINE,
)

Phase 2 (future): Optional enforcement

[tool.docvet.enrichment]
require-notes = ["class"]        # off by default
require-references = false       # off by default

Lower priority — not part of initial implementation.

Acceptance Criteria

• Notes, References, Warnings, Extended Summary recognized as section headers
• Section-boundary parsing stops at these new headers (no content bleed)
• NumPy underline format detected alongside Google colon format
• Napoleon aliases (Parameters, Keyword Args, etc.) recognized
• No new findings produced (recognition only in Phase 1)

Technical Notes

Phase 1 sizing: enrichment.py (~15 lines), tests (~20 lines). No new dependencies.

Category: N/A for Phase 1 (no new findings). Phase 2 rules: recommended.

Relationship to Sphinx/RST style support: When docstring-style = "numpy" is eventually supported, section detection uses underline format, Parameters recognized instead of Args, and griffe uses docstring_parser="numpy". Phase 1 can land independently.

---

BMAD Workflow

When ready to implement:

• /bmad-bmm-quick-spec -> /bmad-bmm-quick-dev

[Alberto-Codes]

Shipped in #344 (commit 62ce6ed). Implementation lives in src/docvet/checks/enrichment/__init__.py — _NUMPY_UNDERLINE_PATTERN regex and NumPy-aware section parsing in parse_docstring_sections.