Description
Replace explicit ReST cross-reference roles (:class:, :func:, :meth:, :data:, :mod:, :attr:, :exc:) in docstrings with bare single-backtick references, reserving double backticks for code literals. Dotted qualification paths and ~ short-name prefixes are kept verbatim — only the role prefixes are dropped. Example: :class:`wool.ContextVar` becomes `wool.ContextVar`, and :meth:`Chain.mount` becomes `Chain.mount`.
The convention is: single backtick = cross-reference, double backtick = code literal. Rendering is handled in the docs repo, which resolves bare single-backtick terms through Sphinx's default_role = "py:obj" against the autodoc object inventory, with intersphinx resolving stdlib names (e.g. contextvars.Context) to docs.python.org. No tooling changes are needed in this repo — only the authoring convention.
Names that are ambiguous across namespaces (e.g. wool.ContextVar vs contextvars.ContextVar vs protocol.ContextVar) must remain fully qualified inside the backticks — the qualification is semantic disambiguation, not markup ceremony, and it is exactly what makes role-free resolution sound.
Current scope: 877 role usages across 67 files in src/ and tests/.
Motivation
The role prefixes are pure ceremony with three costs. They are redundant — the Sphinx object inventory already knows each symbol's kind, so declaring it per-reference adds nothing. They are a staleness vector — when an object's kind changes (a function becomes a class, an attribute becomes a property), every :func:/:attr: reference to it silently breaks while a bare reference keeps resolving. And they are noisy — docstrings are read raw in IDE hovers and terminals far more often than in rendered docs, and the role syntax measurably hurts that primary reading experience.
Expected Outcome
No :class:/:func:/:meth:/:data:/:mod:/:attr:/:exc: roles remain in src/ or tests/ docstrings. Single-backtick terms are cross-references (qualified where ambiguous); double-backtick terms are code literals. The convention is recorded in the project style guidance so future contributions follow it. The sweep is mechanical with no prose changes, verified by ruff/pyright and a green test suite.
Description
Replace explicit ReST cross-reference roles (
:class:,:func:,:meth:,:data:,:mod:,:attr:,:exc:) in docstrings with bare single-backtick references, reserving double backticks for code literals. Dotted qualification paths and~short-name prefixes are kept verbatim — only the role prefixes are dropped. Example::class:`wool.ContextVar`becomes`wool.ContextVar`, and:meth:`Chain.mount`becomes`Chain.mount`.The convention is: single backtick = cross-reference, double backtick = code literal. Rendering is handled in the docs repo, which resolves bare single-backtick terms through Sphinx's
default_role = "py:obj"against the autodoc object inventory, with intersphinx resolving stdlib names (e.g.contextvars.Context) to docs.python.org. No tooling changes are needed in this repo — only the authoring convention.Names that are ambiguous across namespaces (e.g.
wool.ContextVarvscontextvars.ContextVarvsprotocol.ContextVar) must remain fully qualified inside the backticks — the qualification is semantic disambiguation, not markup ceremony, and it is exactly what makes role-free resolution sound.Current scope: 877 role usages across 67 files in
src/andtests/.Motivation
The role prefixes are pure ceremony with three costs. They are redundant — the Sphinx object inventory already knows each symbol's kind, so declaring it per-reference adds nothing. They are a staleness vector — when an object's kind changes (a function becomes a class, an attribute becomes a property), every
:func:/:attr:reference to it silently breaks while a bare reference keeps resolving. And they are noisy — docstrings are read raw in IDE hovers and terminals far more often than in rendered docs, and the role syntax measurably hurts that primary reading experience.Expected Outcome
No
:class:/:func:/:meth:/:data:/:mod:/:attr:/:exc:roles remain insrc/ortests/docstrings. Single-backtick terms are cross-references (qualified where ambiguous); double-backtick terms are code literals. The convention is recorded in the project style guidance so future contributions follow it. The sweep is mechanical with no prose changes, verified by ruff/pyright and a green test suite.