3.10 Documentation Not Hyperlinking Some Methods

[Fidget-Spinner]

BPO	42182
Nosy	@serhiy-storchaka, @miss-islington, @Fidget-Spinner, @akulakov
PRs	bpo-42182: stdtypes doc - update and fix links to several dunder methods  #27384 [3.10] bpo-42182: stdtypes doc - update and fix links to several dunder methods (GH-27384) #30020 [3.9] bpo-42182: stdtypes doc - update and fix links to several dunder methods (GH-27384) #30021

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-10-28.15:28:27.277>
labels = ['3.11', 'type-bug', '3.9', '3.10', 'docs']
title = '3.10 Documentation Not Hyperlinking Some Methods'
updated_at = <Date 2021-12-10.10:04:58.860>
user = 'https://github.com/Fidget-Spinner'

bugs.python.org fields:

activity = <Date 2021-12-10.10:04:58.860>
actor = 'miss-islington'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-10-28.15:28:27.277>
creator = 'kj'
dependencies = []
files = []
hgrepos = []
issue_num = 42182
keywords = ['patch']
message_count = 8.0
messages = ['379829', '398258', '398263', '398275', '398277', '408182', '408185', '408186']
nosy_count = 5.0
nosy_names = ['docs@python', 'serhiy.storchaka', 'miss-islington', 'kj', 'andrei.avk']
pr_nums = ['27384', '30020', '30021']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue42182'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[Fidget-Spinner]

Some ``:meth:`` markups are not being hyperlinked at all, while some are. This only occurs for Python 3.10. This also seems related to https://bugs.python.org/issue42042.

Eg.
For 3.9, https://docs.python.org/3.9/library/stdtypes.html#truth-value-testing:
__bool__, __len__ are hyperlinked.

For 3.10, https://docs.python.org/3.10/library/stdtypes.html#truth-value-testing:
__bool__, __len__ are not hyperlinked.

This occurs throughout the documentation, but it doesn't seem to consistently happen. For example, in https://docs.python.org/3.10/library/stdtypes.html#contextmanager.\_\_exit__ , ``__exit__`` is hyperlinked, but right below that section, the other ``__exit__``s are not. This is puzzling since their markup both uses the same :meth:`__exit__`.

I'm not able to locally reproduce this using Sphinx 2.4.0. I don't know which version exactly of Sphinx this regression occured.

[akulakov]

The same thing happens in 3.11. I've also confirmed the markup is exactly the same.

[akulakov]

In this case, it appears that ref with tilde and object makes it work in both 3.10 and 3.11, but with just bare method specified, it doesn't create link in both -- so it may be good to try updating it to have tilde and a ref to obj:

Once an iterator's :meth:`~iterator.__next__` method raises
:exc:`StopIteration`, it must continue to do so on subsequent calls.
Implementations that do not obey this property are deemed broken.

.. _generator-types:

Generator Types
---------------

Python's :term:`generator`\s provide a convenient way to implement the iterator
protocol. If a container object's :meth:`__iter__` method is implemented as a
generator, it will automatically return an iterator object (technically, a
generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__`
methods.

[akulakov]

Something changed between 3.8 and 3.9 so that "bare" references to methods on `object` no longer get linked. So for example, :meth:`__bool__` would get link to object.__bool__ anchor, but in 3.9+, it should be :meth:`~object.__bool__` for the link to be generated.

The case of __enter__ and __exit__ is that inside of contextmanager block, Sphinx knows that bare ref should link to contextmanager, but outside of the block, it does not, so no link is created.

In 3.8 docs, there are bare refs to __enter__ and __exit__ outside of relevant block, so they link to object.__enter__ and object.__exit__, which is of course wrong.

See 2nd paragraph below the block: https://docs.python.org/3.8/library/stdtypes.html#contextmanager.\_\_exit__

I wasn't able to find why or how in 3.8 it was configured to auto-link bare refs to object. I looked at make.bat, conf.py and pyspecific.py

Perhaps in 3.8 the entire file was considered / configured a block for object object?

I will make a PR to fix the links.

[akulakov]

I put the PR up here:
https://github.com/python/cpython/pull/27384/files

[serhiy-storchaka]

New changeset 8c74713 by andrei kulakov in branch 'main':
bpo-42182: stdtypes doc - update and fix links to several dunder methods (GH-27384)
8c74713

[miss-islington]

New changeset 64c2788 by Miss Islington (bot) in branch '3.10':
bpo-42182: stdtypes doc - update and fix links to several dunder methods (GH-27384)
64c2788

[miss-islington]

New changeset 40d7652 by Miss Islington (bot) in branch '3.9':
bpo-42182: stdtypes doc - update and fix links to several dunder methods (GH-27384)
40d7652