Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Autosummary fails to summarise docstrings that begin with overline section headings #9568

Closed
jakelishman opened this issue Aug 20, 2021 · 0 comments · Fixed by #9569
Closed
Labels

Comments

@jakelishman
Copy link
Contributor

jakelishman commented Aug 20, 2021

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

=========
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

Incorrect behaviour of autosummary, with the empty table.

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

jakelishman added a commit to jakelishman/sphinx that referenced this issue Aug 20, 2021
…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.
tk0miya added a commit that referenced this issue Aug 29, 2021
Fix #9568: autosummary: summarise overlined sectioned headings correctly
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Sep 29, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant