Fix #9568: autosummary: summarise overlined sectioned headings correctly

Add an extra step in the autosummary summariser algorithm to get a valid
text form of section headings.  This fixed issues when the first element
of a summarised document was a section heading with overlines, such as

    =======
    Heading
    =======

Previously, the first line would be taken verbatim, which caused parse
errors in the rest of the document.

CHANGES

@@ -30,6 +30,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 extract_summary(doc: List[str], document: Any) -> str:
 
     # 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.']