This PEP addresses the infrastructure around rendering PEP files fromreStructuredText files to HTML webpages. We aim to specify a self-containedand maintainable solution for PEP readers, authors, and editors.
As of November 2021, Python Enhancement Proposals (PEPs) are rendered in amulti-system, multi-stage process. A continuous integration (CI) task runs adocutils script to render all PEP files individually. The CI task thenuploads a tar archive to a server, where it is retrieved and rendered into thepython.org website periodically.
This places a constraint on thepython.org website to handle raw HTMLuploads and handle PEP rendering, and makes the appropriate place to raiseissues unclear in some cases[1].
This PEP provides a specification for self-contained rendering of PEPs. Thiswould:
We propose that PEPs are accessed throughpeps.python.org at the top-level(for examplepeps.python.org/pep-0008), and that all custom tooling tosupport rendering PEPs is hosted in thepython/peps repository.
As of November 2021, to locally render a PEP file, a PEP author or editor needsto create a full local instance of thepython.org website and run a numberof disparate scripts, followingdocumentation that lives outside of thepython/peps repository.
By contrast, the proposed implementation provides a singleMakefile and aPython script to render all PEP files, with options to target a web-server orthe local filesystem.
Using a single repository to host all tooling will clarify where to raiseissues, reducing volunteer time spent in triage.
Simplified and centralised tooling may also reduce the barrier to entry tofurther improvements, as the scope of the PEP rendering infrastructure is welldefined.
There are several requests for additional features in reading PEPs, such as:
..code-block:: directives[2]These are “easy wins” from this proposal, and would serve to improve thequality-of-life for consumers of PEPs (including reviewers and writers).
For example, the current (as of November 2021) system runs periodically on aschedule. This means that updates to PEPs cannot be circulated immediately,reducing productivity. The reference implementation renders and publishes allPEPs on every commit to the repository, solving the issue by design.
The reference implementation fixes several issues[8]. For example:
Third-party providers such asRead the Docs orNetlify can enhance thisexperience with features such as automatic rendering of pull requests.
The proposed specification for rendering the PEP files to HTML is as per thereference implementation.
The rendered PEPs MUST be available atpeps.python.org. These SHOULD behosted as static files, and MAY be behind a content delivery network (CDN).
A service to render previews of pull requests SHOULD be provided. This serviceMAY be integrated with the hosting and deployment solution.
The following redirect rules MUST be created for thepython.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/$1The following nginx configuration would achieve this:
location~^/dev/peps/?(.*)${return308https://peps.python.org/$1/;}location~^/peps/(.*)\.html${return308https://peps.python.org/$1/;}location^/(dev/)?peps(/.*)?${return308https://peps.python.org/;}
Redirects MUST be implemented to preserveURL fragments for backwardcompatibility purposes.
Due to server-side redirects to the new canonical URLs, links in previouslypublished materials referring to the old URL schemes will be guaranteed to work.All PEPs will continue to render correctly, and a custom stylesheet in thereference implementation improves presentation for some elements (most notablycode blocks and block quotes). Therefore, this PEP presents no backwardscompatibility issues.
The mainpython.org website will no longer process raw HTML uploads,closing a potential threat vector. PEP rendering and deployment processes willuse modern, well-maintained code and secure automated platforms, furtherreducing the potential attack surface. Therefore, we see no negative securityimpact.
The new canonical URLs will be publicised in the documentation. However, thisis mainly a backend infrastructure change, and there should be minimalend-user impact. PEP 1 and PEP 12 will be updated as needed.
The proposed implementation has been merged into thepython/peps repositoryin a series of pull requests[9]. It uses theSphinx documentation systemwith a custom theme (supporting light and dark colour schemes) and extensions.
This already automatically renders all PEPs on every commit, and publishes themtopython.github.io/peps. The high level documentation for the system covershow to render PEPs locally andthe implementation of the system.
It would likely be possible to amend the current (as of November 2021)rendering process to include a subset of the quality-of-life improvements andissue mitigations mentioned above. However, we do not believe that this wouldsolve the distributed tooling issue.
It would be possible to use the output from the proposed rendering system andimport it intopython.org. We would argue that this would be the worst ofboth worlds, as a great deal of complexity is added whilst none is removed.
This document is placed in the public domain or under theCC0-1.0-Universal license, whichever is more permissive.
Source:https://github.com/python/peps/blob/main/peps/pep-0676.rst
Last modified:2025-08-08 15:00:59 GMT