摘要

本PEP旨在解决将PEP文件从reStructuredText文件渲染成HTML网页的基础设施问题。我们旨在为PEP读者、作者和编辑指定一个自成一体且可维护的解决方案。

动机

截至2021年11月，Python增强提案（PEPs）通过多系统、多阶段流程进行渲染。持续集成（CI）任务运行docutils脚本，单独渲染所有PEP文件。然后，CI任务将一个tar压缩包上传到服务器，该服务器会定期检索并将其渲染到python.org网站上。

这使得python.org网站在处理原始HTML上传和PEP渲染方面受到限制，并且在某些情况下，提出问题的合适位置变得不明确[1]。

本PEP为PEP的自包含渲染提供了规范。这将

• 减少支持PEP的分布式配置量
• 为阅读、编写和评审PEP的人员提供生活质量改进
• 解决一些悬而未决的问题，并为改进铺平道路
• 节省志愿者维护者的时间

我们建议通过顶级域名peps.python.org访问PEPs（例如peps.python.org/pep-0008），并且所有支持渲染PEPs的自定义工具都托管在python/peps仓库中。

基本原理

规范

将PEP文件渲染为HTML的建议规范与参考实现一致。

渲染的PEPs必须在peps.python.org上可用。这些应托管为静态文件，并可能位于内容分发网络（CDN）之后。

应提供一项服务来渲染拉取请求的预览。此服务可以与托管和部署解决方案集成。

必须为python.org域创建以下重定向规则

• /peps/ -> https://peps.pythonlang.cn/
• /dev/peps/ -> https://peps.pythonlang.cn/
• /peps/(.*)\.html -> https://peps.pythonlang.cn/$1
• /dev/peps/(.*) -> https://peps.pythonlang.cn/$1

以下 nginx 配置将实现此目标

location ~ ^/dev/peps/?(.*)$ {
    return 308 https://peps.pythonlang.cn/$1/;
}

location ~ ^/peps/(.*)\.html$ {
    return 308 https://peps.pythonlang.cn/$1/;
}

location ^/(dev/)?peps(/.*)?$ {
    return 308 https://peps.pythonlang.cn/;
}

必须实施重定向以保留URL 片段，以实现向后兼容性。

向后兼容性

由于服务器端重定向到新的规范URL，先前发布材料中引用旧URL方案的链接将保证有效。所有PEP将继续正确渲染，参考实现中的自定义样式表改善了一些元素（最显著的是代码块和引用块）的呈现。因此，本PEP不涉及向后兼容性问题。

安全隐患

主要的python.org网站将不再处理原始HTML上传，从而消除潜在的威胁向量。PEP渲染和部署过程将使用现代、维护良好的代码和安全的自动化平台，进一步减少潜在的攻击面。因此，我们认为没有负面安全影响。

如何教授此内容

新的规范 URL 将在文档中公布。然而，这主要是一个后端基础设施变更，对最终用户的影响应该很小。PEP 1 和 PEP 12 将根据需要进行更新。

参考实现

拟议的实现已通过一系列拉取请求合并到python/peps仓库中[9]。它使用Sphinx文档系统，并带有自定义主题（支持明暗配色方案）和扩展。

这已经可以在每次提交时自动渲染所有 PEP，并将它们发布到 python.github.io/peps。系统的高级文档涵盖了 如何在本地渲染 PEP 和 系统的实现。

被拒绝的想法

当前的（截至2021年11月）渲染过程很可能能够修改，以包含上述生活质量改进和问题缓解措施的子集。然而，我们不认为这能解决分布式工具问题。

可以利用建议的渲染系统的输出并将其导入到python.org中。我们认为这将是两害相权取其轻，因为这会增加大量复杂性，而没有任何复杂性被消除。

致谢

• Hugo van Kemenade
• Pablo Galindo Salgado
• 埃里克·阿劳霍
• Mariatta
• C.A.M. Gerlach

脚注

版权

本文档置于公共领域或 CC0-1.0-Universal 许可证下，以更宽松者为准。