Skip to content

Commit 54e5803

Browse files
albertvillanovagfyoung
authored andcommitted
DOC: Validate docstring directives (#27630)
Closes gh-27629
1 parent 640d9e1 commit 54e5803

File tree

3 files changed

+43
-3
lines changed

3 files changed

+43
-3
lines changed

ci/code_checks.sh

+2-2
Original file line numberDiff line numberDiff line change
@@ -263,8 +263,8 @@ fi
263263
### DOCSTRINGS ###
264264
if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
265265

266-
MSG='Validate docstrings (GL03, GL04, GL05, GL06, GL07, GL09, SS04, SS05, PR03, PR04, PR05, PR10, EX04, RT01, RT04, RT05, SA05)' ; echo $MSG
267-
$BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL03,GL04,GL05,GL06,GL07,GL09,SS04,SS05,PR03,PR04,PR05,PR10,EX04,RT01,RT04,RT05,SA05
266+
MSG='Validate docstrings (GL03, GL04, GL05, GL06, GL07, GL09, GL10, SS04, SS05, PR03, PR04, PR05, PR10, EX04, RT01, RT04, RT05, SA05)' ; echo $MSG
267+
$BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL03,GL04,GL05,GL06,GL07,GL09,GL10,SS04,SS05,PR03,PR04,PR05,PR10,EX04,RT01,RT04,RT05,SA05
268268
RET=$(($RET + $?)) ; echo $MSG "DONE"
269269

270270
fi

scripts/tests/test_validate_docstrings.py

+31-1
Original file line numberDiff line numberDiff line change
@@ -200,7 +200,7 @@ def contains(self, pat, case=True, na=np.nan):
200200

201201
def mode(self, axis, numeric_only):
202202
"""
203-
Ensure sphinx directives don't affect checks for trailing periods.
203+
Ensure reST directives don't affect checks for leading periods.
204204
205205
Parameters
206206
----------
@@ -447,6 +447,27 @@ def deprecation_in_wrong_order(self):
447447
def method_wo_docstrings(self):
448448
pass
449449

450+
def directives_without_two_colons(self, first, second):
451+
"""
452+
Ensure reST directives have trailing colons.
453+
454+
Parameters
455+
----------
456+
first : str
457+
Sentence ending in period, followed by single directive w/o colons.
458+
459+
.. versionchanged 0.1.2
460+
461+
second : bool
462+
Sentence ending in period, followed by multiple directives w/o
463+
colons.
464+
465+
.. versionadded 0.1.2
466+
.. deprecated 0.00.0
467+
468+
"""
469+
pass
470+
450471

451472
class BadSummaries:
452473
def wrong_line(self):
@@ -840,6 +861,7 @@ def test_bad_class(self, capsys):
840861
"plot",
841862
"method",
842863
"private_classes",
864+
"directives_without_two_colons",
843865
],
844866
)
845867
def test_bad_generic_functions(self, capsys, func):
@@ -879,6 +901,14 @@ def test_bad_generic_functions(self, capsys, func):
879901
"deprecation_in_wrong_order",
880902
("Deprecation warning should precede extended summary",),
881903
),
904+
(
905+
"BadGenericDocStrings",
906+
"directives_without_two_colons",
907+
(
908+
"reST directives ['versionchanged', 'versionadded', "
909+
"'deprecated'] must be followed by two colons",
910+
),
911+
),
882912
(
883913
"BadSeeAlso",
884914
"desc_no_period",

scripts/validate_docstrings.py

+10
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959

6060
PRIVATE_CLASSES = ["NDFrame", "IndexOpsMixin"]
6161
DIRECTIVES = ["versionadded", "versionchanged", "deprecated"]
62+
DIRECTIVE_PATTERN = re.compile(rf"^\s*\.\. ({'|'.join(DIRECTIVES)})(?!::)", re.I | re.M)
6263
ALLOWED_SECTIONS = [
6364
"Parameters",
6465
"Attributes",
@@ -93,6 +94,7 @@
9394
"GL07": "Sections are in the wrong order. Correct order is: " "{correct_sections}",
9495
"GL08": "The object does not have a docstring",
9596
"GL09": "Deprecation warning should precede extended summary",
97+
"GL10": "reST directives {directives} must be followed by two colons",
9698
"SS01": "No summary found (a short summary in a single line should be "
9799
"present at the beginning of the docstring)",
98100
"SS02": "Summary does not start with a capital letter",
@@ -478,6 +480,10 @@ def parameter_mismatches(self):
478480
def correct_parameters(self):
479481
return not bool(self.parameter_mismatches)
480482

483+
@property
484+
def directives_without_two_colons(self):
485+
return DIRECTIVE_PATTERN.findall(self.raw_doc)
486+
481487
def parameter_type(self, param):
482488
return self.doc_parameters[param][0]
483489

@@ -697,6 +703,10 @@ def get_validation_data(doc):
697703
if doc.deprecated and not doc.extended_summary.startswith(".. deprecated:: "):
698704
errs.append(error("GL09"))
699705

706+
directives_without_two_colons = doc.directives_without_two_colons
707+
if directives_without_two_colons:
708+
errs.append(error("GL10", directives=directives_without_two_colons))
709+
700710
if not doc.summary:
701711
errs.append(error("SS01"))
702712
else:

0 commit comments

Comments
 (0)