Widen numpydoc-validation checks across causalpy#902
Open
drbenvincent wants to merge 8 commits into
Open
Conversation
Replace the ``.plot``-only exclude regex in ``[tool.numpydoc_validation]`` with a private-member exclude (``\\._``), and widen the pre-commit ``files`` pattern from ``^causalpy/experiments/.*\\.py$`` to ``^causalpy/(?!tests/|data/).*\\.py$`` so the existing ``PR01``/``PR02`` checks now apply package-wide. Document and fix every public-API ``PR01``/``PR02`` violation that surfaces under the new scope: convert remaining Sphinx ``:param:`` blocks to numpydoc ``Parameters`` sections, add missing ``**kwargs``/``*args`` rows, populate the protocol/check/maketables/skl helpers, and tidy a ``See Also`` entry in ``utils.py`` that previously broke the docstring parser. The simulated-data helpers under ``causalpy/data/`` are intentionally excluded for this round; they keep their didactic ``:param`` style. Co-authored-by: Cursor <cursoragent@cursor.com>
Add ``PR04`` to the numpydoc-validation check set so parameter rows missing a type are caught going forward. No code changes are required: every documented parameter under the package-wide scope already declares a type. Co-authored-by: Cursor <cursoragent@cursor.com>
Add ``PR07`` to the numpydoc-validation check set so undocumented parameter rows are caught going forward. No code changes are required: every parameter row under the package-wide scope already carries a description. Co-authored-by: Cursor <cursoragent@cursor.com>
Add ``PR10`` to the numpydoc-validation check set so parameter rows that omit a space before the type colon are caught going forward. No code changes are required: existing docstrings in the broadened scope already conform. Co-authored-by: Cursor <cursoragent@cursor.com>
Add ``RT03`` to the numpydoc-validation check set so undocumented return rows are caught going forward, and flesh out the bare ``CheckResult`` return entry on the ``Check`` protocol's ``run`` method (the only violation surfaced under the package-wide scope). Co-authored-by: Cursor <cursoragent@cursor.com>
Add ``SS03`` to the numpydoc-validation check set so first-line summaries that omit a trailing period are caught going forward, and update every docstring under the package-wide scope that previously violated the rule (mostly module-level docstrings and a handful of method summaries). Co-authored-by: Cursor <cursoragent@cursor.com>
Add ``GL07`` to the numpydoc-validation check set so out-of-order docstring sections are caught going forward. Reorder ``Examples``/``Notes``/``See Also`` blocks in ``InterruptedTimeSeries``, ``PiecewiseITS``, ``PyMCModel.priors_from_data``, and the variable-selection-prior classes (the latter previously used a non-standard singular ``Example`` heading), all to match numpydoc's canonical ordering. Co-authored-by: Cursor <cursoragent@cursor.com>
Add ``GL08`` (object has no docstring) to the numpydoc-validation check set so missing docstrings are caught the same way every other rule is, and retire the standalone ``interrogate`` hook now that ``numpydoc-validation`` covers the same ground (and more) for the public API. Concretely: - Drop the ``interrogate`` pre-commit hook, the ``[tool.interrogate]`` section in ``pyproject.toml``, the ``interrogate`` extras entries, the ``interrogate-badge`` workflow, the ``Makefile`` invocation, and the README badge. - Add a top-level package docstring in ``causalpy/__init__.py`` and flesh out abstract ``fit``/``build_model``/``calculate_cumulative_impact`` stubs that previously had no docstring. - Rename the nested ``plot_weights``/``make_hists`` helpers in ``InversePropensityWeighting._plot_weights_propensity`` to a leading underscore so they fall under the configured private exclude. Co-authored-by: Cursor <cursoragent@cursor.com>
github-actions
Bot
added
the
documentation
drbenvincent
changed the title
Collaborator
Author
|
bugbot run |
PR SummaryLow Risk Overview Replaces Updates many public APIs and protocols across Reviewed by Cursor Bugbot for commit 1f43013. Bugbot is set up for automated code reviews on this repo. Configure here. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #902 +/- ##
==========================================
- Coverage 94.74% 94.73% -0.02%
==========================================
Files 84 84
Lines 13131 13131
Branches 793 793
==========================================
- Hits 12441 12439 -2
- Misses 487 488 +1
- Partials 203 204 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Documentation build overview
214 files changed ·
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 1f43013. Configure here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #898.
Summary
numpydoc-validationpre-commit hook from the original.plot-only scope to the wholecausalpy/package (tests/anddata/excluded), and trade the.plot-only exclude regex for a private-member exclude (\._).PR04,PR07,PR10,RT03,SS03,GL07,GL08.interrogatehook withGL08(per the agreed-upon resolution of the overlap discussed in the issue): the pre-commit hook,[tool.interrogate]config, extras entries, theinterrogate-badgeworkflow, theMakefileinvocation, and the README badge are all removed.:param:blocks incausalpy/experiments/*to numpydocParameterssections, documenting forwarded*args/**kwargs, fleshing out protocol/check/maketables/skl helper docstrings, and tidying aSee Alsoentry inutils.pythat previously broke the docstring parser. Subsequent commits include only small, rule-scoped fixes.Commit-by-commit breakdown
PR01/PR02violations under the new scope.Check.run's return entry.Examples/Notes/See Alsoblocks inInterruptedTimeSeries,PiecewiseITS,PyMCModel.priors_from_data, and the variable-selection-prior classes (the latter previously used a non-standard singularExampleheading).interrogatehook plumbing; add a top-level package docstring and flesh out abstractfit/build_model/calculate_cumulative_impactstubs; rename two nested helpers inInversePropensityWeighting._plot_weights_propensityto_-prefixed names so they fall under the configured private exclude.Decisions / clarifications recorded in the issue thread
interrogate: replaceinterrogatewithGL08(single source of truth for missing-docstring enforcement). Allinterrogateconfig, extras, the badge workflow, and the README badge are removed.PR01/PR02cleanup), as suggested in the acceptance criteria.exclude = ['\._']so violations on internal helpers don't drown out the public-API signal. The simulated-data helpers incausalpy/data/are also excluded via the pre-commitfilesregex; they intentionally retain Sphinx:param:style for didactic clarity.Test plan
prek run --all-filespasses (every hook, includingnumpydoc-validation,mypy, ruff, codespell, PyMarkdown, blank-line-before-bullet-lists, environment.yml sync, etc.).python -c "import causalpy; print(causalpy.__doc__)"succeeds and now prints the new package docstring.pytest causalpy/tests/test_misc.py -x -qpasses.Made with Cursor