This discusses rationale for creating
peps.python.org as a stand alone site to host PEPs, replacing the current systems.
Python Enhancement Proposals (PEPs) are currently rendered by running
docutils on each PEP document and are refreshed on python.org/dev/peps every 15 minutes.
This proposal would seek to make rendering of PEPs self-contained. 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 potential improvements
- save volunteer time in maintaining the current system
The proposed end state is that PEPs are accessed through peps.python.org at the top-level namespace (for example peps.python.org/pep-9999), and all tooling to support rendering PEPs is hosted in the
The proposed implementation has been merged into the
python/peps repository, and a rendered preview of all PEPs is available (python.github.io/peps). I was asked to write up this briefing by the PEP editors for consideration.
Currently, three Python repositories are involved in orchestrating the rendering process, using three separate technologies (
docutils, Django, Saltstack). The proposed implementation renders the PEPs using Sphinx and a custom Sphinx plugin.
As it is proposed to stand alone, the integration with
pythondotorg and associated update machinery can be removed, reducing cognitive load when reviewing issues with PEP rendering. Use of CI will also surface all build logs in one place, again useful when investigating problems.
By removing configuration in these other projects, volunteer time does not need to be spent maintaining more fragile linkages and complex distributed systems.
It may also reduce the barrier to entry to adding new features, as the scope of the PEP rendering tooling is well defined.
There are a number of requests for additional features in viewing PEPs, including syntax highlighting,
.. code-block:: directives, support for SVG images, typographic quotation marks, additional footer information, and inter-sphinx functionality. These are “easy wins” from this proposal, and would serve to improve the 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 current
pythondotorg system. These would be solved by default in the proposal.
Of note, I found a lot more such items that had been fixed in various ways by volunteers – which shows both their dedication and that such time investigating a fix might be better used elsewhere.
It would likely be possible to amend the current rendering process to include a lot of the quality-of-life improvements and issue mitigations mentioned above. However, I 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
pythondotorg. I would argue however that this would be the worst of both worlds, as a great deal of complexity is added, and none is removed.
Commercial vendors such as Read the Docs, Inc can provide additional services such as preview rendering, which may align with the quality-of-life piece.
The rendered PEPs would be made available at peps.python.org, with the current redirect configuration updated to point to the new canonical URLs.