摘要

本 PEP 针对将 PEP 文件从 reStructuredText 文件渲染成 HTML 网页的基础设施。我们的目标是为 PEP 阅读者、作者和编辑指定一个自包含且可维护的解决方案。

动机

截至 2021 年 11 月，Python 增强提案 (PEP) 采用多系统、多阶段流程进行渲染。持续集成 (CI) 任务运行 docutils 脚本以单独渲染所有 PEP 文件。然后，CI 任务将 tar 存档上传到服务器，该服务器定期检索并渲染到 python.org 网站。

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

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

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

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

理由

规范

提议的将 PEP 文件渲染成 HTML 的规范与 参考实现 相同。

渲染后的 PEP 必须在 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 将根据需要进行更新。

参考实现

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

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

被拒绝的建议

可能可以修改当前（截至 2021 年 11 月）的渲染过程，以包含上面提到的部分用户体验改进和问题缓解措施。但是，我们认为这并不能解决分布式工具问题。

可以将提议的渲染系统的输出导入 python.org。我们认为这将是两全其美，因为它增加了大量复杂性，却没有减少任何复杂性。

致谢

• Hugo van Kemenade
• Pablo Galindo Salgado
• Éric Araujo
• Mariatta
• C.A.M. Gerlach

脚注

版权

本文件置于公有领域或 CC0-1.0-Universal 许可下，以更宽松的许可为准。