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
Priority: normal Keywords: patch

Created on 2020-10-28 15:28 by kj, last changed 2021-07-27 04:32 by andrei.avk.

Pull Requests
URL Status Linked Edit
PR 27384 open andrei.avk, 2021-07-27 04:32
Messages (5)
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
History
Date User Action Args
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