From cd4e570ffaaf820ab01f89920838b2c2e10439eb Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sat, 18 Dec 2021 22:38:28 -0600 Subject: [PATCH 1/3] PEP 676: Apply basic formatting, spelling, syntax & proofreading fixes --- pep-0676.rst | 60 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 24 deletions(-) diff --git a/pep-0676.rst b/pep-0676.rst index da3545d742b..77185dc791b 100644 --- a/pep-0676.rst +++ b/pep-0676.rst @@ -9,20 +9,22 @@ Content-Type: text/x-rst Created: 01-Nov-2021 Post-History: 23-Sep-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 web pages. 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 +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 `python.org`_ website periodically. This places a constraint on the `python.org`_ website to handle raw HTML @@ -33,15 +35,15 @@ This PEP provides a specification for self-contained rendering of PEPs. This would: * reduce the amount of distributed configuration for supporting PEPs -* enable quality-of-life improvements for those who read, write, and review - PEPs +* enable quality-of-life improvements for those who read, write and review PEPs * 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`` 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. + Rationale ========= @@ -50,12 +52,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. +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. Using a single repository to host all tooling will clarify where to raise issues, reducing volunteer time spent in triage. @@ -64,6 +66,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 ------------------------------------------------- @@ -74,7 +77,7 @@ There are several requests for additional features in reading PEPs, such as: * support for SVG images [3]_ * typographic quotation marks [4]_ * additional footer information [5]_ -* intersphinx functionality [6]_ +* 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 @@ -90,22 +93,23 @@ 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 +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 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 .. code-block:: nginx @@ -122,21 +126,24 @@ The following redirect rules must be created from the `python.org`_ domain: } Redirects must be implemented to preserve `URL fragments`_ for backward -compatability purposes. +compatibility purposes. + Backwards Compatibility ======================= Due to server-side redirects to new canonical URLs, there are no backwards -compatability concerns. Links in previously published materials referring to +compatibility concerns. Links in previously published materials referring to any old URL scheme will be guaranteed to work. + Security Implications ===================== No security implications, and the main `python.org`_ website will no longer take raw HTML uploads, closing a potential threat vector. + How to Teach This ================= @@ -144,6 +151,7 @@ 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. + Reference Implementation ======================== @@ -151,6 +159,7 @@ 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. + Rejected Ideas ============== @@ -164,25 +173,26 @@ 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 =========== None. -Acknowledgements -================ + +Acknowledgments +=============== Thanks to Hugo van Kemenade, Pablo Galindo Salgado, and Éric Araujo for support since April 2020. + 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 -.. _peps.python.org: https://peps.python.org/ -.. _peps.python.org/pep-0008/: https://peps.python.org/pep-0008/ .. _python.org: https://www.python.org .. _python/peps: https://github.com/python/peps .. _Read the Docs: https://readthedocs.org @@ -218,12 +228,14 @@ Footnotes `peps#1933 `__, `peps#1934 `__ + Copyright ========= This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. + .. Local Variables: From 03c9c6bc6547f5466d8c55036776b4f43f5b8a00 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sat, 18 Dec 2021 23:06:55 -0600 Subject: [PATCH 2/3] PEP 676: Copyedit text for clarity, grammar, readibility and meaning --- pep-0676.rst | 70 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 40 insertions(+), 30 deletions(-) diff --git a/pep-0676.rst b/pep-0676.rst index 77185dc791b..da391356077 100644 --- a/pep-0676.rst +++ b/pep-0676.rst @@ -55,9 +55,9 @@ 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 `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 environment. Using a single repository to host all tooling will clarify where to raise issues, reducing volunteer time spent in triage. @@ -81,16 +81,17 @@ There are several requests for additional features in reading PEPs, such as: 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 +example, the new reference implementation no longer requires a scheduled render process to run, instead initiating rendering on every commit to the `python/peps`_ repository. -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. +Equally, there are a number of broken items currently; for example, list styles +are not respected, and support for updating images is challenging with the +current system [7]_. These are solved by the reference implementation of +this proposal. -Commercial providers such as `Read the Docs`_ can additionally enhance this -experience, for example by providing rendered previews of changes in pull +Third-party providers such as `Read the Docs`_ can additionally enhance this +experience; for example, by providing rendered previews of changes in pull requests. @@ -100,17 +101,19 @@ 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 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 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 +The following Nginx configuration would achieve this: + .. code-block:: nginx location ~ ^/dev/peps/?(.*)$ { @@ -125,23 +128,28 @@ 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 new canonical URLs, links in previously +published materials referring to the old URL scheme will be guaranteed to work. +Furthermore, aside from the resolved bugs and new implemented features, all +existing PEPs will still render as they did before with the new backend. +Therefore, this poses no major backwards compatibility concerns. 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 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, +there is no forseen negative security impact. How to Teach This @@ -149,29 +157,31 @@ 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 to include and +document any relevant new roles, directive, syntax and other constructs enabled +by this change. 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 currently automatically renders all +PEPs on every commit. 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 -issue mitigations mentioned above. However, we do not believe that this would +It would likely be possible to amend the current docutils-based manual +rendering process to include many of the quality-of-life improvements and +bug 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 the existing `python.org`_ domain. We would argue, however, +that this would be the worst of both worlds, as a great deal of complexity +is added, while none is removed. Open Issues @@ -183,8 +193,8 @@ None. Acknowledgments =============== -Thanks to Hugo van Kemenade, Pablo Galindo Salgado, and Éric Araujo for support -since April 2020. +Thanks to Hugo van Kemenade, Pablo Galindo Salgado and Éric Araujo for +supporting this effort since April 2020. Footnotes From 6263951b376c273a34a1fc5e973223b61415a0f6 Mon Sep 17 00:00:00 2001 From: CAM Gerlach Date: Sun, 19 Dec 2021 18:34:58 -0600 Subject: [PATCH 3/3] 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