Skip to content

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

Closed
Closed
Doc: Fix ! in C domain ref target syntax#97740
Assignees
CAM-Gerlach
Labels
docsDocumentation in the Doc dir

Description

@CAM-Gerlach
CAM-Gerlach
opened on Oct 2, 2022

! 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.

Activity

  1. CAM-Gerlach
    added
    docsDocumentation in the Doc dir
    on Oct 2, 2022
  2. CAM-Gerlach
    self-assigned this
    on Oct 2, 2022
  3. CAM-Gerlach
    added 2 commits that reference this issue on Oct 2, 2022

    pythongh-97740: Fix bang in Sphinx C domain ref target syntax

    ce7fc52

    pythongh-97740: Fix bang in Sphinx C domain ref target syntax

    edda9dd

  4. AA-Turner commented on Oct 2, 2022

    @AA-Turner
    AA-Turner
    on Oct 2, 2022
    Member

    This is being fixed upstream in Sphinx 5.3, to confirm--thanks to Cam for raising the error.

    A

  5. ezio-melotti
    added this to Sprinton Oct 3, 2022
  6. ezio-melotti
    moved this to Todo in Sprinton Oct 3, 2022
  7. ezio-melotti
    added a commit that references this issue on Oct 3, 2022

    gh-97740: Fix bang in Sphinx C domain ref target syntax (#97741)

    9148c0d
  8. miss-islington
    added 2 commits that reference this issue on Oct 3, 2022

    pythongh-97740: Fix bang in Sphinx C domain ref target syntax (python…

    64cbbd7

    pythongh-97740: Fix bang in Sphinx C domain ref target syntax (python…

    48781a9
  9. ezio-melotti
    moved this from Todo to In Progress in Sprinton Oct 3, 2022
  10. miss-islington
    added 2 commits that reference this issue on Oct 3, 2022

    gh-97740: Fix bang in Sphinx C domain ref target syntax (GH-97741)

    a1711ef

    gh-97740: Fix bang in Sphinx C domain ref target syntax (GH-97741)

    827f77e
  11. ezio-melotti
    closed this as completedon Oct 3, 2022
  12. Repository owner moved this from In Progress to Done in Sprinton Oct 3, 2022

  13. CAM-Gerlach commented on Oct 3, 2022

    @CAM-Gerlach
    CAM-Gerlach
    on Oct 3, 2022
    MemberAuthor

    Thanks to @AA-Turner for doing most of the work to help fix it both here and there!

  14. carljm
    added a commit that references this issue on Oct 3, 2022

    Merge branch 'main' into dictwatch

    e83abac
  15. pablogsal
    added a commit that references this issue on Oct 22, 2022

    gh-97740: Fix bang in Sphinx C domain ref target syntax (GH-97741)

    10818aa
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

docsDocumentation in the Doc dir

Projects

  • Sprint
    Status
    Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions