diff --git a/CHANGES b/CHANGES index 9ad0ba86f..bbdb85ea8 100644 --- a/CHANGES +++ b/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 -------- diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index c1c6a9fb0..20a4e3b0a 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -471,21 +471,32 @@ def extract_summary(doc, document): doc = doc[:i] break - # 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() + 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: - summary = '' - state_machine = RSTStateMachine(state_classes, 'Body') - while sentences: - summary += sentences.pop(0) + '.' - node = new_document('', document.settings) - node.reporter = NullReporter() - state_machine.run([summary], node) - if not node.traverse(nodes.system_message): - # considered as that splitting by period does not break inline markups - break + # 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 = '' + while sentences: + summary += sentences.pop(0) + '.' + node[:] = [] + state_machine.run([summary], node) + if not node.traverse(nodes.system_message): + # considered as that splitting by period does not break inline markups + break # strip literal notation mark ``::`` from tail of summary summary = literal_re.sub('.', summary) diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index fba0ae33c..9b98a59d1 100644 --- a/tests/test_ext_autosummary.py +++ b/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 == ''