This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: 3.10 Documentation Not Hyperlinking Some Methods
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: andrei.avk, docs@python, kj, miss-islington, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2020-10-28 15:28 by kj, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 27384 merged andrei.avk, 2021-07-27 04:32
PR 30020 merged miss-islington, 2021-12-10 09:40
PR 30021 merged miss-islington, 2021-12-10 09:40
Messages (8)
msg379829 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2020-10-28 15:28
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.
msg398258 - (view) Author: Andrei Kulakov (andrei.avk) * (Python triager) Date: 2021-07-26 21:17
The same thing happens in 3.11. I've also confirmed the markup is exactly the same.
msg398263 - (view) Author: Andrei Kulakov (andrei.avk) * (Python triager) Date: 2021-07-26 22:15
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.
msg398275 - (view) Author: Andrei Kulakov (andrei.avk) * (Python triager) Date: 2021-07-27 02:26
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.
msg398277 - (view) Author: Andrei Kulakov (andrei.avk) * (Python triager) Date: 2021-07-27 04:31
I put the PR up here: 
https://github.com/python/cpython/pull/27384/files
msg408182 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2021-12-10 09:40
New changeset 8c74713d0e349c27518080945d5f040dfd52a56e by andrei kulakov in branch 'main':
bpo-42182: stdtypes doc - update and fix links to several dunder methods  (GH-27384)
https://github.com/python/cpython/commit/8c74713d0e349c27518080945d5f040dfd52a56e
msg408185 - (view) Author: miss-islington (miss-islington) Date: 2021-12-10 10:02
New changeset 64c2788f42c49c7094d3b6e5404fe8386a2b4779 by Miss Islington (bot) in branch '3.10':
bpo-42182: stdtypes doc - update and fix links to several dunder methods  (GH-27384)
https://github.com/python/cpython/commit/64c2788f42c49c7094d3b6e5404fe8386a2b4779
msg408186 - (view) Author: miss-islington (miss-islington) Date: 2021-12-10 10:04
New changeset 40d765260ae08d152ee89ed9c1c621f4a0024fa6 by Miss Islington (bot) in branch '3.9':
bpo-42182: stdtypes doc - update and fix links to several dunder methods  (GH-27384)
https://github.com/python/cpython/commit/40d765260ae08d152ee89ed9c1c621f4a0024fa6
History
Date User Action Args
2022-04-11 14:59:37adminsetgithub: 86348
2021-12-10 10:04:58miss-islingtonsetmessages: + msg408186
2021-12-10 10:02:19miss-islingtonsetmessages: + msg408185
2021-12-10 09:40:28miss-islingtonsetpull_requests: + pull_request28245
2021-12-10 09:40:24miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request28244
2021-12-10 09:40:14serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg408182
2021-07-27 04:32:37andrei.avksetkeywords: + patch
stage: patch review
pull_requests: + pull_request25917
2021-07-27 04:31:10andrei.avksetmessages: + msg398277
2021-07-27 02:26:53andrei.avksettype: behavior
versions: + Python 3.9, Python 3.11
2021-07-27 02:26:16andrei.avksetmessages: + msg398275
2021-07-26 22:15:56andrei.avksetmessages: + msg398263
2021-07-26 21:17:29andrei.avksetnosy: + andrei.avk
messages: + msg398258
2020-10-28 15:28:27kjcreate