PEP 渲染系统概述
本文档概述了 PEP 渲染系统，作为 PEP 676 的配套文档。
1. 配置
配置存储在三个文件中
peps/conf.py包含大部分 Sphinx 配置peps/contents.rst包含必需的目录指令pep_sphinx_extensions/pep_theme/theme.conf设置 Pygments 主题
配置
- 注册自定义 Sphinx 扩展
- 将
.rst后缀解析为 PEP - 告诉 Sphinx 使用哪些源文件
- 注册 PEP 主题、数学渲染器和模板
- 禁用扩展中已覆盖的一些默认设置
- 设置默认和“暗模式”代码格式化样式
2. 编排
build.py 管理渲染过程。用法在 本地构建 PEP 中介绍。
3. 扩展
Sphinx 扩展和主题包含在 pep_sphinx_extensions 目录中。以下是 PEP 渲染过程各阶段的简要概述，以及扩展在每个阶段的功能。
3.1 扩展设置
该扩展注册了几个对象
FileBuilder和DirectoryBuilder分别运行基于文件和目录的构建过程。PEPParser注册自定义文档转换，并将 PEP 解析为 Docutils 文档。PEPTranslator将 Docutils 文档转换为 HTML。PEPRole处理 reStructuredText 源中的:pep:角色。
该扩展还修补了默认行为
- 更新默认设置
- 更新 Docutils inliner
- 使用 HTML 数学显示而不是 MathJax
3.2 构建器初始化
在创建和初始化 Sphinx 构建器对象后，我们确保所选构建器的配置正确。
目前这包括更新相对链接模板。请参阅 pep_sphinx_extensions/__init__.py 中的 _update_config_for_builder。
3.3 文档读取前
调用了 create_pep_zero 钩子。请参阅 5. PEP 0。
3.4 读取文档
文档解析由 PEPParser (pep_sphinx_extensions.pep_processor.parsing.pep_parser.PEPParser) 处理，它是 sphinx.parsers.RSTParser 的一个轻量级包装器。
PEPParser 读取带有前导 RFC 2822 头的文档，并注册我们要应用的转换。这些是
PEPHeadersPEPTitlePEPContentsPEPFooter
然后按优先级顺序应用转换。
3.4.1 PEPRole 角色
这会覆盖内置的 :pep: 角色以返回正确的 URL。
3.4.2 PEPHeaders 转换
根据 PEP 1，PEP 以一组 RFC 2822 头开始。此转换验证必需的头是否存在且数据类型正确，并移除不用于显示的头。它必须在 PEPTitle 转换之前运行。
3.4.3 PEPTitle 转换
我们从 PEP 头中解析的标题生成标题节点，并将文档中的所有节点作为新标题节点的子节点。此转换还必须处理 PEP 标题内 reStructuredText 标记的解析，例如 PEP 604。
3.4.4 PEPContents 转换
自动目录 (TOC) 在此转换中通过两个步骤插入。
首先，转换会在文档标题和 PEP 头之后插入一个 TOC 占位符和一个水平线。然后，回调转换会递归遍历文档以创建 TOC，从占位符节点之后开始。在遍历文档时，会移除标题中的所有引用节点，并为标题添加自链接。
3.5 准备写入
pep_html_builder.FileBuilder.prepare_writing 初始化 Docutils writer 和文档写入设置的最少内容。这比基础 Sphinx 实现有显著的速度提升，因为自动初始化的数据大部分是未使用的。
3.6 将 Docutils 转换为 HTML
PEPTranslator 重写了段落和引用逻辑，以复制先前基于 docutils.writers.pep 的系统的处理。段落通过省略 <p> 标签在可能的情况下被紧凑化，并且脚注引用将被包含在方括号中。
3.7 准备导出到 Jinja
最后，在 pep_html_builder 中，我们收集所有将传递给 Jinja 模板的部分。这也是我们创建侧边栏目录的地方。
然后将 HTML 文件写入构建目录。
4. 主题
主题由 pep_sphinx_extensions/pep_theme/templates/page.html 中的 HTML 模板和 pep_sphinx_extensions/pep_theme/static 中的样式表组成。
模板完全独立，不依赖于 Sphinx 的任何默认行为。它指定要包含的 CSS 文件、图标和文档结构的基本语义信息。
样式分为两部分
style.css处理布局的主要部分mq.css添加媒体查询以实现响应式设计
5. PEP 0
索引 PEP 0 的生成分三个阶段进行。首先生成 reStructuredText 源文件，然后将其添加到 Sphinx，最后对数据进行后处理。
5.1 文件创建
在 Sphinx 加载文档之前的回调期间创建 pep-0000.rst。
我们首先解析单个 PEP 文件以获取 RFC 2822 头，然后解析并验证这些元数据。
在收集并验证了所有 PEP 数据后，索引本身通过三个步骤创建
- 输出头文本
- 输出类别和数字索引
- 输出作者索引
然后我们将新创建的 PEP 0 文件添加到两个 Sphinx 变量中，以便它被当作普通源文件处理。
5.2 后处理
PEPHeaders 转换会调度 PEP 0 后处理代码。这有两个功能：屏蔽电子邮件地址和将数字 PEP 引用链接到实际文档。
6. RSS Feed
RSS Feed 是通过提取最近十个 PEP 的头元数据和摘要来创建的。