Context
numpydoc-validation is currently configured (in pyproject.toml) to enforce only PR01 and PR02, and only on .plot methods (negative-lookahead exclude). That narrow scope was intentional for #886, but the hook can do considerably more across the whole causalpy/ tree.
[tool.numpydoc_validation]
checks = [
"PR01", # Parameters not documented
"PR02", # Unknown parameters
]
exclude = ['^(?!.*\.plot$).*$']While addressing #892 it became clear that numpydoc-validation cannot catch the body-level rendering bug we hit there (it doesn't inspect section bodies), but it can catch a number of other defects that currently slip through.
Proposed change
Expand the configured checks to a curated set, then drop the .plot-only exclude so the rules apply package-wide. Candidate rules to add (each can be landed independently to keep the noise manageable):
PR04 parameter has no typePR07 parameter has no descriptionPR10 parameter requires a space before the colonRT03 return value has no descriptionSS03 summary does not end with a periodGL07 sections in wrong orderGL08 object does not have a docstring (note overlap with interrogate; decide whether to keep one or both)
Other rules (SS05 infinitive verb, RT01 no Returns section, EX01 / SA01 / ES01) are likely too noisy to enable globally and should be considered case by case.
Acceptance criteria
Out of scope
Related
Context
numpydoc-validationis currently configured (inpyproject.toml) to enforce onlyPR01andPR02, and only on.plotmethods (negative-lookahead exclude). That narrow scope was intentional for #886, but the hook can do considerably more across the wholecausalpy/tree.While addressing #892 it became clear that
numpydoc-validationcannot catch the body-level rendering bug we hit there (it doesn't inspect section bodies), but it can catch a number of other defects that currently slip through.Proposed change
Expand the configured checks to a curated set, then drop the
.plot-only exclude so the rules apply package-wide. Candidate rules to add (each can be landed independently to keep the noise manageable):PR04parameter has no typePR07parameter has no descriptionPR10parameter requires a space before the colonRT03return value has no descriptionSS03summary does not end with a periodGL07sections in wrong orderGL08object does not have a docstring (note overlap withinterrogate; decide whether to keep one or both)Other rules (
SS05infinitive verb,RT01no Returns section,EX01/SA01/ES01) are likely too noisy to enable globally and should be considered case by case.Acceptance criteria
pyproject.tomlis updated and documented.Out of scope
validate-docstring-listspre-commit hook added under API docs: Returns blocks with inline lists render as a wall of prose #892).BaseExperiment.plotcarve-out (that lives under Make plot() args and kwargs visible in API docs (umbrella) #886).Related