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.

Sign up for GitHub

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

Jump to bottom

Support (detect?) missing blank line before Returns sections. #316

Open
Carreau opened this issue Apr 8, 2021 · 3 comments · May be fixed by #327
Open

Support (detect?) missing blank line before Returns sections. #316

Carreau opened this issue Apr 8, 2021 · 3 comments · May be fixed by #327

Comments

@Carreau
Copy link
Contributor

Carreau commented Apr 8, 2021

It's not the fist time I come across this, but it looks like project regularly forget the blank line between Parameters and Return, leading to the Returns section being merged into Parameters.

That would likely need to update _read_to_next_section to use extra heuristics than read_to_next_empty_line,
Only checking for lines with ------, or ====== might not be sufficient as this also would match tracebacks.

Carreau/velin#14 for reference.
@keewis
Copy link
Contributor

keewis commented May 24, 2021

_parse_summary would also need to be changed:

Summary line.
Parameters
----------
param1 : int

As for filtering out tracebacks: we could either check for the section name (using NumpyDocString.sections.keys()) or check the line following the --- / === for the string "Traceback (most recent call last)" (which is in both the cpython and the ipython traceback)

@keewis keewis linked a pull request May 24, 2021 that will close this issue
Open
@larsoner
Copy link
Collaborator

larsoner commented Jan 17, 2022 •
edited

I'm -1 on fixing this in numpydoc -- this is invalid in plain RST, so I don't think we should support it. In other words, in plain RST this will render as a single header plus a long (ugly) section, not two:

First
-----
some content
Second
------
some more content

@rgommers
Copy link
Member

Agreed with @larsoner, this is invalid and needs to be fixed in the docstring.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

improve section detection keewis/numpydoc
4 participants
@rgommers @Carreau @larsoner @keewis