distutils: cyclic reference in the documentation

[matrixise]

BPO	32774
Nosy	@bitdancer, @matrixise
PRs	bpo-32774: distutils: cyclic reference in the documentation #5555

^{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 = <Date 2018-02-05.19:04:46.542>
created_at = <Date 2018-02-05.16:35:56.015>
labels = ['3.7', '3.8', 'docs']
title = 'distutils: cyclic reference in the documentation'
updated_at = <Date 2018-02-05.19:04:46.541>
user = 'https://github.com/matrixise'

bugs.python.org fields:

activity = <Date 2018-02-05.19:04:46.541>
actor = 'matrixise'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-02-05.19:04:46.542>
closer = 'matrixise'
components = ['Documentation']
creation = <Date 2018-02-05.16:35:56.015>
creator = 'matrixise'
dependencies = []
files = []
hgrepos = []
issue_num = 32774
keywords = ['patch']
message_count = 3.0
messages = ['311674', '311680', '311681']
nosy_count = 3.0
nosy_names = ['r.david.murray', 'docs@python', 'matrixise']
pr_nums = ['5555']
priority = 'normal'
resolution = None
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue32774'
versions = ['Python 2.7', 'Python 3.6', 'Python 3.7', 'Python 3.8']

[matrixise]

in the documentation of the distutils module, there is a cyclic references, just remove them because I think it's useless.

[bitdancer]

This is a common pattern in our documentation. It is done because ":mod:`xxx`" means that xxx should be formatted as a module name, rather than anything else. While it is true that the formatting for most such references is currently the same, it could be different in principle, and is for a few. It is in some ways unfortunate that it also always results in a link, so you will indeed find a number of places where the prefix is omitted, mostly commonly when the same entity is referenced several times in the same paragraph.

So, it is not completely clear cut, but I would recommend rejecting this and leaving the docs as is.

[matrixise]

ok, it's fine for me, I close this issue