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:

This gives us the hyperlink everywhere a PEP is referenced?

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 :/

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

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.

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.

@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.

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.

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

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.

New changeset 12e696b4f071ffe0d585b7f0d0d8020fd328bfdd by Brett Cannon (Stéphane Wirtel) in branch 'master':
bpo-35042: Use the :pep: role where a PEP is specified (#10036)
https://github.com/python/cpython/commit/12e696b4f071ffe0d585b7f0d0d8020fd328bfdd