Merge pull request #5182 from tk0miya/5158_autosummary_wrong_summary

Fix #5158: autosummary: module summary has been broken when it starts with heading

CHANGES

@@ -50,6 +50,7 @@ Bugs fixed
 * #5167: autodoc: Fix formatting type annotations for tuples with more than two
   arguments
 * #3329: i18n: crashed by auto-symbol footnote references
+* #5158: autosummary: module summary has been broken when it starts with heading
 
 Testing
 --------

sphinx/ext/autosummary/__init__.py

@@ -471,21 +471,32 @@ def extract_summary(doc, document):
             doc = doc[:i]
             break
 
-    # Try to find the "first sentence", which may span multiple lines
-    sentences = periods_re.split(" ".join(doc))  # type: ignore
-    if len(sentences) == 1:
-        summary = sentences[0].strip()
+    if doc == []:
+        return ''
+
+    # parse the docstring
+    state_machine = RSTStateMachine(state_classes, 'Body')
+    node = new_document('', document.settings)
+    node.reporter = NullReporter()
+    state_machine.run(doc, node)
+
+    if not isinstance(node[0], nodes.paragraph):
+        # document starts with non-paragraph: pick up the first line
+        summary = doc[0].strip()
     else:
-        summary = ''
-        state_machine = RSTStateMachine(state_classes, 'Body')
-        while sentences:
-            summary += sentences.pop(0) + '.'
-            node = new_document('', document.settings)
-            node.reporter = NullReporter()
-            state_machine.run([summary], node)
-            if not node.traverse(nodes.system_message):
-                # considered as that splitting by period does not break inline markups
-                break
+        # Try to find the "first sentence", which may span multiple lines
+        sentences = periods_re.split(" ".join(doc))  # type: ignore
+        if len(sentences) == 1:
+            summary = sentences[0].strip()
+        else:
+            summary = ''
+            while sentences:
+                summary += sentences.pop(0) + '.'
+                node[:] = []
+                state_machine.run([summary], node)
+                if not node.traverse(nodes.system_message):
+                    # considered as that splitting by period does not break inline markups
+                    break
 
     # strip literal notation mark ``::`` from tail of summary
     summary = literal_re.sub('.', summary)

tests/test_ext_autosummary.py

@@ -85,6 +85,11 @@ def test_extract_summary(capsys):
     doc = ['blah blah::']
     assert extract_summary(doc, document) == 'blah blah.'
 
+    # heading
+    doc = ['blah blah',
+           '=========']
+    assert extract_summary(doc, document) == 'blah blah'
+
     _, err = capsys.readouterr()
     assert err == ''