diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 27c63e3ba3a79..8ebf4299edca4 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -334,6 +334,33 @@ def method(self, foo=None, bar=None): pass +class BadSeeAlso(object): + + def desc_no_period(self): + """ + Return the first 5 elements of the Series. + + See Also + -------- + Series.tail : Return the last 5 elements of the Series. + Series.iloc : Return a slice of the elements in the Series, + which can also be used to return the first or last n + """ + pass + + def desc_first_letter_lowercase(self): + """ + Return the first 5 elements of the Series. + + See Also + -------- + Series.tail : return the last 5 elements of the Series. + Series.iloc : Return a slice of the elements in the Series, + which can also be used to return the first or last n. + """ + pass + + class BadSummaries(object): def wrong_line(self): @@ -564,6 +591,11 @@ def test_bad_generic_functions(self, func): assert errors @pytest.mark.parametrize("klass,func,msgs", [ + # See Also tests + ('BadSeeAlso', 'desc_no_period', + ('Missing period at end of description for See Also "Series.iloc"',)), + ('BadSeeAlso', 'desc_first_letter_lowercase', + ('should be capitalized for See Also "Series.tail"',)), # Summary tests ('BadSummaries', 'wrong_line', ('should start in the line immediately after the opening quotes',)), diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 6588522331433..a492a95b79bf9 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -496,7 +496,14 @@ def validate_one(func_name): wrns.append('See Also section not found') else: for rel_name, rel_desc in doc.see_also.items(): - if not rel_desc: + if rel_desc: + if not rel_desc.endswith('.'): + errs.append('Missing period at end of description for ' + 'See Also "{}" reference'.format(rel_name)) + if not rel_desc[0].isupper(): + errs.append('Description should be capitalized for ' + 'See Also "{}" reference'.format(rel_name)) + else: errs.append('Missing description for ' 'See Also "{}" reference'.format(rel_name))