From a73ab815c385e38430c927b67b63d23b65ce37f2 Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Mon, 12 Nov 2018 15:03:43 -0500 Subject: [PATCH 1/5] DOC: Improve GL03 message re: blank lines at end of docstrings. re: issue #23632 --- scripts/validate_docstrings.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index ed84e58049cae..27a3055d07a50 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -64,7 +64,9 @@ 'in the docstring (do not close the quotes in the same line as ' 'the text, or leave a blank line between the last text and the ' 'quotes)', - 'GL03': 'Use only one blank line to separate sections or paragraphs', + 'GL03': 'Double line break found; please use only one blank line to ' + 'separate sections or paragraphs, and do not leave blank lines ' + 'at the end of docstrings', 'GL04': 'Private classes ({mentioned_private_classes}) should not be ' 'mentioned in public docstrings', 'GL05': 'Tabs found at the start of line "{line_with_tabs}", please use ' From 6a12b872b2faadd52819c78c2369b6f9d4fe5c7d Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Tue, 13 Nov 2018 12:43:12 -0500 Subject: [PATCH 2/5] DOC: Add tests for extra linebreaks in docstrings. --- scripts/tests/test_validate_docstrings.py | 32 ++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index ccd5f56141a6a..7077c8ad46bf2 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -288,6 +288,34 @@ def astype3(self, dtype): """ pass + def two_linebreaks_between_sections(self, foo): + """ + Test linebreaks message GL03. + + Note 2 blank lines before parameters section. + + + Parameters + ---------- + foo : str + Description of foo parameter. + """ + pass + + def linebreak_at_end_of_docstring(self, foo): + """ + Test linebreaks message GL03. + + Note extra blank line at end of docstring. + + Parameters + ---------- + foo : str + Description of foo parameter. + + """ + pass + def plot(self, kind, **kwargs): """ Generate a plot. @@ -694,7 +722,9 @@ def test_bad_class(self): @capture_stderr @pytest.mark.parametrize("func", [ 'func', 'astype', 'astype1', 'astype2', 'astype3', 'plot', 'method', - 'private_classes']) + 'private_classes', + 'two_linebreaks_between_sections', 'linebreak_at_end_of_docstring', + ]) def test_bad_generic_functions(self, func): errors = validate_one(self._import_path( # noqa:F821 klass='BadGenericDocStrings', func=func))['errors'] From e72756855137b36fb7bbe70f88829f5d66cae0a9 Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Sun, 18 Nov 2018 09:31:30 -0800 Subject: [PATCH 3/5] DOC: Move GL03 extra linebreak tests into test_bad_examples(). --- scripts/tests/test_validate_docstrings.py | 65 +++++++++++++---------- 1 file changed, 36 insertions(+), 29 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 0626b4eaf6011..08c10b75f0969 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -288,34 +288,6 @@ def astype3(self, dtype): """ pass - def two_linebreaks_between_sections(self, foo): - """ - Test linebreaks message GL03. - - Note 2 blank lines before parameters section. - - - Parameters - ---------- - foo : str - Description of foo parameter. - """ - pass - - def linebreak_at_end_of_docstring(self, foo): - """ - Test linebreaks message GL03. - - Note extra blank line at end of docstring. - - Parameters - ---------- - foo : str - Description of foo parameter. - - """ - pass - def plot(self, kind, **kwargs): """ Generate a plot. @@ -695,6 +667,34 @@ def missing_whitespace_after_comma(self): """ pass + def two_linebreaks_between_sections(self, foo): + """ + Test linebreaks message GL03. + + Note 2 blank lines before parameters section. + + + Parameters + ---------- + foo : str + Description of foo parameter. + """ + pass + + def linebreak_at_end_of_docstring(self, foo): + """ + Test linebreaks message GL03. + + Note extra blank line at end of docstring. + + Parameters + ---------- + foo : str + Description of foo parameter. + + """ + pass + class TestValidator(object): @@ -752,7 +752,6 @@ def test_bad_class(self): @pytest.mark.parametrize("func", [ 'func', 'astype', 'astype1', 'astype2', 'astype3', 'plot', 'method', 'private_classes', - 'two_linebreaks_between_sections', 'linebreak_at_end_of_docstring', ]) def test_bad_generic_functions(self, func): errors = validate_one(self._import_path( # noqa:F821 @@ -841,6 +840,14 @@ def test_bad_generic_functions(self, func): 'E226 missing whitespace around arithmetic operator',)), ('BadExamples', 'missing_whitespace_after_comma', ("flake8 error: E231 missing whitespace after ',' (3 times)",)), + ('BadExamples', 'two_linebreaks_between_sections', + ('Double line break found; please use only one blank line to ' + 'separate sections or paragraphs, and do not leave blank lines ' + 'at the end of docstrings',)), + ('BadExamples', 'linebreak_at_end_of_docstring', + ('Double line break found; please use only one blank line to ' + 'separate sections or paragraphs, and do not leave blank lines ' + 'at the end of docstrings',)), ]) def test_bad_examples(self, capsys, klass, func, msgs): result = validate_one(self._import_path(klass=klass, func=func)) From a7d2dbc678f6422d0200a00090a38013781b118f Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Mon, 19 Nov 2018 07:26:35 -0800 Subject: [PATCH 4/5] Revert "DOC: Move GL03 extra linebreak tests into test_bad_examples()." This reverts commit e72756855137b36fb7bbe70f88829f5d66cae0a9. --- scripts/tests/test_validate_docstrings.py | 65 ++++++++++------------- 1 file changed, 29 insertions(+), 36 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 08c10b75f0969..0626b4eaf6011 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -288,6 +288,34 @@ def astype3(self, dtype): """ pass + def two_linebreaks_between_sections(self, foo): + """ + Test linebreaks message GL03. + + Note 2 blank lines before parameters section. + + + Parameters + ---------- + foo : str + Description of foo parameter. + """ + pass + + def linebreak_at_end_of_docstring(self, foo): + """ + Test linebreaks message GL03. + + Note extra blank line at end of docstring. + + Parameters + ---------- + foo : str + Description of foo parameter. + + """ + pass + def plot(self, kind, **kwargs): """ Generate a plot. @@ -667,34 +695,6 @@ def missing_whitespace_after_comma(self): """ pass - def two_linebreaks_between_sections(self, foo): - """ - Test linebreaks message GL03. - - Note 2 blank lines before parameters section. - - - Parameters - ---------- - foo : str - Description of foo parameter. - """ - pass - - def linebreak_at_end_of_docstring(self, foo): - """ - Test linebreaks message GL03. - - Note extra blank line at end of docstring. - - Parameters - ---------- - foo : str - Description of foo parameter. - - """ - pass - class TestValidator(object): @@ -752,6 +752,7 @@ def test_bad_class(self): @pytest.mark.parametrize("func", [ 'func', 'astype', 'astype1', 'astype2', 'astype3', 'plot', 'method', 'private_classes', + 'two_linebreaks_between_sections', 'linebreak_at_end_of_docstring', ]) def test_bad_generic_functions(self, func): errors = validate_one(self._import_path( # noqa:F821 @@ -840,14 +841,6 @@ def test_bad_generic_functions(self, func): 'E226 missing whitespace around arithmetic operator',)), ('BadExamples', 'missing_whitespace_after_comma', ("flake8 error: E231 missing whitespace after ',' (3 times)",)), - ('BadExamples', 'two_linebreaks_between_sections', - ('Double line break found; please use only one blank line to ' - 'separate sections or paragraphs, and do not leave blank lines ' - 'at the end of docstrings',)), - ('BadExamples', 'linebreak_at_end_of_docstring', - ('Double line break found; please use only one blank line to ' - 'separate sections or paragraphs, and do not leave blank lines ' - 'at the end of docstrings',)), ]) def test_bad_examples(self, capsys, klass, func, msgs): result = validate_one(self._import_path(klass=klass, func=func)) From 07ed212db1fae66d51a22d46814fdf41c62c5093 Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Mon, 19 Nov 2018 08:30:00 -0800 Subject: [PATCH 5/5] DOC: Improve test function name & move extra linebreak tests. --- scripts/tests/test_validate_docstrings.py | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 0626b4eaf6011..ca3efbfce20a7 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -752,7 +752,6 @@ def test_bad_class(self): @pytest.mark.parametrize("func", [ 'func', 'astype', 'astype1', 'astype2', 'astype3', 'plot', 'method', 'private_classes', - 'two_linebreaks_between_sections', 'linebreak_at_end_of_docstring', ]) def test_bad_generic_functions(self, func): errors = validate_one(self._import_path( # noqa:F821 @@ -841,8 +840,16 @@ def test_bad_generic_functions(self, func): 'E226 missing whitespace around arithmetic operator',)), ('BadExamples', 'missing_whitespace_after_comma', ("flake8 error: E231 missing whitespace after ',' (3 times)",)), + ('BadGenericDocStrings', 'two_linebreaks_between_sections', + ('Double line break found; please use only one blank line to ' + 'separate sections or paragraphs, and do not leave blank lines ' + 'at the end of docstrings',)), + ('BadGenericDocStrings', 'linebreak_at_end_of_docstring', + ('Double line break found; please use only one blank line to ' + 'separate sections or paragraphs, and do not leave blank lines ' + 'at the end of docstrings',)), ]) - def test_bad_examples(self, capsys, klass, func, msgs): + def test_bad_docstrings(self, capsys, klass, func, msgs): result = validate_one(self._import_path(klass=klass, func=func)) for msg in msgs: assert msg in ' '.join(err[1] for err in result['errors'])