From 2755055e98cced1a928181f1ad2193557977eb4d Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Sat, 13 Oct 2018 21:45:57 -0400 Subject: [PATCH 1/6] Add docstring validations for "See Also" section --- scripts/tests/test_validate_docstrings.py | 30 +++++++++++++++++++++++ scripts/validate_docstrings.py | 6 +++++ 2 files changed, 36 insertions(+) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 27c63e3ba3a79..891dcf2f5277a 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_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,9 @@ 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',)), + ('BadSeeAlso', 'desc_lowercase', ('should be capitalized',)), # 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..1d553ee32e8c7 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -499,6 +499,12 @@ def validate_one(func_name): if not rel_desc: errs.append('Missing description for ' 'See Also "{}" reference'.format(rel_name)) + if not rel_desc.endswith('.'): + errs.append('Missing period at end of description' + 'See Also "{}" reference'.format(rel_name)) + if not rel_desc[0].isupper(): + errs.append('Description should be capitalized' + 'See Also "{}" reference'.format(rel_name)) for line in doc.raw_doc.splitlines(): if re.match("^ *\t", line): From 09ec596568b3738ffe70f35fb9bd43176984fe14 Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Sat, 13 Oct 2018 21:48:32 -0400 Subject: [PATCH 2/6] Make docstring validation test name more descriptive --- scripts/tests/test_validate_docstrings.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 891dcf2f5277a..bb9e36cd73e7a 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -348,7 +348,7 @@ def desc_no_period(self): """ pass - def desc_lowercase(self): + def desc_first_letter_lowercase(self): """ Return the first 5 elements of the Series. @@ -593,7 +593,7 @@ def test_bad_generic_functions(self, func): @pytest.mark.parametrize("klass,func,msgs", [ # See Also tests ('BadSeeAlso', 'desc_no_period', ('Missing period at end of description',)), - ('BadSeeAlso', 'desc_lowercase', ('should be capitalized',)), + ('BadSeeAlso', 'desc_first_letter_lowercase', ('should be capitalized',)), # Summary tests ('BadSummaries', 'wrong_line', ('should start in the line immediately after the opening quotes',)), From d3313cd9e4a4c0f3a3c648233b22ecea1e2b4afe Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Sat, 13 Oct 2018 21:50:44 -0400 Subject: [PATCH 3/6] Fix flake error: line too long --- scripts/tests/test_validate_docstrings.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index bb9e36cd73e7a..519cfb94149db 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -592,8 +592,10 @@ def test_bad_generic_functions(self, func): @pytest.mark.parametrize("klass,func,msgs", [ # See Also tests - ('BadSeeAlso', 'desc_no_period', ('Missing period at end of description',)), - ('BadSeeAlso', 'desc_first_letter_lowercase', ('should be capitalized',)), + ('BadSeeAlso', 'desc_no_period', + ('Missing period at end of description',)), + ('BadSeeAlso', 'desc_first_letter_lowercase', + ('should be capitalized',)), # Summary tests ('BadSummaries', 'wrong_line', ('should start in the line immediately after the opening quotes',)), From 1fabcad58a90a91645722b6ea01d464c9be0f7a7 Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Sat, 13 Oct 2018 22:06:40 -0400 Subject: [PATCH 4/6] Fix for blank/missing doc string --- scripts/validate_docstrings.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 1d553ee32e8c7..f12c6d3859046 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -496,15 +496,17 @@ 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' + 'See Also "{}" reference'.format(rel_name)) + if not rel_desc[0].isupper(): + errs.append('Description should be capitalized' + 'See Also "{}" reference'.format(rel_name)) + else: errs.append('Missing description for ' 'See Also "{}" reference'.format(rel_name)) - if not rel_desc.endswith('.'): - errs.append('Missing period at end of description' - 'See Also "{}" reference'.format(rel_name)) - if not rel_desc[0].isupper(): - errs.append('Description should be capitalized' - 'See Also "{}" reference'.format(rel_name)) + for line in doc.raw_doc.splitlines(): if re.match("^ *\t", line): From 067dad835162a8a31e9540a44d5bb14cb233a07a Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Sat, 13 Oct 2018 22:34:08 -0400 Subject: [PATCH 5/6] Cleanup error string format --- scripts/validate_docstrings.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index f12c6d3859046..3e3837e11682f 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -498,10 +498,10 @@ def validate_one(func_name): for rel_name, rel_desc in doc.see_also.items(): if rel_desc: if not rel_desc.endswith('.'): - errs.append('Missing period at end of description' + 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' + errs.append('Description should be capitalized for ' 'See Also "{}" reference'.format(rel_name)) else: errs.append('Missing description for ' From 6901171527f43cdefbe65bb8e12725c225addddd Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Sun, 14 Oct 2018 12:06:50 -0400 Subject: [PATCH 6/6] CR feedback: make doc string validation tests more specific about location of error --- scripts/tests/test_validate_docstrings.py | 6 +++--- scripts/validate_docstrings.py | 1 - 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 519cfb94149db..8ebf4299edca4 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -352,7 +352,7 @@ def desc_first_letter_lowercase(self): """ Return the first 5 elements of the Series. - see Also + See Also -------- Series.tail : return the last 5 elements of the Series. Series.iloc : Return a slice of the elements in the Series, @@ -593,9 +593,9 @@ def test_bad_generic_functions(self, func): @pytest.mark.parametrize("klass,func,msgs", [ # See Also tests ('BadSeeAlso', 'desc_no_period', - ('Missing period at end of description',)), + ('Missing period at end of description for See Also "Series.iloc"',)), ('BadSeeAlso', 'desc_first_letter_lowercase', - ('should be capitalized',)), + ('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 3e3837e11682f..a492a95b79bf9 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -507,7 +507,6 @@ def validate_one(func_name): errs.append('Missing description for ' 'See Also "{}" reference'.format(rel_name)) - for line in doc.raw_doc.splitlines(): if re.match("^ *\t", line): errs.append('Tabs found at the start of line "{}", '