PEP 676: Formatting and prose updates (#2207)

Co-authored-by: C.A.M. Gerlach <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>

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,35 +81,39 @@ 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
 =============
 
 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 for the `python.org`_ domain:
 
-The following redirect rules must be created from 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,72 +129,87 @@ 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.
-
-Open Issues
-===========
+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.
 
-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
 =========
 
 .. _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
 =========