PEP 676: Formatting and prose updates (#2207)
Co-authored-by: C.A.M. Gerlach <cam.gerlach@gerlach.cam> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
This commit is contained in:
Adam Turner
GitHub
parent
557696d143
commit
19684a0787
122
pep-0676.rst
122
pep-0676.rst
|
|
@ -7,22 +7,24 @@ Status: Draft
|
|||
Type: Process
|
||||
Content-Type: text/x-rst
|
||||
Created: 01-Nov-2021
|
||||
Post-History: 23-Sep-2021
|
||||
Post-History: 23-Sep-2021, 30-Nov-2021
|
||||
|
||||
|
||||
Abstract
|
||||
========
|
||||
|
||||
This PEP addresses the infrastructure around rendering PEP files from
|
||||
reStructuredText_ files to HTML webpages. We aim to specify a self-contained
|
||||
`reStructuredText`_ files to HTML webpages. We aim to specify a self-contained
|
||||
and maintainable solution for PEP readers, authors, and editors.
|
||||
|
||||
|
||||
Motivation
|
||||
==========
|
||||
|
||||
As of November 2021, Python Enhancement Proposals (PEPs) are rendered in a
|
||||
multi-system, multi-stage process. A continuous integration (CI) task runs a
|
||||
docutils_ script to render all PEP files individually. The CI task then uploads
|
||||
a tar archive to a server, where it is retrieved and rendered into the
|
||||
`docutils`_ script to render all PEP files individually. The CI task then
|
||||
uploads a tar archive to a server, where it is retrieved and rendered into the
|
||||
`python.org`_ website periodically.
|
||||
|
||||
This places a constraint on the `python.org`_ website to handle raw HTML
|
||||
|
|
@ -38,9 +40,10 @@ would:
|
|||
* solve a number of outstanding issues, and lay the path for improvements
|
||||
* save volunteer maintainers' time
|
||||
|
||||
We propose that PEPs are accessed through peps.python.org_ at the top-level
|
||||
namespace (for example `peps.python.org/pep-0008/`_), and that all custom
|
||||
tooling to support rendering PEPs is hosted in the `python/peps`_ repository.
|
||||
We propose that PEPs are accessed through `peps.python.org`_ at the top-level
|
||||
(for example `peps.python.org/pep-0008`_), and that all custom tooling to
|
||||
support rendering PEPs is hosted in the `python/peps`_ repository.
|
||||
|
||||
|
||||
Rationale
|
||||
=========
|
||||
|
|
@ -50,12 +53,12 @@ Simplifying and Centralising Infrastructure
|
|||
|
||||
As of November 2021, to locally render a PEP file, a PEP author or editor needs
|
||||
to create a full local instance of the `python.org`_ website and run a number
|
||||
of disparate scripts, following documentation_ that lives outside of the
|
||||
of disparate scripts, following `documentation`_ that lives outside of the
|
||||
`python/peps`_ repository.
|
||||
|
||||
The proposed implementation provides a single Makefile_ and a Python script to
|
||||
render all PEP files, with options to target a web-server or local filesystem
|
||||
environment.
|
||||
By contrast, the proposed implementation provides a single `Makefile`_ and a
|
||||
Python script to render all PEP files, with options to target a web-server or
|
||||
the local filesystem.
|
||||
|
||||
Using a single repository to host all tooling will clarify where to raise
|
||||
issues, reducing volunteer time spent in triage.
|
||||
|
|
@ -64,6 +67,7 @@ Simplified and centralised tooling may also reduce the barrier to entry to
|
|||
further improvements, as the scope of the PEP rendering infrastructure is well
|
||||
defined.
|
||||
|
||||
|
||||
Quality-of-Life Improvements and Resolving Issues
|
||||
-------------------------------------------------
|
||||
|
||||
|
|
@ -77,18 +81,21 @@ There are several requests for additional features in reading PEPs, such as:
|
|||
* intersphinx functionality [6]_
|
||||
|
||||
These are "easy wins" from this proposal, and would serve to improve the
|
||||
quality-of-life for consumers of PEPs (including reviewers and writers). For
|
||||
example, the reference implementation no longer requires a scheduled render
|
||||
process to run, instead initiating rendering on every commit to the
|
||||
`python/peps`_ repository.
|
||||
quality-of-life for consumers of PEPs (including reviewers and writers).
|
||||
|
||||
Equally, there are a small number of broken items, for example list styles not
|
||||
being respected or support for updating images being challenging with the
|
||||
system [7]_. These would be solved by default in the proposal.
|
||||
For example, the current (as of November 2021) system runs periodically on a
|
||||
schedule. This means that updates to PEPs cannot be circulated immediately,
|
||||
reducing productivity. The reference implementation renders and publishes all
|
||||
PEPs on every commit to the repository, solving the issue by design.
|
||||
|
||||
The reference implementation fixes several issues [7]_. For example:
|
||||
|
||||
* list styles are currently not respected by `python.org`_'s stylesheets
|
||||
* support for updating images in PEPs is challenging in `python.org`_
|
||||
|
||||
Third-party providers such as `Read the Docs`_ or `Netlify`_ can enhance this
|
||||
experience with features such as automatic rendering of pull requests.
|
||||
|
||||
Commercial providers such as `Read the Docs`_ can additionally enhance this
|
||||
experience, for example by providing rendered previews of changes in pull
|
||||
requests.
|
||||
|
||||
Specification
|
||||
=============
|
||||
|
|
@ -96,16 +103,17 @@ Specification
|
|||
The proposed specification for rendering the PEP files to HTML is as per the
|
||||
`reference implementation`_.
|
||||
|
||||
That the HTML files should be made available under peps.python.org_. The
|
||||
rendered files may be hosted just as static files, and behind a content
|
||||
delivery network (CDN).
|
||||
The rendered PEPs MUST be available at `peps.python.org`_. These SHOULD be
|
||||
hosted as static files, and MAY be behind a content delivery network (CDN).
|
||||
|
||||
The following redirect rules must be created from the `python.org`_ domain:
|
||||
The following redirect rules MUST be created for the `python.org`_ domain:
|
||||
|
||||
* /peps/ -> https://peps.python.org/
|
||||
* /dev/peps/ -> https://peps.python.org/
|
||||
* /peps/(.*)\.html -> https://peps.python.org/$1
|
||||
* /dev/peps/(.*) -> https://peps.python.org/$1
|
||||
* ``/peps/`` -> https://peps.python.org/
|
||||
* ``/dev/peps/`` -> https://peps.python.org/
|
||||
* ``/peps/(.*)\.html`` -> https://peps.python.org/$1
|
||||
* ``/dev/peps/(.*)`` -> https://peps.python.org/$1
|
||||
|
||||
The following nginx configuration would achieve this:
|
||||
|
||||
.. code-block:: nginx
|
||||
|
||||
|
|
@ -121,59 +129,71 @@ The following redirect rules must be created from the `python.org`_ domain:
|
|||
return 308 https://peps.python.org/;
|
||||
}
|
||||
|
||||
Redirects must be implemented to preserve `URL fragments`_ for backward
|
||||
Redirects MUST be implemented to preserve `URL fragments`_ for backward
|
||||
compatibility purposes.
|
||||
|
||||
Backwards Compatibility
|
||||
=======================
|
||||
|
||||
Due to server-side redirects to new canonical URLs, there are no backwards
|
||||
compatibility concerns. Links in previously published materials referring to
|
||||
any old URL scheme will be guaranteed to work.
|
||||
Due to server-side redirects to the new canonical URLs, links in previously
|
||||
published materials referring to the old URL schemes will be guaranteed to work.
|
||||
All PEPs will continue to render correctly, and a custom stylesheet in the
|
||||
reference implementation improves presentation for some elements (most notably
|
||||
code blocks and block quotes). Therefore, this PEP presents no backwards
|
||||
compatibility issues.
|
||||
|
||||
|
||||
Security Implications
|
||||
=====================
|
||||
|
||||
No security implications, and the main `python.org`_ website will no longer
|
||||
take raw HTML uploads, closing a potential threat vector.
|
||||
The main `python.org`_ website will no longer process raw HTML uploads,
|
||||
closing a potential threat vector. PEP rendering and deployment processes will
|
||||
use modern, well-maintained code and secure automated platforms, further
|
||||
reducing the potential attack surface. Therefore, we see no negative security
|
||||
impact.
|
||||
|
||||
|
||||
How to Teach This
|
||||
=================
|
||||
|
||||
The new canonical URLs will be publicised in the documentation. However, this
|
||||
is mainly a backend infrastructure change, and there should be minimal
|
||||
end-user impact.
|
||||
end-user impact. PEP 1 and PEP 12 will be updated as needed.
|
||||
|
||||
|
||||
Reference Implementation
|
||||
========================
|
||||
|
||||
The proposed implementation has been merged into the `python/peps`_ repository
|
||||
in a series of pull requests [8]_. This automatically renders all PEPs on every
|
||||
commit.
|
||||
in a series of pull requests [8]_. It uses the `Sphinx`_ documentation system
|
||||
with a custom theme and extensions.
|
||||
|
||||
This already automatically renders all PEPs on every commit, and publishes them
|
||||
to `python.github.io/peps`_.
|
||||
|
||||
|
||||
Rejected Ideas
|
||||
==============
|
||||
|
||||
It would likely be possible to amend the current (as of November 2021)
|
||||
rendering process to include a lot of the quality-of-life improvements and
|
||||
rendering process to include a subset of the quality-of-life improvements and
|
||||
issue mitigations mentioned above. However, we do not believe that this would
|
||||
solve the distributed tooling issue.
|
||||
|
||||
It would be possible to use the output from the proposed rendering system and
|
||||
import it into `python.org`_. We would argue however that this would be the
|
||||
worst of both worlds, as a great deal of complexity is added, and none is
|
||||
removed.
|
||||
import it into `python.org`_. We would argue that this would be the worst of
|
||||
both worlds, as a great deal of complexity is added whilst none is removed.
|
||||
|
||||
Open Issues
|
||||
===========
|
||||
|
||||
None.
|
||||
|
||||
Acknowledgements
|
||||
================
|
||||
|
||||
Thanks to Hugo van Kemenade, Pablo Galindo Salgado, and Éric Araujo for support
|
||||
since April 2020.
|
||||
- Hugo van Kemenade
|
||||
- Pablo Galindo Salgado
|
||||
- Éric Araujo
|
||||
- Mariatta
|
||||
- C.A.M. Gerlach
|
||||
|
||||
|
||||
Footnotes
|
||||
=========
|
||||
|
|
@ -181,12 +201,15 @@ Footnotes
|
|||
.. _documentation: https://pythondotorg.readthedocs.io/pep_generation.html
|
||||
.. _docutils: https://docutils.sourceforge.io
|
||||
.. _Makefile: https://www.gnu.org/software/make/manual/make.html#Introduction
|
||||
.. _Netlify: https://www.netlify.com/
|
||||
.. _peps.python.org: https://peps.python.org/
|
||||
.. _peps.python.org/pep-0008/: https://peps.python.org/pep-0008/
|
||||
.. _peps.python.org/pep-0008: https://peps.python.org/pep-0008/
|
||||
.. _python.github.io/peps: https://python.github.io/peps
|
||||
.. _python.org: https://www.python.org
|
||||
.. _python/peps: https://github.com/python/peps
|
||||
.. _Read the Docs: https://readthedocs.org
|
||||
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
|
||||
.. _Sphinx: https://www.sphinx-doc.org/en/master/
|
||||
.. _URL fragments: https://url.spec.whatwg.org/#concept-url-fragment
|
||||
|
||||
.. [1] For example,
|
||||
|
|
@ -218,6 +241,7 @@ Footnotes
|
|||
`peps#1933 <https://github.com/python/peps/pull/1933>`__,
|
||||
`peps#1934 <https://github.com/python/peps/pull/1934>`__
|
||||
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue