Skip to content

Read ReST lines starting with a role as text - #170

Merged
rr- merged 1 commit into
mainfrom
rework/30-rest-roles
Nov 6, 2026
Merged

rr- merged 1 commit into
mainfrom
rework/30-rest-roles

Conversation

@rr-

@rr- rr- commented Nov 6, 2026

Copy link
Copy Markdown
Owner

In ReST, a line that starts with a role was read as a field named after the role. So in

Called after the request is dispatched.

This calls all functions decorated with
:meth:`teardown_request`, and :meth:`Blueprint.teardown_request`
if a blueprint handled the request.

the second paragraph lost its second and third lines to a DocstringMeta with key meth and a description starting `teardown_request`,, and compose wrote it back as :meth: `teardown_request`, ... after the description.

This reads a field's name the way docutils does: a colon inside the name is followed by neither whitespace nor a backtick, and the colon closing it is followed by whitespace or the end of the line. Any other line starting with a colon is text. It continues the field before it, or the description if no field came yet, and after a blank line it ends the field list and goes to the long description. The example above now parses with the whole paragraph in the long description and no meta.

One more case follows from the same rule: :param x:desc, with no space after the closing colon, is no field in docutils and is now text too. A line starting with a colon that holds no other colon, such as :param x, is still a field that cannot be read and reports bad-field, as before.

Parity against origin/main: 85 of 29,143 docstrings differ, 78 from the case files (corpus docstrings from flask, requests, sphinx, google-auth, scipy and numpy, plus the four new rest/roles_* cases) and 7 from the stdlib, none generated. Every one has a line starting with a role, and each differs in parse REST and its composes, and in parse AUTO and its composes where auto picked ReST. In one numpy docstring auto-detection now picks Numpydoc, because ReST no longer finds fake role fields in it. No case or stdlib docstring writes :name:text without a space.

Bench (just bench): parse rest 91.2 ms on main vs 92.3 ms (1.01x), parse auto 341.7 ms vs 345.2 ms (1.00x), and the other workloads 0.95x to 1.01x.

@rr- rr- self-assigned this Nov 6, 2026
A line starting with a role, such as ":meth:`run` does stuff.", was
read as a field named meth, cutting it out of the description or of
the field it continued. Read a field's name as docutils does: a colon
in the name is followed by neither whitespace nor a backtick, and the
colon closing it is followed by whitespace or the end of the line.
Any other line starting with a colon continues the field before it,
or the description before any field, and after a blank line it ends
the field list.

A line starting with a colon and holding no other colon, as in
":param x", is still a field that cannot be read.
@rr-
rr- force-pushed the rework/30-rest-roles branch from 8682157 to b2485aa Compare November 6, 2026 17:56
@rr-
rr- merged commit 5315203 into main Nov 6, 2026
25 checks passed
@rr-
rr- deleted the rework/30-rest-roles 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