PY-26281: Make empty line after summary in docstring optional

GitOrigin-RevId: 35914ea4676e716fca8a82eff7e8bde4f427d8ff

python/helpers/docstring_formatter.py

@@ -8,6 +8,9 @@ from six import text_type, u
 
 ENCODING = 'utf-8'
 
+# regexp from sphinxcontrib/napoleon/docstring.py:35 and py2only/docutils/parsers/rst/states.py:1107
+TAGS_START = re.compile(
+    r'(\.\. \S+::)|:(?![: ])([^:\\]|\\.|:(?!([ `]|$)))*(?<! ):( +|$)')
 
 def format_rest(docstring):
     from docutils import nodes
@@ -208,6 +211,7 @@ def format_rest(docstring):
             self.output = ''
 
     writer = _DocumentPseudoWriter()
+    docstring = add_blank_line_before_first_tag(docstring)
     publish_string(docstring, writer=writer, settings_overrides={'report_level': 10000,
                                                                  'halt_level': 10000,
                                                                  'warning_stream': None,
@@ -219,6 +223,16 @@ def format_rest(docstring):
     return u('').join(visitor.body)
 
 
+def add_blank_line_before_first_tag(docstring):
+    input_lines = docstring.splitlines()
+    for i, line in enumerate(input_lines):
+        if TAGS_START.match(line):
+            if i > 0 and not input_lines[i - 1].isspace():
+                input_lines.insert(i, '')
+            break
+    return '\n'.join(input_lines)
+
+
 def format_google(docstring):
     from sphinxcontrib.napoleon import GoogleDocstring
     transformed = text_type(GoogleDocstring(textwrap.dedent(docstring)))

python/helpers/tests/data/docstrings/google_no_empty_line_between_text_and_attributes.html

@@ -0,0 +1,2 @@
+<p>Summary</p>
+<p>Description</p>

python/helpers/tests/data/docstrings/google_no_empty_line_between_text_and_attributes.rest

@@ -0,0 +1,12 @@
+Summary
+
+Description
+.. attribute:: attr1
+
+   attr1 description
+
+   :type: int
+
+.. attribute:: attr2
+
+   attr2 description

python/helpers/tests/data/docstrings/google_no_empty_line_between_text_and_attributes.txt

@@ -0,0 +1,6 @@
+Summary
+
+Description
+Attributes:
+    attr1 (int): attr1 description
+    attr2: attr2 description

python/helpers/tests/data/docstrings/google_no_empty_line_between_text_and_seealso.html

@@ -0,0 +1,5 @@
+<p>Summary</p>
+<p>Description</p>
+<h1 class="heading">See Also</h1>
+Some text
+Some text

python/helpers/tests/data/docstrings/google_no_empty_line_between_text_and_seealso.rest

@@ -0,0 +1,7 @@
+Summary
+
+Description
+.. seealso::
+
+   Some text
+   Some text

python/helpers/tests/data/docstrings/google_no_empty_line_between_text_and_seealso.txt

@@ -0,0 +1,6 @@
+Summary
+
+Description
+See also:
+  Some text
+  Some text

python/helpers/tests/data/docstrings/numpy_no_empty_line_between_text_and_param.html

@@ -0,0 +1,2 @@
+<p>Summary</p>
+<p>This is an example of a module level function.</p>

python/helpers/tests/data/docstrings/numpy_no_empty_line_between_text_and_param.rest

@@ -0,0 +1,7 @@
+Summary
+
+This is an example of a module level function.
+:param param1: The first parameter.
+:type param1: int
+:param param2: The second parameter.
+:type param2: Optional[str]

python/helpers/tests/data/docstrings/numpy_no_empty_line_between_text_and_param.txt

@@ -0,0 +1,9 @@
+Summary
+
+This is an example of a module level function.
+Parameters
+----------
+param1 : int
+    The first parameter.
+param2 : Optional[str]
+    The second parameter.

python/helpers/tests/data/docstrings/rest_no_empty_line_between_math_and_param.html

@@ -0,0 +1,2 @@
+<p>Function evaluating
+<span class="rst-formula"><i>F</i>(<br/><i>rho</i><sub>1</sub>, <br/><i>rho</i><sub>2</sub>)</span></p>

python/helpers/tests/data/docstrings/rest_no_empty_line_between_math_and_param.txt

@@ -0,0 +1,4 @@
+Function evaluating
+:math:`F(\\rho_1, \\rho_2)`
+:param param1: the first parameter
+:type param1: `MyClass`

python/helpers/tests/data/docstrings/rest_no_empty_line_between_text_and_param.html

@@ -0,0 +1 @@
+<p>Some description</p>

python/helpers/tests/data/docstrings/rest_no_empty_line_between_text_and_param.txt

@@ -0,0 +1,3 @@
+Some description
+:param param1: the first parameter
+:type param1: `MyClass`

python/helpers/tests/test_docstring_formatter.py

@@ -127,3 +127,18 @@ class DocstringFormatterTest(HelpersTestCase):
 
     def test_rest_simple(self):
         self._test()
+
+    def test_rest_no_empty_line_between_text_and_param(self):
+        self._test()
+
+    def test_rest_no_empty_line_between_math_and_param(self):
+        self._test()
+
+    def test_google_no_empty_line_between_text_and_seealso(self):
+        self._test()
+
+    def test_google_no_empty_line_between_text_and_attributes(self):
+        self._test()
+
+    def test_numpy_no_empty_line_between_text_and_param(self):
+        self._test()