You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
=========
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, 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
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
The text was updated successfully, but these errors were encountered:
…ngs 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.
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
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, which is a very minimal Python package, using autosummary to summarise two modules whose docstrings both begin with overline headings.
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
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
The text was updated successfully, but these errors were encountered: