diff options
| author | Jake Lishman <jake.lishman@ibm.com> | 2021-08-20 17:05:58 +0100 |
|---|---|---|
| committer | Jake Lishman <jake.lishman@ibm.com> | 2021-08-20 17:05:58 +0100 |
| commit | 9d7fa75d4a247b5898e25de2311385ad0405ce7a (patch) | |
| tree | 14f8165a0473dd06373271e5db2cbc4daaf914e6 | |
| parent | 8fd4373d3aec07b8d9a4fb159b6236f4dc715b21 (diff) | |
| download | sphinx-git-9d7fa75d4a247b5898e25de2311385ad0405ce7a.tar.gz | |
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.
| -rw-r--r-- | CHANGES | 1 | ||||
| -rw-r--r-- | sphinx/ext/autosummary/__init__.py | 5 | ||||
| -rw-r--r-- | tests/test_ext_autosummary.py | 5 |
3 files changed, 10 insertions, 1 deletions
@@ -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 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 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: 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.'] |