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

bisect.bisect is not cross-referenced properly #104145

Closed
Gobot1234 opened this issue May 3, 2023 · 9 comments
Closed

bisect.bisect is not cross-referenced properly #104145

Gobot1234 opened this issue May 3, 2023 · 9 comments
Labels
3.11 only security fixes 3.12 bugs and security fixes 3.13 bugs and security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error

Comments

@Gobot1234
Copy link
Contributor

Gobot1234 commented May 3, 2023 •
edited by bedevere-bot

Documentation

The documentation page for bisect includes lots of interlinks to the bisect function but it appears that link isn't being resolved correctly by sphinx, whilst it thinks it is a function, it links to the module header

To reproduce: https://docs.python.org/3/library/bisect.html#searching-sorted-lists, click on bisect() and see it take you to the top of the page and not to the function bisect

Linked PRs
@Gobot1234 Gobot1234 added the docs Documentation in the Doc dir label May 3, 2023
@Lincoln-developer

This comment was marked as off-topic.

Sign in to view
@Gobot1234

This comment was marked as off-topic.

Sign in to view
@Lincoln-developer

This comment was marked as off-topic.

Sign in to view
@AA-Turner AA-Turner added type-bug An unexpected behavior, bug, or error 3.11 only security fixes 3.12 bugs and security fixes 3.13 bugs and security fixes labels May 4, 2023
@AA-Turner
Copy link
Member

James is right, this is an issue in Sphinx. Removing the 'easy' label.

A

@AA-Turner AA-Turner removed the easy label May 4, 2023
@Lincoln-developer

This comment was marked as off-topic.

Sign in to view
@AA-Turner

This comment was marked as off-topic.

Sign in to view
@Lincoln-developer

This comment was marked as off-topic.

Sign in to view
@AA-Turner
Copy link
Member

@Gobot1234 -- the issue is the default cross reference resolution order from Sphinx. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#role-py-obj for an explanation, but in essence a standard cross reference role (e.g. :py:func:, :meth:, etc) performs a lookup ignoring the cross-reference type specified. For instance, in our case this means that the :func:`bisect` role here tries to resolve an object with the name bisect first, and succeeds when it finds the reference to the bisect module.

I'm not sure why cross-reference resolution was implemented with this behaviour, but in the spirit of Chesterton's fence I'm hesitant to change it. It does seem odd though that the explicit type specified is ignored by the resolution machinery: https://github.com/sphinx-doc/sphinx/blob/ba7408209e84ee413f240afc20f3c6b484a81f8f/sphinx/domains/python.py#L1344-L1356

I'll put up a PR with an (inelegant) fix, but this likely affects the other modules with an eponymous object.

A

@AA-Turner AA-Turner mentioned this issue May 4, 2023
Merged
AlexWaygood pushed a commit that referenced this issue May 8, 2023
@AA-Turner
GH-104145: Use fully-qualified cross reference types for the bisect m…
76eef55 
…odule (#104172)
@bedevere-bot bedevere-bot mentioned this issue May 8, 2023
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue May 8, 2023
@AA-Turner @miss-islington
pythonGH-104145: Use fully-qualified cross reference types for the bi…
3e5613c 
…sect module (pythonGH-104172)

(cherry picked from commit 76eef55)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
AlexWaygood pushed a commit that referenced this issue May 8, 2023
@miss-islington @AA-Turner
[3.11] GH-104145: Use fully-qualified cross reference types for the b…
8a6ff59 
…isect module (GH-104172) (#104295)

GH-104145: Use fully-qualified cross reference types for the bisect module (GH-104172)
(cherry picked from commit 76eef55)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
@AlexWaygood
Copy link
Member

AlexWaygood commented May 8, 2023 •
edited

Fixed and backported. Thanks @AA-Turner!

I'll close this for now; we can open a followup issue if we find other instances of this problem occuring.

jbower-fb pushed a commit to jbower-fb/cpython-jbowerfb that referenced this issue May 8, 2023
@AA-Turner @jbower-fb
pythonGH-104145: Use fully-qualified cross reference types for the bi…
a7e9a63 
…sect module (python#104172)
carljm added a commit to carljm/cpython that referenced this issue May 9, 2023
@carljm
Merge branch 'main' into inlinecomp2
76077cd 
* main: (47 commits)
  pythongh-97696 Remove unnecessary check for eager_start kwarg (python#104188)
  pythonGH-104308: socket.getnameinfo should release the GIL (python#104307)
  pythongh-104310: Add importlib.util.allowing_all_extensions() (pythongh-104311)
  pythongh-99113: A Per-Interpreter GIL! (pythongh-104210)
  pythonGH-104284: Fix documentation gettext build (python#104296)
  pythongh-89550: Buffer GzipFile.write to reduce execution time by ~15% (python#101251)
  pythongh-104223: Fix issues with inheriting from buffer classes (python#104227)
  pythongh-99108: fix typo in Modules/Setup (python#104293)
  pythonGH-104145: Use fully-qualified cross reference types for the bisect module (python#104172)
  pythongh-103193: Improve `getattr_static` test coverage (python#104286)
  Trim trailing whitespace and test on CI (python#104275)
  pythongh-102500: Remove mention of bytes shorthand (python#104281)
  pythongh-97696: Improve and fix documentation for asyncio eager tasks (python#104256)
  pythongh-99108: Replace SHA3 implementation HACL* version (python#103597)
  pythongh-104273: Remove redundant len() calls in argparse function (python#104274)
  pythongh-64660: Don't hardcode Argument Clinic return converter result variable name (python#104200)
  pythongh-104265 Disallow instantiation of `_csv.Reader` and `_csv.Writer` (python#104266)
  pythonGH-102613: Improve performance of `pathlib.Path.rglob()` (pythonGH-104244)
  pythongh-103650: Fix perf maps address format (python#103651)
  pythonGH-89812: Churn `pathlib.Path` methods (pythonGH-104243)
  ...
carljm added a commit to carljm/cpython that referenced this issue May 9, 2023
@carljm
Merge branch 'main' into fixsendfamily
a614216 
* main: (29 commits)
  pythongh-104276: Make `_struct.unpack_iterator` type use type flag instead of custom constructor (python#104277)
  pythongh-97696: Move around and update the whatsnew entry for asyncio eager task factory (python#104298)
  pythongh-103193: Fix refleaks in `test_inspect` and `test_typing` (python#104320)
  require-pr-label.yml: Add missing "permissions:" (python#104309)
  pythongh-90656: Add platform triplets for 64-bit LoongArch (LA64) (python#30939)
  pythongh-104180: Read SOCKS proxies from macOS System Configuration (python#104181)
  pythongh-97696 Remove unnecessary check for eager_start kwarg (python#104188)
  pythonGH-104308: socket.getnameinfo should release the GIL (python#104307)
  pythongh-104310: Add importlib.util.allowing_all_extensions() (pythongh-104311)
  pythongh-99113: A Per-Interpreter GIL! (pythongh-104210)
  pythonGH-104284: Fix documentation gettext build (python#104296)
  pythongh-89550: Buffer GzipFile.write to reduce execution time by ~15% (python#101251)
  pythongh-104223: Fix issues with inheriting from buffer classes (python#104227)
  pythongh-99108: fix typo in Modules/Setup (python#104293)
  pythonGH-104145: Use fully-qualified cross reference types for the bisect module (python#104172)
  pythongh-103193: Improve `getattr_static` test coverage (python#104286)
  Trim trailing whitespace and test on CI (python#104275)
  pythongh-102500: Remove mention of bytes shorthand (python#104281)
  pythongh-97696: Improve and fix documentation for asyncio eager tasks (python#104256)
  pythongh-99108: Replace SHA3 implementation HACL* version (python#103597)
  ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
3.11 only security fixes 3.12 bugs and security fixes 3.13 bugs and security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@AA-Turner @hauntsaninja @Gobot1234 @AlexWaygood @Lincoln-developer