Skip to content

docstring_parser: part lead text from the summary - #194

Merged
rr- merged 2 commits into
mainfrom
rework/59-lead-text
Nov 7, 2026
Merged

rr- merged 2 commits into
mainfrom
rework/59-lead-text

Conversation

@rr-

@rr- rr- commented Nov 7, 2026

Copy link
Copy Markdown
Owner

Numpydoc moves indented text before a section's first item into the long description. When that text came right after a summary with no blank line, blank_after_short_description stayed False, so compose wrote it straight under the summary and it read back as part of the summary. This affected every section with items: Parameters, Attributes, Other Parameters, Receives, Keyword Arguments, Returns, Yields, Raises and Warns.

  • append_loose now marks such text as a paragraph of its own whenever compose would write it right after the summary, that is, unless a leading deprecation goes between them. The existing deprecation_keeps_blank_after_short cases keep their spacing.
  • Google, ReST and Epydoc already set the flag, so only Numpydoc output changes.
  • New test: the lead text reads back for Parameters, Attributes and Raises. I also checked all nine sections with items in every rendering.
  • No existing round-trip exclusion goes away. None of them was this bug. google+numpydoc: list methods one item each #193 adds the one that was, (182, Numpydoc), and will drop it once based on this branch.
  • just update-cases changes nothing.
  • Parity against origin/main: 5 generated inputs differ, only in Numpydoc and auto, and only by blank_after_short_description turning True plus the compose output that follows from it.
  • Bench against origin/main: max 1.02 on 3.14 and 1.01 on 3.8.

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.
@rr- rr- self-assigned this Nov 7, 2026
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.
@rr-
rr- merged commit e1c6a86 into main Nov 7, 2026
26 checks passed
@rr-
rr- deleted the rework/59-lead-text branch November 7, 2026 11:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant