Repository navigation
Read ReST lines starting with a role as text - #170
Merged
Merged
Conversation
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-
force-pushed
the
rework/30-rest-roles
branch
from
November 6, 2026 17:56
8682157 to
b2485aa
Compare
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.
In ReST, a line that starts with a role was read as a field named after the role. So in
the second paragraph lost its second and third lines to a
DocstringMetawith keymethand 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 reportsbad-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 inparse RESTand its composes, and inparse AUTOand 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:textwithout 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.