Repository navigation
google+numpydoc: list methods one item each - #193
Merged
Merged
Conversation
A Methods section was one text item holding the whole section. Read it as napoleon does, one item per method: a DocstringMethod of the new Kind.METHOD, named by the method's signature as written, as in run(x, y=1), with its description. Docstring.methods lists them. Google takes everything before the item's colon as the signature, so annotations inside the brackets stay in it, and a head with no colon is a signature alone. Numpydoc takes the whole line. A section that lists no method stays a titled text item, as before. Both styles compose Methods sections that read back. ReST and Epydoc have no methods, so they write each as a :methods: text field holding its signature and description.
Numpydoc moves indented text before a section's first item to the long description. Right after a summary with no blank line, it kept blank_after_short_description False, so the text composed straight under the summary and read back as part of it, in every section with items, such as Parameters, Attributes and Raises. Mark such text as a paragraph of its own whenever it is written right after the summary, that is, unless a leading deprecation goes between them, which keeps the summary's spacing as before.
Generated input 182 reads back in Numpydoc now that text before a section's first item stays apart from the summary, so it needs no exclusion. Mark the Methods change as breaking: code that read a Methods section as one text item gets an item per method instead.
append_loose imported leading_deprecation inside the function, as _directives imports _compose, which imports _text. The function needs only the common classes, so move it down to _text, where every module that uses it can import it at the top level.
This was referenced Nov 7, 2026
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.
Item 10 of BEHAVIOR.md: a
Methodssection gives one item per method, in Google and Numpydoc, instead of one text item holding the whole section.DocstringMethodof the newKind.METHOD, with the signature as written as itsname, such asrun(x, y=1), and its description.Docstring.methodslists them.Kind.METHODis 13, afterTEXT, so the other kinds keep their values.stop(a: int)stay in it. A head with no colon is a signature alone, as napoleon reads it.datetime.time's still parse in Google.:methods:/@methods:text field holding its signature and description. Writing the signature in the field's head would split it at its colon in ReST and fail to parse in Epydoc.methodsgets aDocstringMethodper method instead.just update-caseschanged four cases, allMethodssections that are now items:google/napoleon_sections_02,numpydoc/napoleon_sections_01and two scipy corpus cases.