Repository navigation
Accept Numpydoc underlines of any length, and of = - #178
Merged
Merged
Conversation
A section title had to be underlined by exactly as many dashes as it has characters, so "Parameters" over "---" or over "==========" stayed in the long description. As in napoleon, an underline of two or more dashes or equals signs now does, whatever its length. Auto-detection looks for an underline of equals signs too, so it no longer takes such a docstring for one without sections. Headings no section declares still need an underline of dashes as long as the title, which tells them from tables. More text now reads as sections, which made compose show two ways a return did not read back: a named return with an empty type, written as its name alone and read back as its type, and an unnamed one with a colon in its type, read back as a name and a type. Compose writes them as "total :" and ": a: b". A param with no name is written with no space before its colon, which indented it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A Numpydoc section title no longer needs an underline exactly as long as the title. Following napoleon, any underline of two or more
-, or of two or more=, now starts the section, soand
are read as sections and no longer end up in the long description. Auto-detection's "no fields at all" shortcut now also looks for
=underlines, so a docstring like that gets detected as Numpydoc and not sent to ReST unparsed.Headings that no section declares, such as
Options, are unchanged: they still need a dash underline exactly as long as the title. That rule is what keeps a table's header row from being read as a heading.Once more text read as sections, the round-trip invariant caught two returns that compose wrote in a form that read back differently:
total :, was written astotal, and that reads back as a type. It is now writtentotal :.: a: b, was written asa: b, and that reads back as a name and a type. It is now written: a: b.A typed param with an empty name is also written without a space before its colon, since that space indented the line. The invariant exclusion lists are unchanged.
Case diffs
corpus/numpy/numpy.lib._histograms_impl._get_bin_edges: itsParameters/==========andReturns/=======were long description and are now three params and two returns. Detection changes fromresttonumpydoc, and compose writes dash underlines.numpydoc/underline_01(short and long dashes),numpydoc/underline_02(=, including detection),numpydoc/compose_returns_01(the two returns above).Parity against
origin/mainI spot-checked the generated parse differences. Each one has a declared title with a dash underline of a different length. The six that differ only in compose are the return and param forms listed above.
tools/parity.pyitself crashes with aKeyErrorwhen printing an input that parses in the base but not in the tree, so I got these counts from a small script that calls itsoutputs().Bench
Python 3.8, every ratio between 0.98 and 1.01.