Repository navigation
3.10 Documentation Not Hyperlinking Some Methods #86348
Description
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']
Activity
Fidget-Spinner commentedon Oct 28, 2020
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 commentedon Jul 26, 2021
The same thing happens in 3.11. I've also confirmed the markup is exactly the same.
akulakov commentedon Jul 26, 2021
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 commentedon Jul 27, 2021
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.pyPerhaps in 3.8 the entire file was considered / configured a block for
objectobject?I will make a PR to fix the links.
akulakov commentedon Jul 27, 2021
I put the PR up here:
https://github.com/python/cpython/pull/27384/files
serhiy-storchaka commentedon Dec 10, 2021
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 commentedon Dec 10, 2021
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 commentedon Dec 10, 2021
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
kumaraditya303 commentedon May 9, 2022
Fixed by #27384