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
This commit is contained in:
CAM Gerlach
GitHub
parent
a7332976a4
commit
d286a46470
|
|
@ -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"
|
||||
|
|
|
|||
12
README.rst
12
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.
|
||||
|
|
|
|||
|
|
@ -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-*
|
||||
|
|
|
|||
39
pep-0001.txt
39
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
|
||||
|
||||
|
|
|
|||
49
pep-0012.rst
49
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:
|
||||
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/>`_.
|
||||
|
||||
* `A ReStructuredText Primer`__, a gentle introduction.
|
||||
A number of resources are available to learn more about them:
|
||||
|
||||
__ https://docutils.sourceforge.io/docs/user/rst/quickstart.html
|
||||
* `Sphinx ReStructuredText Primer
|
||||
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_,
|
||||
a gentle but fairly detailed introduction.
|
||||
|
||||
* `Quick reStructuredText`__, a users' quick reference.
|
||||
* `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.
|
||||
|
||||
__ https://docutils.sourceforge.io/docs/user/rst/quickref.html
|
||||
* `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.
|
||||
|
||||
* `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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue