Repository navigation
Many broken :meth: roles in the docs #91411
Description
| BPO | 47255 |
|---|---|
| Nosy | @JelleZijlstra, @Fidget-Spinner |
| PRs |
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 2022-04-08.03:13:27.583>
labels = ['3.11', '3.9', '3.10', 'docs']
title = 'Many broken :meth: roles in the docs'
updated_at = <Date 2022-04-08.15:41:25.420>
user = 'https://github.com/JelleZijlstra'bugs.python.org fields:
activity = <Date 2022-04-08.15:41:25.420>
actor = 'kj'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2022-04-08.03:13:27.583>
creator = 'JelleZijlstra'
dependencies = []
files = []
hgrepos = []
issue_num = 47255
keywords = ['patch']
message_count = 3.0
messages = ['416956', '416957', '416992']
nosy_count = 3.0
nosy_names = ['docs@python', 'JelleZijlstra', 'kj']
pr_nums = ['32409']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue47255'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
Activity
JelleZijlstra commentedon Apr 8, 2022
The docs for the hash() builtin use :meth:`__hash__`, but this doesn't actually link to the datamodel documentation for __hash__: it needs :meth:`~object.__hash__` instead.
I'm fixing this in the builtin functions docs, but there are probably more places.
Why don't we warn when a :meth: link doesn't actually create a link?
JelleZijlstra commentedon Apr 8, 2022
There are a lot of places in the rest of the docs that have the same problem:
Doc % git grep ':meth:`__' | grep -v whatsnew | wc -l
610
I wonder if we can make the :meth: role globally default to linking to object.__dunder__. Would that require a change to Sphinx?
Fidget-Spinner commentedon Apr 8, 2022
It's 3.10 only. Presumably our sphinx version changed then and something broke. In 3.9 and earlier the links are all fine.
See https://bugs.python.org/issue42182 for a similar issue I raised ages ago.
StanFromIreland commentedon Aug 18, 2025
@AA-Turner / @picnixz Is there anyway to do this in Sphinx? I can not find anything in the docs. Otherwise, this can be closed as a duplicate of the larger effort, #101100.
picnixz commentedon Aug 18, 2025
AFAIR, no. The
methrole needs to be used in the context of a class, whether it's via currentclass (which I don't remember whether it's supported or an open PR on Sphinx' side) or if it's inside a.. class::directive. We don't have a "global" class beingobject. What can be achieved is to create an extension that replaces those occurrences with the correct one (that can be easily achieved with RST pre-processing but this still requires the source to be processed so we might slow down a bit the docs).An alternative is to replace all
:meth:`__dunder__`by|\_\_dunder\_\_|and define.. |__dunder__| replace:: :meth:`~object.__dunder__`. This is the same as writing the extension but the substitution phase always runs (I think we just do some huge str.replace()).StanFromIreland commentedon Aug 18, 2025
I guess we can close then, as replacing them all with something else is the same as fixing them properly (without the additional disadvantages).