PEP 1, 12: Update for adoption of PEP 676, and fix a few related items (#2447)

* PEP 1, 12: Update outdated references to Docutils to point to Sphinx

* PEP 1, 12: Update and simplify outdated legacy rendering workflow steps

* Readme: Fix minor issues introduced in PR #2399

* Infra: Update contents to include PEP rendering docs and avoid warnings

* Lint: Update hardcoded PEP link checker to detect new PEP URLs

Author: CAM-Gerlach

.pre-commit-config.yaml

@@ -136,9 +136,9 @@ repos:
       - id: check-direct-pep-links
         name: "Check that PEPs aren't linked directly"
         language: pygrep
-        entry: 'dev/peps/pep-\d+'
+        entry: '(dev/peps|peps\.python\.org)/pep-\d+'
         files: '^pep-\d+\.(rst|txt)$'
-        exclude: '^pep-(0009|0287|8001)\.(rst|txt)$'
+        exclude: '^pep-(0009|0287|0676|8001)\.(rst|txt)$'
         types: [text]
       - id: check-direct-rfc-links
         name: "Check that RFCs aren't linked directly"

README.rst

@@ -28,7 +28,8 @@ Render PEPs locally
 -------------------
 
 See the `build documentation <./docs/build.rst>`__ for full
-instructions on how to render PEPs locally. In summary:
+instructions on how to render PEPs locally.
+In summary, run the following in a fresh, activated virtual environment:
 
 .. code-block:: bash
 
@@ -38,15 +39,14 @@ instructions on how to render PEPs locally. In summary:
     # Render the PEPs
     make render
 
-    # or, if you don't have 'make':
-    python3 build.py
-
+    # Or, if you don't have 'make':
+    python build.py
 
 The output HTML is found under the ``build`` directory.
 
 
-Tools to lint PEPs
-------------------
+Check and lint PEPs
+-------------------
 
 You can check for and fix common linting and spelling issues,
 either on-demand or automatically as you commit, with our pre-commit suite.

contents.rst

@@ -4,8 +4,7 @@
 Python Enhancement Proposals (PEPs)
 ***********************************
 
-
-This is an internal Sphinx page, please go to the :doc:`PEP Index <pep-0000>`.
+This is an internal Sphinx page; please go to the :doc:`PEP Index <pep-0000>`.
 
 
 .. toctree::
@@ -15,4 +14,5 @@ This is an internal Sphinx page, please go to the :doc:`PEP Index <pep-0000>`.
    :glob:
    :caption: PEP Table of Contents (needed for Sphinx):
 
-   pep-*
+   docs/*
+   pep-*

pep-0001.txt

@@ -26,7 +26,9 @@ documenting dissenting opinions.
 
 Because the PEPs are maintained as text files in a versioned
 repository, their revision history is the historical record of the
-feature proposal [1]_.
+feature proposal. This historical record is available by the normal git
+commands for retrieving older revisions, and can also be browsed
+`on GitHub <https://github.com/python/peps>`__.
 
 
 PEP Audience
@@ -285,8 +287,8 @@ the PEP Sponsor and PEP editors can advise them accordingly.
 
 If the chosen venue is not the `Python-Dev`_ mailing list,
 a brief announcement should be posted there when the draft PEP is
-committed to the PEP repository and available on the PEP website,
-with a link to the rendered PEP and to the canonical ``Discussions-To`` thread.
+committed to the repository, which should include a link to the rendered PEP
+and to the canonical ``Discussions-To`` thread.
 
 If a PEP undergoes a significant re-write or other major, substantive
 changes to its proposed specification, a new thread should typically be created
@@ -572,11 +574,11 @@ PEP Formats and Templates
 PEPs are UTF-8 encoded text files using the reStructuredText_ format.
 reStructuredText allows for rich markup that is still quite easy to
 read, but also results in good-looking and functional HTML. :pep:`12`
-contains instructions and a :pep:`template <12#suggested-sections>`
-for reStructuredText PEPs.
+contains instructions and a :pep:`PEP template <12#suggested-sections>`.
 
 The PEP text files are automatically
 `converted to HTML <https://peps.python.org/docs/rendering_system/>`__
+(via a `Sphinx <https://www.sphinx-doc.org/>`_-based :pep:`build system <676>`)
 for easier `online reading <https://peps.python.org/>`__.
 
 
@@ -795,22 +797,13 @@ Once the PEP is ready for the repository, a PEP editor will:
   ("Standards Track", "Informational", or "Process"), and marked its
   status as "Draft".
 
-* Add the PEP to a local fork of the `PEP repository`_.  For workflow
-  instructions, follow `The Python Developers Guide <https://devguide.python.org/>`_
+* Ensure all CI build and lint checks pass without errors,
+  and there are no obvious issues in the rendered preview output.
 
-* Run ``./build.py`` to ensure the PEPs are generated without errors. If the
-  rendering triggers errors, then the web site will not be updated to reflect
-  the PEP changes.
+* Merge the new (or updated) PEP.
 
-* Commit and push the new (or updated) PEP
-
-* Monitor python.org to make sure the PEP gets added to the site
-  properly. If it fails to appear, running ``make`` will build all of the
-  current PEPs. If any of these are triggering errors, they must be
-  corrected before any PEP will update on the site.
-
-* Send email back to the PEP author with next steps (post to
-  python-list & -dev).
+* Inform the author of the next steps (open a discussion thread and
+  update the PEP with it, post an announcement to Python-Dev, etc).
 
 Updates to existing PEPs should be submitted as a `GitHub pull request`_.
 
@@ -835,19 +828,13 @@ Resources:
 Footnotes
 =========
 
-.. [1] This historical record is available by the normal git commands
-   for retrieving older revisions, and can also be browsed
-   `on GitHub <https://github.com/python/peps>`__.
-
 .. _.github/CODEOWNERS: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 
 .. _issue tracker: https://bugs.python.org/
 
 .. _CC0-1.0-Universal: https://choosealicense.com/licenses/cc0-1.0/
 
-.. _reStructuredText: https://docutils.sourceforge.io/rst.html
-
-.. _Docutils: https://docutils.sourceforge.io/
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
 
 .. _PEP repository: https://github.com/python/peps
 

pep-0012.rst

@@ -154,8 +154,10 @@ directions below.
 - Update your Footnotes section, listing any footnotes and
   non-inline link targets referenced by the text.
 
-- Create a pull request against the https://github.com/python/peps
-  repository.
+- Run ``./build.py`` to ensure the PEP is rendered without errors,
+  and check that the output in ``build/pep-9999.html`` looks as you intend.
+
+- Create a pull request against the `PEPs repository`_.
 
 For reference, here are all of the possible header fields (everything
 in brackets should either be replaced or have the field removed if
@@ -680,33 +682,32 @@ Various sections are found to be common across PEPs and are outlined in
 Resources
 =========
 
-Many other constructs and variations are possible.  For more details
-about the reStructuredText markup, in increasing order of
-thoroughness, please see:
-
-* `A ReStructuredText Primer`__, a gentle introduction.
-
-  __ https://docutils.sourceforge.io/docs/user/rst/quickstart.html
-
-* `Quick reStructuredText`__, a users' quick reference.
+Many other constructs and variations are possible,
+both those supported by basic `Docutils <https://docutils.sourceforge.io/>`_
+and the extensions added by `Sphinx <https://www.sphinx-doc.org/>`_.
 
-  __ https://docutils.sourceforge.io/docs/user/rst/quickref.html
+A number of resources are available to learn more about them:
 
-* `reStructuredText Markup Specification`__, the final authority.
+* `Sphinx ReStructuredText Primer
+  <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_,
+  a gentle but fairly detailed introduction.
 
-  __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+* `reStructuredText Markup Specification
+  <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`_,
+  the authoritative, comprehensive documentation of the basic reST syntax,
+  directives, roles and more.
 
-The processing of reStructuredText PEPs is done using Docutils_.  If
-you have a question or require assistance with reStructuredText or
-Docutils, please `post a message`_ to the `Docutils-users mailing
-list`_.  The `Docutils project web site`_ has more information.
+* `Sphinx Roles
+  <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_
+  and `Sphinx Directives
+  <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_,
+  the extended constructs added by the Sphinx documentation system used to
+  render the PEPs to HTML.
 
-.. _Docutils:
-.. _Docutils project web site: https://docutils.sourceforge.io/
-.. _post a message:
-   mailto:[email protected]?subject=PEPs
-.. _Docutils-users mailing list:
-   https://docutils.sourceforge.io/docs/user/mailing-lists.html#docutils-users
+If you have questions or require assistance with writing a PEP that the above
+resources don't address, ping ``@python/pep-editors`` on GitHub, open an
+`issue on the PEPs repository <https://github.com/python/peps/issues>`_
+or reach out to a PEP editor directly.
 
 
 Copyright

pep-0685.rst

@@ -77,7 +77,8 @@ Specification
 =============
 
 When comparing extra names, tools MUST normalize the names being compared
-using the semantics outlined in `PEP 503 for names <https://peps.python.org/pep-0503/#normalized-names>`__::
+using the semantics outlined in :pep:`PEP 503 <0503#normalized-names>`
+for names::
 
     re.sub(r"[-_.]+", "-", name).lower()
 
@@ -89,8 +90,8 @@ metadata version increase to ``2.3``.
 
 For tools writing `core metadata`_,
 they MUST write out extra names in their normalized form.
-This applies to the `Provides-Extra`_ field and the `extra marker`_
-when used in the `Requires-Dist`_ field.
+This applies to the `Provides-Extra`_ field and the
+:pep:`extra marker <0508#extras>` when used in the `Requires-Dist`_ field.
 
 Tools generating metadata MUST raise an error if a user specified
 two or more extra names which would normalize to the same name.
@@ -186,7 +187,6 @@ CC0-1.0-Universal license, whichever is more permissive.
 
 
 .. _core metadata: https://packaging.python.org/en/latest/specifications/core-metadata/
-.. _extra marker: https://peps.python.org/pep-0508/#extras
 .. _Name: https://packaging.python.org/en/latest/specifications/core-metadata/#name
 .. _packaging project: https://packaging.pypa.io
 .. _Provides-Extra: https://packaging.python.org/en/latest/specifications/core-metadata/#provides-extra-multiple-use