Repository navigation
Read deprecated directives in ReST and Google - #169
Merged
Merged
Conversation
A ".. deprecated:: <version>" directive in the free text now gives a DocstringDeprecated in ReST and Google, as it does in Numpydoc: the version from its line, its indented body as the description. The directive leaves the description, and every directive gives an item. A directive on the first line of text is read whatever its indent, as the short description it would otherwise give is. The cutting of directives out of the lines moves from ReST's attribute directives into _directives, which both parsers use, with the placing of a leading deprecation after the short description that Numpydoc compose did on its own. ReST and Google compose a deprecation as the directive: right after the short description when it comes first, or else in its place among the items. A blank line around it is written only where it reads back the same. ReST keeps a :deprecated: field for a deprecation read from one with a description. Epydoc reads @deprecated as a deprecation, with the version that starts its description, and composes a deprecation as that field with its version.
Composing a docstring looked for a deprecation to write as a directive at its start and end, which made composing ReST 22% slower. Look only when the first or last meta is a deprecation.
rr-
force-pushed
the
rework/39-deprecated-directive
branch
from
November 6, 2026 20:55
cfe56e1 to
4266940
Compare
Composing a Google docstring looked for a deprecation to write after the short description every time, which took composing to the edge of 10% slower. Look only when the first meta is a deprecation.
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.
ReST and Google now read a
.. deprecated::directive in the free text as aDocstringDeprecated, as Numpydoc already did, and Epydoc reads@deprecatedas one too. The version comes from the directive line and the indented body is the description. Each directive gives its own item, and the directive leaves the long description.Before, the directive stayed in the long description in ReST and Google, and Epydoc's
@deprecatedwas a plain text meta.Compose writes deprecations back as directives in ReST and Google, and keeps the version in Epydoc. Before, ReST wrote a
:deprecation:field that dropped the version, and Google wrote aDeprecation:section that read back as text.The round-trip test on main passes with no new exclusions.
Parity: 1,989 of 29,162 docstrings differ: 28 case, 0 stdlib, 1,961 generated. Every one has a deprecated directive or field in its input.