From 108d092a50f7a374ef1f914e6e93fbe239c439f8 Mon Sep 17 00:00:00 2001 From: Thierry Moisan Date: Wed, 5 Sep 2018 21:13:20 -0400 Subject: [PATCH 1/2] Test in scripts/validate_docstrings.py that the short summary is always one line long --- scripts/tests/test_validate_docstrings.py | 11 +++++++++++ scripts/validate_docstrings.py | 2 +- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 0c0757c6963d7..474f5a1e7fce6 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -362,6 +362,15 @@ def multi_line(self): which is not correct. """ + def two_paragraph_multi_line(self): + """ + Extends beyond one line + which is not correct. + + Extends beyond one line, which in itself is correct but the + previous short summary should still be an issue. + """ + class BadParameters(object): """ @@ -557,6 +566,8 @@ def test_bad_generic_functions(self, func): ('Summary must start with infinitive verb',)), ('BadSummaries', 'multi_line', ('a short summary in a single line should be present',)), + ('BadSummaries', 'two_paragraph_multi_line', + ('a short summary in a single line should be present',)), # Parameters tests ('BadParameters', 'missing_params', ('Parameters {**kwargs} not documented',)), diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 83bb382480eaa..bf9d763f9e9a3 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -163,7 +163,7 @@ def double_blank_lines(self): @property def summary(self): - if not self.doc['Extended Summary'] and len(self.doc['Summary']) > 1: + if len(self.doc['Summary']) > 1: return '' return ' '.join(self.doc['Summary']) From 8e08dd6ca9cdff3afa3f5c07531e3f25933bf4ae Mon Sep 17 00:00:00 2001 From: Thierry Moisan Date: Thu, 6 Sep 2018 20:10:40 -0400 Subject: [PATCH 2/2] summary property now always returns the summary and add num_summary_lines in validate_docstrings script --- scripts/tests/test_validate_docstrings.py | 4 ++-- scripts/validate_docstrings.py | 8 ++++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 474f5a1e7fce6..00496f771570b 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -565,9 +565,9 @@ def test_bad_generic_functions(self, func): ('BadSummaries', 'no_capitalization', ('Summary must start with infinitive verb',)), ('BadSummaries', 'multi_line', - ('a short summary in a single line should be present',)), + ('Summary should fit in a single line.',)), ('BadSummaries', 'two_paragraph_multi_line', - ('a short summary in a single line should be present',)), + ('Summary should fit in a single line.',)), # Parameters tests ('BadParameters', 'missing_params', ('Parameters {**kwargs} not documented',)), diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index bf9d763f9e9a3..790a62b53845b 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -163,10 +163,12 @@ def double_blank_lines(self): @property def summary(self): - if len(self.doc['Summary']) > 1: - return '' return ' '.join(self.doc['Summary']) + @property + def num_summary_lines(self): + return len(self.doc['Summary']) + @property def extended_summary(self): if not self.doc['Extended Summary'] and len(self.doc['Summary']) > 1: @@ -452,6 +454,8 @@ def validate_one(func_name): errs.append('Summary must start with infinitive verb, ' 'not third person (e.g. use "Generate" instead of ' '"Generates")') + if doc.num_summary_lines > 1: + errs.append("Summary should fit in a single line.") if not doc.extended_summary: wrns.append('No extended summary found')