Skip to content

Compose blank lines in descriptions with no indent - #196

Merged
rr- merged 1 commit into
mainfrom
rework/61-compose-blank-lines
Nov 7, 2026
Merged

rr- merged 1 commit into
mainfrom
rework/61-compose-blank-lines

Conversation

@rr-

@rr- rr- commented Nov 7, 2026

Copy link
Copy Markdown
Owner

Compose a blank line inside an item's description as an empty line, not as a line of indent spaces, so that compose(parse(text)) gives back the text of #61 exactly and composed docstrings have no trailing whitespace.

  • Google, Numpydoc and Epydoc joined the description lines with the indent, so every blank line got it too. They now go through a shared hang() in _compose.py, which indents only the lines that have text. ReST already wrote blank lines empty, and the other places that indent text (sections, directives, attribute bodies) already skipped them.
  • test_invariants.py gets test_compose_writes_no_blank_line_with_indent: every case input whose own blank lines are empty composes, in every style and rendering, with no line of spaces alone. It fails on main for Google, Numpydoc and Epydoc. test_google.py adds the example from newlines not preserved in google param description #61.
  • just update-cases rewrote 54 case files; all 123 changed lines are compose output where a line of spaces became an empty line.
  • Parity against main: 2430 of 29184 docstrings differ, all in compose output (case 1317, stdlib 204, generated 28179 outputs), and every one is the same text once lines of spaces alone are emptied. No parse output changes.
  • Bench: worst ratio 1.01 on Python 3.8 and 1.04 on 3.14.

Closes #61.

Google, Numpydoc and Epydoc compose joined an item's description lines
with the indent, so a blank line inside it came out as spaces alone.
Indent only the lines that have text, through one shared helper. ReST
already wrote them empty.

A new invariant checks that no case input composes, in any style or
rendering, to a line of spaces alone.

Closes #61.
@rr- rr- self-assigned this Nov 7, 2026
@rr-
rr- merged commit b9bad50 into main Nov 7, 2026
26 checks passed
@rr-
rr- deleted the rework/61-compose-blank-lines branch November 7, 2026 14:45
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.

newlines not preserved in google param description

1 participant