Merge pull request #9569 from jakelishman/fix-autosummary-sections

Fix #9568: autosummary: summarise overlined sectioned headings correctly

CHANGES

@@ -31,6 +31,7 @@ Bugs fixed
 * #9522: autodoc: PEP 585 style typehints having arguments (ex. ``list[int]``)
   are not displayed well
 * #9481: autosummary: some warnings contain non-existing filenames
+* #9568: autosummary: summarise overlined sectioned headings correctly
 * #9481: c domain: some warnings contain non-existing filenames
 * #9481: cpp domain: some warnings contain non-existing filenames
 * #9456: html search: abbreation marks are inserted to the search result if

sphinx/ext/autosummary/__init__.py

@@ -540,7 +540,10 @@ def parse(doc: List[str], settings: Any) -> nodes.document:
 
     # parse the docstring
     node = parse(doc, document.settings)
-    if not isinstance(node[0], nodes.paragraph):
+    if isinstance(node[0], nodes.section):
+        # document starts with a section heading, so use that.
+        summary = node[0].astext().strip()
+    elif not isinstance(node[0], nodes.paragraph):
         # document starts with non-paragraph: pick up the first line
         summary = doc[0].strip()
     else:

tests/test_ext_autosummary.py

@@ -109,6 +109,11 @@ def test_extract_summary(capsys):
            '=========']
     assert extract_summary(doc, document) == 'blah blah'
 
+    doc = ['=========',
+           'blah blah',
+           '=========']
+    assert extract_summary(doc, document) == 'blah blah'
+
     # hyperlink target
     doc = ['Do `this <https://www.sphinx-doc.org/>`_ and that. '
            'blah blah blah.']