Use the role :pep: for the PEP \d+

[matrixise]

BPO	35042
Nosy	@brettcannon, @merwok, @serhiy-storchaka, @matrixise, @srinivasreddy, @JulienPalard, @tirkarthi
PRs	bpo-35042: Use the :pep: role where a PEP is specified #10036

^{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-10-28.07:46:04.839>
created_at = <Date 2018-10-22.08:11:03.222>
labels = ['3.7', '3.8', 'docs']
title = 'Use the role :pep: for the PEP \\d+'
updated_at = <Date 2018-10-28.07:46:04.838>
user = 'https://github.com/matrixise'

bugs.python.org fields:

activity = <Date 2018-10-28.07:46:04.838>
actor = 'mdk'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-10-28.07:46:04.839>
closer = 'mdk'
components = ['Documentation']
creation = <Date 2018-10-22.08:11:03.222>
creator = 'matrixise'
dependencies = []
files = []
hgrepos = []
issue_num = 35042
keywords = ['patch']
message_count = 11.0
messages = ['328240', '328246', '328247', '328251', '328252', '328256', '328257', '328258', '328266', '328605', '328614']
nosy_count = 8.0
nosy_names = ['brett.cannon', 'eric.araujo', 'docs@python', 'serhiy.storchaka', 'matrixise', 'thatiparthy', 'mdk', 'xtreak']
pr_nums = ['10036']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue35042'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[matrixise]

In the doc, we write PEP XYZ but there is a sphinx role for that, just replace PEP XYZ by :pep:`XYZ` and convert the :PEP: by :pep:

[srinivasreddy]

This gives us the hyperlink everywhere a PEP is referenced?

[matrixise]

sure, it's the default behavior of this role, I have a PR with the fix, but Github has a big issue with the PRs :/

[serhiy-storchaka]

What is wrong with the current code? Why replace :PEP: with :pep:?

[matrixise]

in fact, in the doc of Sphinx, it's just :pep: and not :PEP:

see http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html?highlight=%3Apep%3A#role-pep

in this case, I think it's better to use the "reference" and use pep in lowercase.

[srinivasreddy]

I am -0 on this. I want to hear a more compelling argument than wanting to leverage an existing feature.

IMHO, when i am reading the documentation i never bothered to go into the PEP docs - most of the times. I explicitly visited a PEP when i want to understand the rationale of a feature.

My 2 cents.

[matrixise]

@thatiparthy

When you start to contribute to Python, and you see there is a PEP in the doc.

1. What's a PEP?
2. Where can I find the PEP XYZ?
3. Am I on the right website for the PEP?

if you don't know the concept of the PEPs, you will check with your favorite search engine because you are a developer. This is not the case for everybody.

For a newcomer/beginner, read the right information just with a click, it's just the founding principles of the Web.

create a link is not a real problem for a computer and for the end-user will be happy.

[JulienPalard]

When mentionning a PEP I see no reason not to point to it, and as it's easy to do with the pep role, I'm +1 on this.

[tirkarthi]

If I am understanding this correctly the :pep: role is already present and only that PEP references that don't have this role are being updated now?

➜ cpython git:(master) rg ':pep:`\d+`' | grep 'rst' | grep -Ev 'NEWS|whatsnew' | wc
324 2686 27228

References that don't have the role are being updated along with :PEP: changed to :pep: in the PR? (Around 30 entries)

➜ cpython git:(master) rg 'PEP \d+' | grep 'rst' | grep -Ev 'NEWS|whatsnew' | wc
21 228 1891
➜ cpython git:(master) rg ':PEP:`\d+`' | grep 'rst' | grep -Ev 'NEWS|whatsnew' | wc
6 51 517

I think older NEWS entries can be left behind like the PR changes whatsnew for Python 2.0, 2.1, 2.5 and they won't be back ported I personally feel little value in changing them though doc changes have been done on those files in 2016 and up to the reviewer.

Thanks

[merwok]

Docutils itself parses RFC nnnn and PEP nnn to replace with links.

In some parts of the docs with many references, some devs (I think Raymond Hettinger for example) use tricks like PEP\ nnn to avoid getting twenty links in a row.

So I don’t see what the replacement of `PEP nnn` with `:pep:`nnn`` adds.

[brettcannon]

New changeset 12e696b by Brett Cannon (Stéphane Wirtel) in branch 'master':
bpo-35042: Use the :pep: role where a PEP is specified (bpo-10036)
12e696b