MAINT: Add script for numpydoc linting of Public API #11121
+174
−0
Conversation
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
VeckoTheGecko
commented
Feb 2, 2026
| ROOT_PACKAGE = "xarray" | ||
|
|
||
| # full list of numpydoc error codes: https://numpydoc.readthedocs.io/en/latest/validation.html | ||
| SKIP_ERRORS = [ # TODO: Curate these for Xarray |
Contributor
Author
There was a problem hiding this comment.
These error code skips have mostly been inherited from my work on Parcels. These can be updated (though would be good to have input from core devs here)
Contributor
Author
There was a problem hiding this comment.
is doc a good place for this script?
1 task
VeckoTheGecko
commented
Feb 2, 2026
| try: | ||
| res = validate(item) | ||
| except (AttributeError, StopIteration, ValueError) as e: | ||
| if isinstance(e, ValueError) and "Error parsing See Also entry" in str(e): # TODO: Fix later https://github.com/pydata/xarray/issues/8596#issuecomment-3832443795 |
Contributor
Author
There was a problem hiding this comment.
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.
I realised that there isn't any(?) linting of docstrings to make sure they adhere to the numpydoc style guide.
This PR adds a script and Pixi integration to quickly lint public docstrings. This is a similar script to that introduced in Scipy (scipy/scipy#24317 ) - though I wrote my own version which I think is a bit more robust in finding all the methods :) .
Note that numpydoc does have validation out of the box however this is on a file level, and not on the public API level (this applies to the CLI tool, pre-commit hook, and for numpydoc's integration in Sphinx - all are on the file level) - hence our need for this script.
I've used this script to find a heap of minor typos in the docs which I'll wrap into another PR.
I don't know if we can integrate this into a pre-commit hook as it requires building xarray.