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,17 +471,28 @@ def extract_summary(doc, document):
             doc = doc[:i]
             break
 
+    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:
         # 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 = ''
-        state_machine = RSTStateMachine(state_classes, 'Body')
             while sentences:
                 summary += sentences.pop(0) + '.'
-            node = new_document('', document.settings)
-            node.reporter = NullReporter()
+                node[:] = []
                 state_machine.run([summary], node)
                 if not node.traverse(nodes.system_message):
                     # considered as that splitting by period does not break inline markups

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 == ''