Skip to content

DOC: Validate docstring directives #27630

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.

Sign up for GitHub

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

Merged
merged 9 commits into from
Aug 6, 2019
Merged

DOC: Validate docstring directives #27630

Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
e1f3606
Validate docstring directives
albertvillanova Jul 28, 2019
5892904
Fix linting
albertvillanova Jul 28, 2019
2e8c76f
Merge branch 'master' into fix-validate-docstrings-directives
albertvillanova Aug 5, 2019
ae3f03d
Remove duplicated DIRECTIVES
albertvillanova Aug 5, 2019
caed8d9
Rename regex DIRECTIVE_PATTERN
albertvillanova Aug 5, 2019
1162735
Add GL10 to code_checks
albertvillanova Aug 5, 2019
900f75e
Add tests for validate_docstrings
albertvillanova Aug 5, 2019
fd2fa5a
fix linting
albertvillanova Aug 5, 2019
e25a769
Fix regex DIRECTIVE_PATTERN
albertvillanova Aug 5, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions scripts/validate_docstrings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@
"GL07": "Sections are in the wrong order. Correct order is: " "{correct_sections}",
"GL08": "The object does not have a docstring",
"GL09": "Deprecation warning should precede extended summary",
"GL10": "reST directives {directives} must be followed by two colons",
"SS01": "No summary found (a short summary in a single line should be "
"present at the beginning of the docstring)",
"SS02": "Summary does not start with a capital letter",
Expand Down Expand Up @@ -239,6 +240,11 @@ def get_api_items(api_doc_fd):


class Docstring:
DIRECTIVES = ["deprecated", "versionadded", "versionchanged"]
DIRECTIVE_WITHOUT_TWO_COLONS = re.compile(
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. We should rename this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it OK as DIRECTIVE_PATTERN?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds good to me

rf"^\s*.. ({'|'.join(DIRECTIVES)})(?!::)", re.I | re.M
)

def __init__(self, name):
self.name = name
obj = self._load_obj(name)
Expand Down Expand Up @@ -478,6 +484,10 @@ def parameter_mismatches(self):
def correct_parameters(self):
return not bool(self.parameter_mismatches)

@property
def directives_without_two_colons(self):
return Docstring.DIRECTIVE_WITHOUT_TWO_COLONS.findall(self.raw_doc)

def parameter_type(self, param):
return self.doc_parameters[param][0]

Expand Down Expand Up @@ -697,6 +707,10 @@ def get_validation_data(doc):
if doc.deprecated and not doc.extended_summary.startswith(".. deprecated:: "):
errs.append(error("GL09"))

directives_without_two_colons = doc.directives_without_two_colons
if directives_without_two_colons:
errs.append(error("GL10", directives=directives_without_two_colons))

if not doc.summary:
errs.append(error("SS01"))
else:
Expand Down