Skip to content

Doc: Fix ! in C domain ref target syntax #97740

Closed
@CAM-Gerlach

Description

@CAM-Gerlach

! doesn't appear to work as documented in the C domain (to not try to resolve references) in the CPython docs building on 4.5.0. That means there's no way to not link subsequent instances of a reference to a C domain item, or refer to an item that isn't defined (e.g. for removed or undocumented APIs in the What's New, where it is used heavily) without either using the syntactically, semantically and stylistically inconsistent literal syntax (or, for non-existent entries, attempting to resolve known broken references and generating spurious warnings).

Thanks to @AA-Turner 's helpful investigation, it looks like this is:

an implementation error in CXRefRole.run() means that if c_allow_pre_v3 is True then the value of .disabled is ignored, hence the ! is not taken into account.

At some point soon we need to upgrade the docs to the latest Sphinx to pick up a number of significant features and bug fixes that have been implemented specifically for our docs, and we also need to migrate off c_allow_pre_v3 which I understand @AA-Turner is also working on. However, there is an immediate stopgap fix to get things working immediately, including on older docs—we can add a bit of code in our conf.py to avoid the issue. I'll submit a PR.

Metadata

Metadata

Assignees

Labels

docsDocumentation in the Doc dir

Projects

Status

Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions