DOC: Validate docstring directives #27630
Conversation
|
For the moment, I have hardcoded the directives:
Nevertheless, I have noted there exist other directives used in pandas:
May I also include these? |
|
Any reviewer? ;) @gfyoung @datapythonista Thanks. |
albertvillanova
changed the title
There was a problem hiding this comment.
Good job, nice PR.
Just couple of comments. Also, can you please add unit tests for the new feature? And can you add GL10 to the list of docstring codes checked in ci/code_checks.sh. If there are failing cases and the CI is red, is ok, let's first see how is this working and if there are cases left, and then we see what we do.
I'm happy to add the other directives you mention (not sure if we have code-block in docstrings, but I think for warning and other can be useful to check. But we can do that in a follow up too.
Thanks!
scripts/validate_docstrings.py
Outdated
| @@ -239,6 +240,11 @@ def get_api_items(api_doc_fd): | |||
|
|
|||
|
|
|||
| class Docstring: | |||
| DIRECTIVES = ["deprecated", "versionadded", "versionchanged"] | |||
| DIRECTIVE_WITHOUT_TWO_COLONS = re.compile( | |||
There was a problem hiding this comment.
We define similar constants at the top of the file, I'd keep these two there.
I find the name DIRECTIVE_WITHOUT_TWO_COLONS a bit misleading. If I understand correctly it's the same exact directives than the previous, but as compile expression to detect them. I understand your reasoning for the name, and it may be the best option, but reading the two constants gives me the impression that it's a different set of directives.
There was a problem hiding this comment.
Is it OK as DIRECTIVE_PATTERN?
|
All in GREEN (I had already fixed the docstrings #27621). |
There was a problem hiding this comment.
Great job @albertvillanova, lgtm. Thanks for adding this, will be very useful.
|
Thanks @albertvillanova ! |
black pandasgit diff upstream/master -u -- "*.py" | flake8 --diff