classification
Title: Use the role :pep: for the PEP \d+
Type: Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brett.cannon, docs@python, eric.araujo, matrixise, mdk, serhiy.storchaka, thatiparthy, xtreak
Priority: normal Keywords: patch

Created on 2018-10-22 08:11 by matrixise, last changed 2018-10-28 07:46 by mdk. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 10036 merged matrixise, 2018-10-22 09:47
Messages (11)
msg328240 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2018-10-22 08:11
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:
msg328246 - (view) Author: Srinivas Reddy Thatiparthy(శ్రీనివాస్ రెడ్డి తాటిపర్తి) (thatiparthy) * Date: 2018-10-22 11:38
This gives us the hyperlink everywhere a PEP is referenced?
msg328247 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2018-10-22 11:47
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 :/
msg328251 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-10-22 12:47
What is wrong with the current code? Why replace :PEP: with :pep:?
msg328252 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2018-10-22 12:54
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.
msg328256 - (view) Author: Srinivas Reddy Thatiparthy(శ్రీనివాస్ రెడ్డి తాటిపర్తి) (thatiparthy) * Date: 2018-10-22 14:46
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.
msg328257 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2018-10-22 14:53
@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.
msg328258 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-10-22 14:57
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.
msg328266 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2018-10-22 17:34
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
msg328605 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2018-10-26 21:01
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.
msg328614 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2018-10-26 22:58
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
History
Date User Action Args
2018-10-28 07:46:04mdksetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-10-26 22:58:35brett.cannonsetnosy: + brett.cannon
messages: + msg328614
2018-10-26 21:01:52eric.araujosetnosy: + eric.araujo
messages: + msg328605
2018-10-22 17:34:00xtreaksetnosy: + xtreak
messages: + msg328266
2018-10-22 14:57:58mdksetnosy: + mdk
messages: + msg328258
2018-10-22 14:53:58matrixisesetmessages: + msg328257
2018-10-22 14:46:14thatiparthysetmessages: + msg328256
2018-10-22 12:54:19matrixisesetmessages: + msg328252
2018-10-22 12:47:52serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg328251
2018-10-22 11:47:27matrixisesetmessages: + msg328247
2018-10-22 11:38:00thatiparthysetnosy: + thatiparthy
messages: + msg328246
2018-10-22 09:47:52matrixisesetkeywords: + patch
stage: patch review
pull_requests: + pull_request9374
2018-10-22 08:11:03matrixisecreate