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/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. 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-* diff --git a/pep-0001.txt b/pep-0001.txt index 8aeccfbdf39..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 @@ -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 `__ +(via a `Sphinx `_-based :pep:`build system <676>`) for easier `online reading `__. @@ -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,19 +824,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 `__. - .. _.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 diff --git a/pep-0012.rst b/pep-0012.rst index f40b3d0b548..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 @@ -657,33 +659,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 `_ +and the extensions added by `Sphinx `_. - __ 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 + `_, + a gentle but fairly detailed introduction. - __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +* `reStructuredText Markup Specification + `_, + 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 + `_ + and `Sphinx Directives + `_, + 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:docutils-users@lists.sourceforge.net?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 `_ +or reach out to a PEP editor directly. Copyright 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