Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Closed
CAM-Gerlach opened this issue Oct 2, 2022 · 2 comments
Closed

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

CAM-Gerlach opened this issue Oct 2, 2022 · 2 comments
Assignees
@CAM-Gerlach
Labels
docs Documentation in the Doc dir

Comments

@CAM-Gerlach
Copy link
Member

! 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.
@CAM-Gerlach CAM-Gerlach added the docs Documentation in the Doc dir label Oct 2, 2022
@CAM-Gerlach CAM-Gerlach self-assigned this Oct 2, 2022
CAM-Gerlach added a commit to CAM-Gerlach/cpython that referenced this issue Oct 2, 2022
@CAM-Gerlach
pythongh-97740: Fix bang in Sphinx C domain ref target syntax
ce7fc52
@bedevere-bot bedevere-bot mentioned this issue Oct 2, 2022
Merged
CAM-Gerlach added a commit to CAM-Gerlach/cpython that referenced this issue Oct 2, 2022
@CAM-Gerlach @AA-Turner
pythongh-97740: Fix bang in Sphinx C domain ref target syntax
edda9dd 
Co-authored-by: Adam Turner <[email protected]>
@CAM-Gerlach CAM-Gerlach mentioned this issue Oct 2, 2022
Closed
33 tasks
@AA-Turner
Copy link
Member

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

A

ezio-melotti pushed a commit that referenced this issue Oct 3, 2022
@CAM-Gerlach @AA-Turner
gh-97740: Fix bang in Sphinx C domain ref target syntax (#97741)
9148c0d 
* gh-97740: Fix bang in Sphinx C domain ref target syntax

Co-authored-by: Adam Turner <[email protected]>

* Add NEWS entry for C domain bang fix

Co-authored-by: Adam Turner <[email protected]>
This was referenced Oct 3, 2022
Merged
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Oct 3, 2022
@CAM-Gerlach @miss-islington
pythongh-97740: Fix bang in Sphinx C domain ref target syntax (python…
64cbbd7 
…GH-97741)

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

Co-authored-by: Adam Turner <[email protected]>

* Add NEWS entry for C domain bang fix

Co-authored-by: Adam Turner <[email protected]>
(cherry picked from commit 9148c0d)

Co-authored-by: C.A.M. Gerlach <[email protected]>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Oct 3, 2022
@CAM-Gerlach @miss-islington
pythongh-97740: Fix bang in Sphinx C domain ref target syntax (python…
48781a9 
…GH-97741)

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

Co-authored-by: Adam Turner <[email protected]>

* Add NEWS entry for C domain bang fix

Co-authored-by: Adam Turner <[email protected]>
(cherry picked from commit 9148c0d)

Co-authored-by: C.A.M. Gerlach <[email protected]>
miss-islington added a commit that referenced this issue Oct 3, 2022
@miss-islington @CAM-Gerlach
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

Co-authored-by: Adam Turner <[email protected]>

* Add NEWS entry for C domain bang fix

Co-authored-by: Adam Turner <[email protected]>
(cherry picked from commit 9148c0d)

Co-authored-by: C.A.M. Gerlach <[email protected]>
miss-islington added a commit that referenced this issue Oct 3, 2022
@miss-islington @CAM-Gerlach
gh-97740: Fix bang in Sphinx C domain ref target syntax (GH-97741)
827f77e 
* gh-97740: Fix bang in Sphinx C domain ref target syntax

Co-authored-by: Adam Turner <[email protected]>

* Add NEWS entry for C domain bang fix

Co-authored-by: Adam Turner <[email protected]>
(cherry picked from commit 9148c0d)

Co-authored-by: C.A.M. Gerlach <[email protected]>
@CAM-Gerlach
Copy link
Member Author

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

carljm added a commit to carljm/cpython that referenced this issue Oct 3, 2022
@carljm
Merge branch 'main' into dictwatch
e83abac 
* main: (2069 commits)
  pythongh-96512: Move int_max_str_digits setting to PyConfig (python#96944)
  pythongh-94808: Coverage: Check picklablability of calliter (python#95923)
  pythongh-94808: Add test coverage for PyObject_HasAttrString (python#96627)
  pythongh-94732: Fix KeyboardInterrupt race in asyncio run_forever() (python#97765)
  Fix typos in `bltinmodule.c`. (pythonGH-97766)
  pythongh-94808: `_PyLineTable_StartsLine` was not used (pythonGH-96609)
  pythongh-97681: Remove Tools/demo/ directory (python#97682)
  Fix typo in unittest docs (python#97742)
  pythongh-97728: Argument Clinic: Fix uninitialized variable in the Py_UNICODE converter (pythonGH-97729)
  pythongh-95913: Fix PEP number in PEP 678 What's New ref label (python#97739)
  pythongh-95913: Copyedit/improve New Modules What's New section (python#97721)
  pythongh-97740: Fix bang in Sphinx C domain ref target syntax (python#97741)
  pythongh-96819: multiprocessing.resource_tracker: check if length of pipe write <= 512 (python#96890)
  pythongh-97706: multiprocessing tests: Delete unused variable `rand` (python#97707)
  pythonGH-85447: Clarify docs about awaiting future multiple times (python#97738)
  [docs] Update logging cookbook with recipe for using a logger like an output… (pythonGH-97730)
  pythongh-97607: Fix content parsing in the impl-detail reST directive (python#97652)
  pythongh-95975: Move except/*/finally ref labels to more precise locations (python#95976)
  pythongh-97591: In `Exception.__setstate__()` acquire strong references before calling `tp_hash` slot (python#97700)
  pythongh-95588: Drop the safety claim from `ast.literal_eval` docs. (python#95919)
  ...
pablogsal pushed a commit that referenced this issue Oct 22, 2022
@miss-islington @CAM-Gerlach @pablogsal
gh-97740: Fix bang in Sphinx C domain ref target syntax (GH-97741)
10818aa 
* gh-97740: Fix bang in Sphinx C domain ref target syntax

Co-authored-by: Adam Turner <[email protected]>

* Add NEWS entry for C domain bang fix

Co-authored-by: Adam Turner <[email protected]>
(cherry picked from commit 9148c0d)

Co-authored-by: C.A.M. Gerlach <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@CAM-Gerlach CAM-Gerlach

Labels
docs Documentation in the Doc dir
Projects
Sprint 2024
Archived in project
Milestone
No milestone
Development

No branches or pull requests
4 participants
@AA-Turner @CAM-Gerlach @ezio-melotti and others