Skip to content

Split Numpydoc raises heads after their type - #171

Merged
rr- merged 1 commit into
mainfrom
rework/33-numpydoc-raises
Nov 6, 2026
Merged

rr- merged 1 commit into
mainfrom
rework/33-numpydoc-raises

Conversation

@rr-

@rr- rr- commented Nov 6, 2026

Copy link
Copy Markdown
Owner

In a Numpydoc Raises or Warns section, an item written with its description on the head line made the whole line the type:

Raises
------
ValueError : if bad.
    Or worse.

gave a raises with type_name='ValueError : if bad.' and the description Or worse.. It now gives type_name='ValueError' and the description if bad.\nOr worse., as sphinx napoleon reads it. ValueError: if bad. without the space before the colon splits the same way, and ValueError : alone on its line takes its description from the indented lines below.

The line splits only when what comes before the colon is one type: a dotted name, maybe with a subscript such as pkg.Error[int]. That is the same type pattern Google's Raises: already uses, so it moves to _text for both styles to share. Prose with a colon, such as If the value is bad: an error, and several types, such as KeyError, TypeError : if missing., stay whole as before. Compose already writes the type and the description on separate lines, so the split items read back unchanged.

Parity against origin/main: 6 of 29,142 docstrings differ, 4 from the case files and 2 generated, none from the stdlib. The case ones are two pandas corpus docstrings (TypeError : on inequality comparisons and ValueError : `match` does not ...) plus the new numpydoc/raises_03 and numpydoc/warns_02 cases. The generated ones are a y: thing item and a Yields: item that ended up under a Raises heading, which now split into the type y with the description thing, and the type Yields. All of them differ in parse NUMPYDOC and parse AUTO and in their composes.

Bench (just bench): parse numpydoc 172.7 ms on main vs 171.8 ms (0.99x), and the other workloads 0.98x to 1.00x.

@rr- rr- self-assigned this Nov 6, 2026
An item under Raises or Warns written as "ValueError : if bad." or
"ValueError: if bad." had the whole line as its type. Split it as
napoleon does: the type is ValueError, and "if bad." starts the
description, which the indented lines below continue.

Split only when what comes before the colon is one type, a dotted
name maybe with a subscript, as Google's Raises reads it, so a line of
prose with a colon in it stays whole. The type pattern moves to _text
for both styles to share.
@rr-
rr- force-pushed the rework/33-numpydoc-raises branch from e99be54 to 7c576bf Compare November 6, 2026 17:59
@rr-
rr- merged commit c443375 into main Nov 6, 2026
25 checks passed
@rr-
rr- deleted the rework/33-numpydoc-raises branch November 6, 2026 23:51
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