diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a98015fbd..62b0351bf 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -127,3 +127,16 @@ repos: args: ['--multiline'] files: '^pep-\d+\.(rst|txt)$' types: [text] + - id: check-direct-pep-links + name: "Check that PEPs aren't linked directly" + language: pygrep + entry: 'dev/peps/pep-\d+' + files: '^pep-\d+\.(rst|txt)$' + exclude: '^pep-(0009|0287|8001)\.(rst|txt)$' + types: [text] + - id: check-direct-rfc-links + name: "Check that RFCs aren't linked directly" + language: pygrep + entry: '(rfc-editor\.org|ietf\.org)/[\.\-_\?\&\#\w/]*[Rr][Ff][Cc][\-_]?\d+' + files: '\.(rst|txt)$' + types: [text] diff --git a/pep-0012.rst b/pep-0012.rst index 0ec4c1863..2be95b510 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -475,47 +475,50 @@ Footnotes containing the URLs from external targets will be generated automatically at the end of the References section of the PEP, along with footnote references linking the reference text to the footnotes. -Text of the form "PEP x" or "RFC x" (where "x" is a number) will be -linked automatically to the appropriate URLs. +To refer to PEPs or RFCs, always use the ``:pep:`` and ``:rfc:`` roles, +never hardcoded URLs. +For example: + +.. code-block:: rst + + See :pep:`1` for more information on how to write a PEP, + and :pep:`the Hyperlink section of PEP 12 <12#hyperlinks>` for how to link. + +This renders as: + + See :pep:`1` for more information on how to write a PEP, + and :pep:`the Hyperlink section of PEP 12 <12#hyperlinks>` for how to link. + +PEP numbers in the text are never padded, and there is a space (not a dash) +between "PEP" or "RFC" and the number; the above roles will take care of +that for you. Footnotes --------- Footnote references consist of a left square bracket, a number, a -right square bracket, and a trailing underscore:: +right square bracket, and a trailing underscore: + +.. code-block:: rst This sentence ends with a footnote reference [1]_. Whitespace must precede the footnote reference. Leave a space between the footnote reference and the preceding word. -When referring to another PEP, include the PEP number in the body -text, such as "PEP 1". The title may optionally appear. Add a -footnote reference following the title. For example:: - - Refer to PEP 1 [2]_ for more information. - -Add a footnote that includes the PEP's title and author. It may -optionally include the explicit URL on a separate line, but only in -the References section. Footnotes begin with ".. " (the explicit +Footnotes begin with ".. " (the explicit markup start), followed by the footnote marker (no underscores), -followed by the footnote body. For example:: +followed by the footnote body. For example: + +.. code-block:: rst References ========== - .. [2] PEP 1, "PEP Purpose and Guidelines", Warsaw, Hylton - (http://www.python.org/dev/peps/pep-0001) + .. [1] Note that the footnote reference is a numbered one. -If you decide to provide an explicit URL for a PEP, please use this as -the URL template:: - - http://www.python.org/dev/peps/pep-xxxx - -PEP numbers in URLs must be padded with zeros from the left, so as to -be exactly 4 characters wide; however, PEP numbers in the text are -never padded. + .. [2] Donald Knuth's *The TeXbook*, pages 195 and 196. During the course of developing your PEP, you may have to add, remove, and rearrange footnote references, possibly resulting in mismatched @@ -523,20 +526,20 @@ references, obsolete footnotes, and confusion. Auto-numbered footnotes allow more freedom. Instead of a number, use a label of the form "#word", where "word" is a mnemonic consisting of alphanumerics plus internal hyphens, underscores, and periods (no whitespace or -other characters are allowed). For example:: +other characters are allowed). For example: - Refer to PEP 1 [#PEP-1]_ for more information. +.. code-block:: rst + + Refer to The TeXbook [#TeXbook]_ for more information. References ========== - .. [#PEP-1] PEP 1, "PEP Purpose and Guidelines", Warsaw, Hylton + .. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196. - http://www.python.org/dev/peps/pep-0001 Footnotes and footnote references will be numbered automatically, and -the numbers will always match. Once a PEP is finalized, auto-numbered -labels should be replaced by numbers for simplicity. +the numbers will always match. Images diff --git a/pep-0340.txt b/pep-0340.txt index 8c908e7c8..770def06c 100644 --- a/pep-0340.txt +++ b/pep-0340.txt @@ -461,7 +461,7 @@ accepted, these can be changed to just "yield" of course.) Used as follows:: block auto_retry(3, IOError): - f = urllib.urlopen("http://www.python.org/dev/peps/pep-0340/") + f = urllib.urlopen("https://www.example.com/") print f.read() 5. It is possible to nest blocks and combine templates:: diff --git a/pep-0427.txt b/pep-0427.txt index bb7703175..4b40773e8 100644 --- a/pep-0427.txt +++ b/pep-0427.txt @@ -312,9 +312,9 @@ checker only needs to establish that RECORD matches the signature. See -- https://datatracker.ietf.org/doc/html/rfc7515 +- :rfc:`7515` - https://datatracker.ietf.org/doc/html/draft-jones-jose-jws-json-serialization.html -- https://datatracker.ietf.org/doc/html/rfc7517 +- :rfc:`7517` - https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key.html diff --git a/pep-0491.txt b/pep-0491.txt index 79436b8aa..1d20cc11e 100644 --- a/pep-0491.txt +++ b/pep-0491.txt @@ -394,9 +394,9 @@ checker only needs to establish that RECORD matches the signature. See -- https://datatracker.ietf.org/doc/html/rfc7515 +- :rfc:`7515` - https://datatracker.ietf.org/doc/html/draft-jones-jose-jws-json-serialization.html -- https://datatracker.ietf.org/doc/html/rfc7517 +- :rfc:`7517` - https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key.html