Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
matrixise opened this issue Oct 22, 2018 · 11 comments
Closed

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

matrixise opened this issue Oct 22, 2018 · 11 comments
Labels
3.7 (EOL) end of life 3.8 (EOL) end of life docs Documentation in the Doc dir

Comments

@matrixise
Copy link
Member

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
    Copy link
    Member Author

    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:

    @matrixise matrixise added 3.7 (EOL) end of life 3.8 (EOL) end of life labels Oct 22, 2018
    @matrixise matrixise added the docs Documentation in the Doc dir label Oct 22, 2018
    @srinivasreddy
    Copy link
    Mannequin

    srinivasreddy mannequin commented Oct 22, 2018

    This gives us the hyperlink everywhere a PEP is referenced?

    @matrixise
    Copy link
    Member Author

    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
    Copy link
    Member

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

    @matrixise
    Copy link
    Member Author

    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
    Copy link
    Mannequin

    srinivasreddy mannequin commented Oct 22, 2018

    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
    Copy link
    Member Author

    @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
    Copy link
    Member

    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
    Copy link
    Member

    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
    Copy link
    Member

    merwok commented Oct 26, 2018

    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
    Copy link
    Member

    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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    AA-Turner pushed a commit to AA-Turner/devguide that referenced this issue Sep 13, 2023
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.7 (EOL) end of life 3.8 (EOL) end of life docs Documentation in the Doc dir
    Projects
    None yet
    Development

    No branches or pull requests

    6 participants