Many broken :meth: roles in the docs

[JelleZijlstra]

BPO	47255
Nosy	@JelleZijlstra, @Fidget-Spinner
PRs	bpo-47255: fix method references in functions.rst #32409

^{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']

[JelleZijlstra]

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]

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]

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.