One-line summary
This discusses rationale for creating peps.python.org
as a stand alone site to host PEPs, replacing the current systems.
Summary:
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 python/peps
repository.
Current status:
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.
Reducing distributed configuration and simplifying tooling:
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.
Quality-of-life improvements and resolving issues:
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.
Potential alternatives
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.
Specific proposed implementation
As the proposed system uses Sphinx, any static file hosting solution could be used for peps.python.org – this could also be behind a CDN for example as there is no dynamic content, and the only optional JavaScript is for a single cosmetic change.
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.
A
Thanks,
Adam
References:
General
Initial 2016 issues
This proposal’s implementation
peps#1930
peps#1931
peps#1932
peps#1933
peps#1934
Quality of life improvements
Syntax highlighting and .. code-block::
pythondotorg#1063
pythondotorg#1206
pythondotorg#1638
peps#159
comment in peps#1571
peps#1577