Repository: sphinx-doc/sphinx

Issue:
Autosummary fails to summarise docstrings that begin with overline section headings
### Describe the bug

When using autosummary, it attempts to summarise paragraphs specially, and everything else it just takes the first line.  This causes parsing errors if the first reST element in the source is a section heading with an overline, for example

```text
=========
My Module
=========
```

It will take the first line (`====`) and insert it raw into a table cell, which results in invalid reST.

### How to Reproduce

First unpack attached [MWE project](https://github.com/sphinx-doc/sphinx/files/7022761/autosummary-module-bug-mwe.zip), which is a very minimal Python package, using autosummary to summarise two modules whose docstrings both begin with overline headings.

```
$ python -mpip install -e .
$ cd docs
$ make html
```

`make html` will show two warnings, and the generated HTML page (`doc/_build/html/index.html`) will have a table with empty entries in it, rather than showing text.


### Expected behavior

The summariser should take the text of section headings as a summary.

### Your project

MWE attached to reproduction steps.

### Screenshots

![Incorrect behaviour of autosummary, with the empty table.](https://user-images.githubusercontent.com/5968590/130260685-7fbf978e-870b-4680-b28f-fa624d41c487.png)

The generated `index.html` file from the attached MWE.  This is the incorrect behaviour: the table entries are empty because of parsing errors.  (Ignore the Sphinx 3.5.4 in the screenshot - I accidentally took the screenshot using a build from an old venv, but the behaviour is present as of the latest 4.x.)

### OS

Any

### Python version

Any

### Sphinx version

4.x branch

### Sphinx extensions

sphinx.ext.autosummary

### Extra tools

_No response_

### Additional context

_No response_

Discussion:

Patch:
diff --git a/CHANGES b/CHANGES
index 2ed4c7492..4b7745622 100644
--- a/CHANGES
+++ b/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
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
index 379fd48ad..be89f1c38 100644
--- a/sphinx/ext/autosummary/__init__.py
+++ b/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:


Test patch:
diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py
index 71868d492..9506ad19d 100644
--- a/tests/test_ext_autosummary.py
+++ b/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.']