From 6263951b376c273a34a1fc5e973223b61415a0f6 Mon Sep 17 00:00:00 2001 From: CAM Gerlach Date: Sun, 19 Dec 2021 18:34:58 -0600 Subject: [PATCH] PEP 676: Apply reviewer suggestions to revert and refine textual tweaks Co-authored-by: Hugo van Kemenade --- pep-0676.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/pep-0676.rst b/pep-0676.rst index da391356077..fec30b51668 100644 --- a/pep-0676.rst +++ b/pep-0676.rst @@ -14,7 +14,7 @@ Abstract ======== This PEP addresses the infrastructure around rendering PEP files from -`reStructuredText`_ files to HTML web pages. 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. @@ -22,9 +22,9 @@ 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 +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 to a server, where it is retrieved and rendered into the +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 @@ -39,8 +39,8 @@ 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 +We propose that PEPs are accessed through `peps.python.org`_ as 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. @@ -101,11 +101,11 @@ Specification The proposed specification for rendering the PEP files to HTML is as per the `reference implementation`_. -The HTML files SHOULD be made available under the ``peps.python.org`` domain. +The HTML files SHOULD be made available under the `peps.python.org`_ domain. The rendered output 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/ @@ -148,7 +148,7 @@ Security Implications The main `python.org`_ website will no longer need to process raw HTML uploads, closing a potential threat vector, and the PEP building and deployment process will use modern, well maintained code and secure -automated platforms, reducing likely potential attack surface. Therefore, +automated platforms, reducing the likely potential attack surface. Therefore, there is no forseen negative security impact. @@ -204,6 +204,8 @@ Footnotes .. _docutils: https://docutils.sourceforge.io .. _Makefile: https://www.gnu.org/software/make/manual/make.html#Introduction .. _python.org: https://www.python.org +.. _peps.python.org: https://peps.python.org/ +.. _peps.python.org/pep-0008: https://peps.python.org/pep-0008/ .. _python/peps: https://github.com/python/peps .. _Read the Docs: https://readthedocs.org .. _reStructuredText: https://docutils.sourceforge.io/rst.html