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

Ref target labels for except/except*/finally not located precisely #95975

Closed
CAM-Gerlach opened this issue Aug 14, 2022 · 4 comments
Closed

Ref target labels for except/except*/finally not located precisely #95975

CAM-Gerlach opened this issue Aug 14, 2022 · 4 comments
Assignees
@CAM-Gerlach
Labels
docs Documentation in the Doc dir

Comments

@CAM-Gerlach
Copy link
Member

CAM-Gerlach commented Aug 14, 2022 •
edited
Loading

As originally noticed by @ezio-melotti on #95937 , the ref target labels for the except, except* and finally keywords are located at the top of the [try statement section in the Compound Statements][(https://docs.python.org/3.11/reference/compound_stmts.html#the-try-statement) reference; however, they are actually discussed at specific points sometimes several pages down in the lengthy section. Therefore, the targets should be moved to more precise locations immediately prior to the introduction of the relevant keyword.

It would also be nice to make the section either to navigate with sub sections rather than one big long section, but that is considered outside the immediate scope of this proximate issue. It turns out this is required to get :keyword: to work, and the section is already organized by clause, so it makes sense just to add them.
@CAM-Gerlach CAM-Gerlach added the docs Documentation in the Doc dir label Aug 14, 2022
@CAM-Gerlach CAM-Gerlach self-assigned this Aug 14, 2022
CAM-Gerlach added a commit to CAM-Gerlach/cpython that referenced this issue Aug 14, 2022
@CAM-Gerlach
pythongh-95975: Move except/*/finally ref labels to more precise loca…
23e1b84 
…tions
CAM-Gerlach added a commit to CAM-Gerlach/cpython that referenced this issue Aug 14, 2022
@CAM-Gerlach
pythongh-95975: Move except/*/finally ref labels to more precise loca…
f741f38 
…tions
@CAM-Gerlach
Copy link
Member Author

The plot thickens—for no obvious reason, it seems :keyword: simply won't work with ref target labels that don't precede a section header (or at least some named object), which is presumably why they were put there in the first place. However, given it would make navigating what has become a quite long section easier, and requires no textual changes given the section is already strongly organized by clause type, I can just add the appropriate subsection headers to fix this, given it improves both internal and external navigation.

@ghost
Copy link

ghost commented Aug 14, 2022

@CAM-Gerlach hi, can I work on this issue? please.

@CAM-Gerlach CAM-Gerlach mentioned this issue Aug 14, 2022
Merged
@CAM-Gerlach
Copy link
Member Author

CAM-Gerlach commented Aug 14, 2022 •
edited
Loading

@najmiehsa Sorry, I already submitted #95976 — it ended up being not as trivial as I thought in any case.

ezio-melotti added a commit that referenced this issue Oct 2, 2022
@CAM-Gerlach @ezio-melotti
gh-95975: Move except/*/finally ref labels to more precise locations (#…
dcc8233 
…95976)

* gh-95975: Move except/*/finally ref labels to more precise locations

* Add section headers to fix :keyword: role and aid navigation

* Move see also to the introduction rather than a particular subsection

* Fix other minor Sphinx syntax issues with except

Co-authored-by: Ezio Melotti <[email protected]>

* Suppress redundant link to same section for except too

* Don't link try/except/else/finally keywords if in the same section

* Format try/except/finally as keywords in modified sections

Co-authored-by: Ezio Melotti <[email protected]>
@miss-islington miss-islington mentioned this issue Oct 2, 2022
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Oct 2, 2022
@CAM-Gerlach @miss-islington
pythongh-95975: Move except/*/finally ref labels to more precise loca…
4fee86b 
…tions (pythonGH-95976)

* pythongh-95975: Move except/*/finally ref labels to more precise locations

* Add section headers to fix :keyword: role and aid navigation

* Move see also to the introduction rather than a particular subsection

* Fix other minor Sphinx syntax issues with except

Co-authored-by: Ezio Melotti <[email protected]>

* Suppress redundant link to same section for except too

* Don't link try/except/else/finally keywords if in the same section

* Format try/except/finally as keywords in modified sections

Co-authored-by: Ezio Melotti <[email protected]>
(cherry picked from commit dcc8233)

Co-authored-by: C.A.M. Gerlach <[email protected]>
miss-islington added a commit that referenced this issue Oct 2, 2022
@miss-islington @CAM-Gerlach
gh-95975: Move except/*/finally ref labels to more precise locations (G…
1fa848a 
…H-95976)

* gh-95975: Move except/*/finally ref labels to more precise locations

* Add section headers to fix :keyword: role and aid navigation

* Move see also to the introduction rather than a particular subsection

* Fix other minor Sphinx syntax issues with except

Co-authored-by: Ezio Melotti <[email protected]>

* Suppress redundant link to same section for except too

* Don't link try/except/else/finally keywords if in the same section

* Format try/except/finally as keywords in modified sections

Co-authored-by: Ezio Melotti <[email protected]>
(cherry picked from commit dcc8233)

Co-authored-by: C.A.M. Gerlach <[email protected]>
serhiy-storchaka pushed a commit to serhiy-storchaka/cpython that referenced this issue Oct 2, 2022
@CAM-Gerlach @ezio-melotti @serhiy-storchaka
pythongh-95975: Move except/*/finally ref labels to more precise loca…
879e866 
…tions (python#95976)

* pythongh-95975: Move except/*/finally ref labels to more precise locations

* Add section headers to fix :keyword: role and aid navigation

* Move see also to the introduction rather than a particular subsection

* Fix other minor Sphinx syntax issues with except

Co-authored-by: Ezio Melotti <[email protected]>

* Suppress redundant link to same section for except too

* Don't link try/except/else/finally keywords if in the same section

* Format try/except/finally as keywords in modified sections

Co-authored-by: Ezio Melotti <[email protected]>
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-95975: Move except/*/finally ref labels to more precise locations (G…
d79a412 
…H-95976)

* gh-95975: Move except/*/finally ref labels to more precise locations

* Add section headers to fix :keyword: role and aid navigation

* Move see also to the introduction rather than a particular subsection

* Fix other minor Sphinx syntax issues with except

Co-authored-by: Ezio Melotti <[email protected]>

* Suppress redundant link to same section for except too

* Don't link try/except/else/finally keywords if in the same section

* Format try/except/finally as keywords in modified sections

Co-authored-by: Ezio Melotti <[email protected]>
(cherry picked from commit dcc8233)

Co-authored-by: C.A.M. Gerlach <[email protected]>
@hauntsaninja
Copy link
Contributor

Thanks all!

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
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@hauntsaninja @CAM-Gerlach