PEP 676: PEP Infrastructure Process (#2173)
This commit is contained in:
Adam Turner
GitHub
parent
b6e3845f4c
commit
54e9bd01a3
|
|
@ -530,6 +530,7 @@ pep-0672.rst @encukou
|
|||
pep-0673.rst @jellezijlstra
|
||||
pep-0674.rst @vstinner
|
||||
pep-0675.rst @jellezijlstra
|
||||
pep-0676.rst @Mariatta
|
||||
# ...
|
||||
# pep-0754.txt
|
||||
# ...
|
||||
|
|
|
|||
|
|
@ -0,0 +1,235 @@
|
|||
PEP: 676
|
||||
Title: PEP Infrastructure Process
|
||||
Author: Adam Turner <python@quite.org.uk>
|
||||
Sponsor: Mariatta <mariatta@python.org>
|
||||
Discussions-To: https://discuss.python.org/t/10774
|
||||
Status: Draft
|
||||
Type: Process
|
||||
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
|
||||
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
|
||||
`python.org`_ website periodically.
|
||||
|
||||
This places a constraint on the `python.org`_ website to handle raw HTML
|
||||
uploads and handle PEP rendering, and makes the appropriate place to raise
|
||||
issues unclear in some cases [1]_.
|
||||
|
||||
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
|
||||
* 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.
|
||||
|
||||
Rationale
|
||||
=========
|
||||
|
||||
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
|
||||
`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.
|
||||
|
||||
Using a single repository to host all tooling will clarify where to raise
|
||||
issues, reducing volunteer time spent in triage.
|
||||
|
||||
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
|
||||
-------------------------------------------------
|
||||
|
||||
There are several requests for additional features in reading PEPs, such as:
|
||||
|
||||
* syntax highlighting [2]_
|
||||
* use of ``.. code-block::`` directives [2]_
|
||||
* support for SVG images [3]_
|
||||
* typographic quotation marks [4]_
|
||||
* additional footer information [5]_
|
||||
* 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.
|
||||
|
||||
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.
|
||||
|
||||
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 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
|
||||
|
||||
.. code-block:: nginx
|
||||
|
||||
location ~ ^/dev/peps/?(.*)$ {
|
||||
return 308 https://peps.python.org/$1/;
|
||||
}
|
||||
|
||||
location ~ ^/peps/(.*)\.html$ {
|
||||
return 308 https://peps.python.org/$1/;
|
||||
}
|
||||
|
||||
location ^/(dev/)?peps(/.*)?$ {
|
||||
return 308 https://peps.python.org/;
|
||||
}
|
||||
|
||||
Redirects must be implemented to preserve `URL fragments`_ for backward
|
||||
compatability 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
|
||||
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
|
||||
=================
|
||||
|
||||
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
|
||||
========================
|
||||
|
||||
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
|
||||
==============
|
||||
|
||||
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
|
||||
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
|
||||
===========
|
||||
|
||||
None.
|
||||
|
||||
Acknowledgements
|
||||
================
|
||||
|
||||
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
|
||||
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
|
||||
.. _URL fragments: https://url.spec.whatwg.org/#concept-url-fragment
|
||||
|
||||
.. [1] For example,
|
||||
`pythondotorg#1024 <https://github.com/python/pythondotorg/issues/1204>`__,
|
||||
`pythondotorg#1038 <https://github.com/python/pythondotorg/issues/1038>`__,
|
||||
`pythondotorg#1387 <https://github.com/python/pythondotorg/issues/1387>`__,
|
||||
`pythondotorg#1388 <https://github.com/python/pythondotorg/issues/1388>`__,
|
||||
`pythondotorg#1393 <https://github.com/python/pythondotorg/issues/1393>`__,
|
||||
`pythondotorg#1564 <https://github.com/python/pythondotorg/issues/1564>`__,
|
||||
`pythondotorg#1913 <https://github.com/python/pythondotorg/issues/1913>`__,
|
||||
.. [2] Requested: `pythondotorg#1063 <https://github.com/python/pythondotorg/pull/1063>`__,
|
||||
`pythondotorg#1206 <https://github.com/python/pythondotorg/issues/1206>`__,
|
||||
`pythondotorg#1638 <https://github.com/python/pythondotorg/pull/1638>`__,
|
||||
`peps#159 <https://github.com/python/peps/issues/159>`__,
|
||||
`comment in peps#1571 <https://github.com/python/peps/pull/1571#discussion_r478701944>`__,
|
||||
`peps#1577 <https://github.com/python/peps/pull/1577>`__,
|
||||
.. [3] Requested: `peps#701 <https://github.com/python/peps/issues/701>`__
|
||||
.. [4] Requested: `peps#165 <https://github.com/python/peps/issues/165>`__
|
||||
.. [5] Requested: `pythondotorg#1564 <https://github.com/python/pythondotorg/issues/1564>`__
|
||||
.. [6] Requested: `comment in peps#2 <https://github.com/python/peps/issues/2#issuecomment-339195595>`__
|
||||
.. [7] As of November 2021, see
|
||||
`peps#1387 <https://github.com/python/peps/issues/1387>`__,
|
||||
`pythondotorg#824 <https://github.com/python/pythondotorg/issues/824>`__,
|
||||
`pythondotorg#1556 <https://github.com/python/pythondotorg/pull/1556>`__,
|
||||
.. [8] Implementation PRs:
|
||||
`peps#1930 <https://github.com/python/peps/pull/1930>`__,
|
||||
`peps#1931 <https://github.com/python/peps/pull/1931>`__,
|
||||
`peps#1932 <https://github.com/python/peps/pull/1932>`__,
|
||||
`peps#1933 <https://github.com/python/peps/pull/1933>`__,
|
||||
`peps#1934 <https://github.com/python/peps/pull/1934>`__
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
This document is placed in the public domain or under the
|
||||
CC0-1.0-Universal license, whichever is more permissive.
|
||||
|
||||
|
||||
..
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
sentence-end-double-space: t
|
||||
fill-column: 70
|
||||
coding: utf-8
|
||||
End:
|
||||
Loading…
Reference in New Issue