bisect.bisect is not cross-referenced properly

[Gobot1234]

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

• GH-104145: Use fully-qualified cross reference types for the bisect module #104172
• [3.11] GH-104145: Use fully-qualified cross reference types for the bisect module (GH-104172) #104295

[Lincoln-developer]

Hey @Gobot1234 and @hauntsaninja ,am kindly requesting to work on this if it is possible. Thanks and kind regards.

[Gobot1234]

I would have done it myself but I'm not even sure where the issue lies as the documentation uses the func role which probably means sphinx is broken

[Lincoln-developer]

okay then, how can we go about fixing this

[AA-Turner]

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

A

[Lincoln-developer]

Alright, does @AA-Turner removing the easy label mean its out of entry bounds ? I am just starting out with contributions.

[AA-Turner]

It just means that it isn't entirely straightforwards; to find other documentation issues labelled as easy you can look here: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Aeasy+label%3Adocs
A

[Lincoln-developer]

thanks @AA-Turner, let me look through and see where to begin from.

[AA-Turner]

@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