From a23937e2374fd23db269f1eec1457a6c19286959 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Fri, 18 Mar 2022 22:28:48 -0500 Subject: [PATCH 1/5] PEP 1, 12: Update outdated references to Docutils to point to Sphinx --- pep-0001.txt | 8 +++----- pep-0012.rst | 53 ++++++++++++++++++++++++++-------------------------- 2 files changed, 29 insertions(+), 32 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 8aeccfbdf39..448682e5249 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -572,11 +572,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 `__ +(via a `Sphinx `_-based :pep:`build system <676>`) for easier `online reading `__. @@ -841,9 +841,7 @@ Footnotes .. _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 diff --git a/pep-0012.rst b/pep-0012.rst index f40b3d0b548..b148ae4d9e8 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -657,33 +657,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. - - __ https://docutils.sourceforge.io/docs/user/rst/quickref.html - -* `reStructuredText Markup Specification`__, the final authority. - - __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html - -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. - -.. _Docutils: -.. _Docutils project web site: https://docutils.sourceforge.io/ -.. _post a message: - mailto:docutils-users@lists.sourceforge.net?subject=PEPs -.. _Docutils-users mailing list: - https://docutils.sourceforge.io/docs/user/mailing-lists.html#docutils-users +Many other constructs and variations are possible, +both those supported by basic `Docutils `_ +and the extensions added by `Sphinx `_. + +A number of resources are available to learn more about them: + +* `Sphinx ReStructuredText Primer + `_, + a gentle but fairly detailed introduction. + +* `reStructuredText Markup Specification + `_, + the authoritative, comprehensive documentation of the basic reST syntax, + directives, roles and more. + +* `Sphinx Roles + `_ + and `Sphinx Directives + `_, + the extended constructs added by the Sphinx documentation system used to + render the PEPs to HTML. + +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 `_ +or reach out to a PEP editor directly. Copyright From 046faf756900078defb29df5fd92a770bda8e819 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Fri, 18 Mar 2022 22:46:18 -0500 Subject: [PATCH 2/5] PEP 1, 12: Update and simplify outdated legacy rendering workflow steps --- pep-0001.txt | 31 ++++++++++--------------------- pep-0012.rst | 6 ++++-- 2 files changed, 14 insertions(+), 23 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 448682e5249..52375c56094 100644 --- a/pep-0001.txt +++ b/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 `__. 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 @@ -791,22 +793,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 `_ +* 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`_. @@ -831,10 +824,6 @@ Resources: Footnotes ========= -.. [1] This historical record is available by the normal git commands - for retrieving older revisions, and can also be browsed - `on GitHub `__. - .. _.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/ diff --git a/pep-0012.rst b/pep-0012.rst index b148ae4d9e8..d7a91c869dc 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -152,8 +152,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 From 0ce267773ead0855e40a68892ea8c8d190c17304 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Fri, 18 Mar 2022 23:02:30 -0500 Subject: [PATCH 3/5] Readme: Fix minor issues introduced in PR #2399 --- README.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index acc7250f67c..8e481451132 100644 --- a/README.rst +++ b/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. From 632deb91c0fffcba81c5f5a047b667af2b13d2b1 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Fri, 18 Mar 2022 23:08:52 -0500 Subject: [PATCH 4/5] Infra: Update contents to include PEP rendering docs and avoid warnings --- contents.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/contents.rst b/contents.rst index 94295408341..aa1bf01d493 100644 --- a/contents.rst +++ b/contents.rst @@ -4,8 +4,7 @@ Python Enhancement Proposals (PEPs) *********************************** - -This is an internal Sphinx page, please go to the :doc:`PEP Index `. +This is an internal Sphinx page; please go to the :doc:`PEP Index `. .. toctree:: @@ -15,4 +14,5 @@ This is an internal Sphinx page, please go to the :doc:`PEP Index `. :glob: :caption: PEP Table of Contents (needed for Sphinx): - pep-* \ No newline at end of file + docs/* + pep-* From 51913e0a325ae991f1963be424b8174bfda3c4c1 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Fri, 18 Mar 2022 23:21:22 -0500 Subject: [PATCH 5/5] Lint: Update hardcoded PEP link checker to detect new PEP URLs --- .pre-commit-config.yaml | 4 ++-- pep-0685.rst | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 61d63be9f6f..8a503bab566 100644 --- a/.pre-commit-config.yaml +++ b/.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" diff --git a/pep-0685.rst b/pep-0685.rst index 020aa33a825..c5d8996ea9e 100644 --- a/pep-0685.rst +++ b/pep-0685.rst @@ -76,7 +76,8 @@ Specification ============= When comparing extra names, tools MUST normalize the names being compared -using the semantics outlined in `PEP 503 for names `__:: +using the semantics outlined in :pep:`PEP 503 <0503#normalized-names>` +for names:: re.sub(r"[-_.]+", "-", name).lower() @@ -88,8 +89,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. @@ -185,7 +186,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