Docs: :deco: references with ~ render as @~module.name #159265

Documentation

Decorator cross-references written with the tilde short form, e.g. :deco:`~typing.dataclass_transform` , render literally as @~typing.dataclass_transform instead of @dataclass_transform. The link target is correct; only the title is wrong.

See e.g. What's New In Python 3.11 – PEP 681.

Cause

The deco role is Sphinx's own (_PyDecoXRefRole). In Sphinx 8.2.3, it prepends @ in update_title_and_target(), which runs before PyXRefRole.process_link(). process_link() then checks title[0:1] == '~', sees @, and leaves the tilde and module prefix in place. Sphinx 9.x prepends the @ in process_link() after the tilde handling, so it renders correctly.

These references were introduced in gh-139598 (gh-105812). That landed while Doc/requirements.txt was pinned to sphinx<9.0.0 (gh-143284, to work around Chinese search in Sphinx 9), so the docs build hits the Sphinx 8 bug.

Possible fixes

1. Unpin and go back to Sphinx 9 once the Documentation can't find anything in Chinese language #143284 search issue is resolved. That fixes every instance with no .rst changes.
2. Rewrite each reference with an explicit title, e.g. :deco:`dataclass_transform <typing.dataclass_transform>` , or drop the ~ (:deco:`typing.dataclass_transform` ).

Affected references (29)

Source links are pinned to 0768eed. "Rendered" links point to docs.python.org/dev/ and use a text fragment to jump to the broken text.

Found with: git grep -n ':deco:`~' -- Doc