-
-
Notifications
You must be signed in to change notification settings - Fork 161
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Pre-commit hook for running numpydoc validation #454
Merged
Merged
Changes from all commits
Commits
Show all changes
35 commits
Select commit
Hold shift + click to select a range
6e3b468
Add numpydoc.hooks directory.
stefmolin 6d5b54e
Add numpydoc.hooks to packages.
stefmolin 3d4ba71
Add tabulate dependency for use in validate hook.
stefmolin 2b0a962
Add option to pass a Validator class to validate() function.
stefmolin ed9ba3c
Add AST-based validation logic to review files.
stefmolin fb53cee
Add entry point for validation hook.
stefmolin c18c990
Add pre-commit hook configuration.
stefmolin f7df258
Add SS05 match pattern for allowed verbs; add some type annotations.
stefmolin ee49b0d
Add config option to override GL08 by name.
stefmolin 2409e43
Add option specify a path to a config file.
stefmolin a4fdc71
Add information on the hook to the docs.
stefmolin 749feee
Grab arg name off ast arg nodes for *args/**kwargs; don't alter filep…
stefmolin 8f4457b
Update spacing in example.
stefmolin 34061f3
Reduce maxcolwidths in report of findings by hook.
stefmolin 056bcd8
Show file in a separate column of the findings; item is from module o…
stefmolin 56f6320
Update example in docs for new column.
stefmolin 26ac09e
Update example in docs for new column.
stefmolin 5d9584d
Switch to a stack for visiting.
stefmolin afa2509
Add line to file column; show module lineno as 1.
stefmolin cead4ae
Expand user on config file path.
stefmolin 195d35b
Use Path operations.
stefmolin 9d73d6a
Add support for using inline comments to ignore specific checks.
stefmolin 8e59535
Add support for comments at the end of a multiline declaration.
stefmolin 629c65c
Add a note on inline option to docs.
stefmolin 405affb
Simplify check for the declaration start.
stefmolin e2e42ba
Add support for reading hook config from pyproject.toml
stefmolin 4e0707b
Add some initial tests for the validate hook.
stefmolin 97fc2dd
Tweak docstring.
stefmolin 223ed2d
Add tests for hook using config files.
stefmolin f4663d3
Add finding of project root.
stefmolin 583b6b1
Update link in docstring.
stefmolin 281c04d
Tweak code blocks in docs.
stefmolin 09281fd
Merge branch 'main' into ast-validate-hook
stefmolin 6a1a606
Shorten table to avoid scroll in docs.
stefmolin 262dbef
Merge branch 'main' into ast-validate-hook
stefmolin File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
- id: numpydoc-validation | ||
name: numpydoc-validation | ||
description: This hook validates that docstrings in committed files adhere to numpydoc standards. | ||
entry: validate-docstrings | ||
require_serial: true | ||
language: python | ||
types: [python] |
This file contains 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
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,6 +2,83 @@ | |
Validation | ||
========== | ||
|
||
Docstring Validation using Pre-Commit Hook | ||
------------------------------------------ | ||
|
||
To enable validation of docstrings as you commit files, add the | ||
following to your ``.pre-commit-config.yaml`` file: | ||
|
||
.. code-block:: yaml | ||
|
||
- repo: https://github.com/numpy/numpydoc | ||
rev: <version> | ||
hooks: | ||
- id: numpydoc-validation | ||
|
||
After installing ``numpydoc``, run the following to see available | ||
command line options for this hook: | ||
|
||
.. code-block:: bash | ||
|
||
$ python -m numpydoc.hooks.validate_docstrings --help | ||
|
||
Using a config file provides additional customization. Both | ||
``pyproject.toml`` and ``setup.cfg`` are supported; however, if the | ||
project contains both you must use the ``pyproject.toml`` file. | ||
The example below configures the pre-commit hook to ignore three checks | ||
and specifies exceptions to the checks ``SS05`` (allow docstrings to | ||
start with "Process ", "Assess ", or "Access ") and ``GL08`` (allow | ||
the class/method/function with name "__init__" to not have a docstring). | ||
|
||
``pyproject.toml``:: | ||
|
||
[tool.numpydoc_validation] | ||
ignore = [ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Loving this! |
||
"EX01", | ||
"SA01", | ||
"ES01", | ||
] | ||
override_SS05 = '^((Process|Assess|Access) )' | ||
override_GL08 = '^(__init__)$' | ||
|
||
``setup.cfg``:: | ||
|
||
[tool:numpydoc_validation] | ||
ignore = EX01,SA01,ES01 | ||
override_SS05 = ^((Process|Assess|Access) ) | ||
override_GL08 = ^(__init__)$ | ||
|
||
For more fine-tuned control, you can also include inline comments to tell the | ||
validation hook to ignore certain checks: | ||
|
||
.. code-block:: python | ||
|
||
class SomeClass: # numpydoc ignore=EX01,SA01,ES01 | ||
"""This is the docstring for SomeClass.""" | ||
|
||
def __init__(self): # numpydoc ignore=GL08 | ||
pass | ||
|
||
If any issues are found when commiting, a report is printed out and the | ||
commit is halted: | ||
|
||
.. code-block:: output | ||
|
||
numpydoc-validation......................................................Failed | ||
- hook id: numpydoc-validation | ||
- exit code: 1 | ||
|
||
+----------------------+----------------------+---------+--------------------------------------+ | ||
| file | item | check | description | | ||
+======================+======================+=========+======================================+ | ||
| src/pkg/utils.py:1 | utils | GL08 | The object does not have a docstring | | ||
| src/pkg/utils.py:90 | utils.normalize | PR04 | Parameter "field" has no type | | ||
| src/pkg/module.py:12 | module.MyClass | GL08 | The object does not have a docstring | | ||
| src/pkg/module.py:33 | module.MyClass.parse | RT03 | Return value has no description | | ||
+----------------------+----------------------+---------+--------------------------------------+ | ||
|
||
See below for a full listing of checks. | ||
|
||
Docstring Validation using Python | ||
--------------------------------- | ||
|
||
|
This file contains 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
"""Pre-commit hooks using numpydoc.""" |
This file contains 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,48 @@ | ||
"""Utility functions for pre-commit hooks.""" | ||
|
||
import itertools | ||
import os | ||
from pathlib import Path | ||
from typing import Sequence | ||
|
||
|
||
def find_project_root(srcs: Sequence[str]): | ||
""" | ||
Return a directory containing .git, .hg, pyproject.toml, or setup.cfg. | ||
|
||
That directory can be one of the directories passed in ``srcs`` or their | ||
common parent. If no directory in the tree contains a marker that would | ||
specify it's the project root, the root of the file system is returned. | ||
|
||
Parameters | ||
---------- | ||
srcs : Sequence[str] | ||
The filepaths to run the hook on. | ||
|
||
Returns | ||
------- | ||
str | ||
The project root directory. | ||
|
||
See Also | ||
-------- | ||
black.find_project_root : | ||
This function was adapted from | ||
`Black <https://github.com/psf/black/blob/main/src/black/files.py>`_. | ||
""" | ||
if not srcs: | ||
return Path(".").resolve(), "current directory" | ||
|
||
common_path = Path( | ||
os.path.commonpath([Path(src).expanduser().resolve() for src in srcs]) | ||
) | ||
|
||
for dir in itertools.chain([common_path], common_path.parents): | ||
if (dir / "pyproject.toml").is_file(): | ||
return dir, "pyproject.toml" | ||
if (dir / "setup.cfg").is_file(): | ||
return dir, "setup.cfg" | ||
if (dir / ".git").exists() or (dir / ".hg").is_dir(): | ||
return dir, "version control" | ||
|
||
return dir, "file system root" |
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is fine for now, but longer term I'm wondering if we shouldn't consolidate everything under
python -m numpydoc
, which currently has questionable semantics. E.g., to a new user this must be clear as mud:There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Indeed. I'm happy to work on this, but I think we first need to discuss whether we are comfortable changing this interface (for example, if we had subparsers to split up the current functionality and the new hook). Probably best to save this discussion for an issue dedicated to the topic though 😊