Repository: pandas-dev/pandas

Issue:
DOC: scripts/validate_docstrings.py should detect when the short summary span over multiple lines
#### Code Sample, a copy-pastable example if possible

Take any docstring and write a short summary (the first line of the docstring) on multiple lines. Then test it with `./scripts/validate_docstrings.py pandas.DataFrame.my_method`. 

#### Problem description

As discussed in #22516 and in the [documentation](https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html), the first line of the docstring should be a short summary and shouldn't take more than one line.

#### Expected Output

An error stating that the first line (the short summary) should not be more than one line long.



Discussion:
Hmm I think we have this generally covered and tested:

https://github.com/pandas-dev/pandas/blob/e2e1a1051576a48f210ce17272fc24b90ebcf24a/scripts/tests/test_validate_docstrings.py#L558

Isn't the first line in the linked PR a single line anyway? @datapythonista 
Seems like before fixing the docstring to have a short summary, the script had the reported problem, as @Moisan showned here: https://gist.github.com/Moisan/5b349fddeea6f7ed83987673f7bde5de
Ah OK - I thought this was referring to the current state of the PR, which is now correct. That makes more sense :-)
@Moisan feel free to send a PR, you can use the beginning of your original docstring for the test that reproduces the error. I guess it has to do with the latex code, as in most cases the script works as expected.

Resolving patch:
diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -163,10 +163,12 @@ def double_blank_lines(self):
 
     @property
     def summary(self):
-        if not self.doc['Extended Summary'] and 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')
 


Test patch:
diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
--- 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):
     """
@@ -556,7 +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',
+         ('Summary should fit in a single line.',)),
         # Parameters tests
         ('BadParameters', 'missing_params',
          ('Parameters {**kwargs} not documented',)),