CPython 文档构建指南：基于 Doc/README.rst 详解 Sphinx、Make 与全量构建流程

2026-09-03 15:21:58作者：薛曦旖Francesca

本文以 CPython 仓库中的 Doc/README.rst 为核心，系统讲解 Python 官方文档从 reStructuredText 源文件到 HTML/PDF/EPUB 成品的完整构建链路。读完本文，你将掌握使用 make venv / make html 等目标本地构建文档、脱离 Make 直接调用 sphinx-build、通过 html_context 注入"过期版本"红色横幅（deprecation header）、以及 dist、changes、coverage 等高级目标的用法，并能对照 Doc/Makefile 与 Doc/conf.py 理解每个参数背后的实际行为。

一、文档源文件与构建工具链总览

Doc/ 目录存放的是 reStructuredText（reST）格式的 Python 官方文档源文件。README 开篇即说明：你不需要自己构建文档，官方提供预构建版本可直接下载；本文档主要面向文档贡献者和维护者。撰写规范（风格与标记用法）则指向 Python 开发者指南中的 "Documenting Python" 章节。

文档骨架由 Doc/contents.rst 中的 toctree 指令定义，它把整份文档组织为 12 个大板块：

What's New、Tutorial、Using、Language Reference、Library Reference
Extending and Embedding、C API、Installing、Howtos、FAQ
Deprecations、Glossary，外加 about.rst、bugs.rst、copyright.rst、license.rst 等页面

构建依赖三个不随源码树分发、而是从 PyPI 独立维护安装的工具：

工具	职责	依据
Sphinx	文档构建引擎，将 reST 编译为 HTML/LaTeX/EPUB 等格式	Doc/requirements.txt 中固定为 `sphinx<9.0.0`
blurb	从 `Misc/NEWS.d/` 下的片段合并生成 CHANGELOG（NEWS 文件）	Doc/Makefile 的 `build` 目标
python-docs-theme	官方文档主题（`python_docs_theme`），独立仓库单独安装	Doc/conf.py 中 `html_theme = 'python_docs_theme'`

README 建议的最简上手方式，就是在 Doc/ 目录下创建一个虚拟环境，把工具安装进去。依赖版本管理上有两层保障：

Doc/requirements.txt 声明直接依赖（Sphinx、pygments、blurb、sphinx-linklint、sphinx-notfound-page、sphinxext-opengraph、python-docs-theme 等），并注释了"Sphinx 版本被刻意钉住，避免新版本引入新警告导致构建突然失败"；
Doc/pylock.toml 是 make lock 生成的锁文件，Doc/Makefile 中的 lock 目标用 uv pip compile 生成，其中还包含一条供应链安全设计：所有依赖默认有 14 天冷却期（--exclude-newer P14D），只有核心团队维护的 sphinx_linklint 和 python-docs-theme 例外可即时更新。

二、使用 Make 构建文档（Unix）

2.1 虚拟环境与首次构建

在 Unix 上，README 给出的两条命令即可完成首次构建：

make venv
make html

venv 目录将包含从 PyPI 下载安装的全部构建工具。对照 Doc/Makefile，venv 目标的实际行为比 README 描述的更精细：

若 venv 目录已存在，会直接提示"venv already exists"，需先 make clean-venv 删除后重建；
若系统装有 uv，优先使用 uv venv + uv pip install -r pylock.toml（按锁文件安装，版本可复现）；
否则回退到标准库 python -m venv + pip install -r pylock.toml。

两个可配置的变量：

VENVDIR：虚拟环境位置，默认为 ./venv（Doc/Makefile 第 8 行），可用 make venv VENVDIR=... 覆盖；
PYTHON：解释器，默认 python3。

2.2 跳过虚拟环境：复用系统工具

README 说明可以完全不创建虚拟环境，此时 Makefile 会在你的 PATH 中查找 sphinx-build 与 blurb，可用 SPHINXBUILD 和 BLURB 变量覆盖。从源码看，这两者的默认值（Doc/Makefile）是：

SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
BLURB     = PATH=$(VENVDIR)/bin:$$PATH blurb

即默认优先在 venv/bin 里找工具，找不到才落到系统 PATH——这与 README 的"跳过 venv"语义一致：只要 sphinx-build 和 blurb 可执行，构建即可进行。注意 build 目标里有硬校验（Doc/Makefile）：两者任一缺失会打印 "Missing the required blurb or sphinx-build tools. Please run 'make venv'..." 并退出。

2.3 Windows 下的 make.bat

Windows 上仓库提供了 Doc/make.bat，尽量模拟 Unix Makefile 的行为。如需指定解释器，设置 PYTHON 环境变量即可（README "On Windows" 一节）。

2.4 全部 make 目标清单

README 列出的目标（与 Doc/Makefile 的 help 目标一一对应）如下：

clean：删除所有构建产物与虚拟环境；
clean-venv：仅删除虚拟环境目录；
venv：创建装好全部工具的虚拟环境；
html：构建离线查看的独立 HTML 文件（输出到 build/html/）；
htmlview：复用 html 构建器，然后在默认浏览器中打开主页面。源码实现是 python -c "import os, webbrowser; webbrowser.open(...)"（Doc/Makefile）；
htmllive：复用 html 构建器，重建文档、启动本地服务器，并在 reST 文件变动时自动刷新浏览器（仅 Unix）。从源码看它通过 _ensure-sphinx-autobuild 目标按需补装 sphinx-autobuild，并用 --re-ignore="/venv/" --open-browser --delay 0 参数（Doc/Makefile）；
htmlhelp：构建 HTML 加 HTML Help 工程文件，可进一步编译为单文件 CHM（Windows 下流行，其他平台也实用）。生成 CHM 需对产出的 .hhp 工程文件运行 Microsoft HTML Help Workshop，make.bat 在 Windows 上会代劳。注意 Doc/conf.py 中检测到 htmlhelp 构建时会主动打印 "Windows CHM Help is no longer supported" 警告，说明该格式已处于弃用过渡期；
latex：构建 LaTeX 源文件，作为 pdflatex（配置中实际为 xelatex，见 Doc/conf.py）的输入以生成 PDF。可用 PAPER=a4 或 PAPER=letter 指定纸张；
text：为每个源文件构建纯文本；
epub：构建 EPUB 电子书，适合在电子阅读器中查看；
linkcheck：检查所有外部引用是否断链、重定向或格式错误，结果输出到 stdout 及一个 .txt 文件（build/linkcheck/output.txt）；
changes：汇总当前版本中所有 versionadded/versionchanged/deprecated 项，作为撰写 "What's New" 文档的辅助；
coverage：生成标准库模块与 C API 的文档覆盖率报告，结果在 build/coverage/ 下的 c.txt 与 python.txt；
pydoc-topics：构建一个 Python 模块，其中是 Doc/tools/extensions/pyspecific.py 所定义标签的纯文本文档字典——pydoc 需要它来显示 topic 与 keyword 帮助。构建完成后需手动复制到 Lib/pydoc_data/（见 Doc/Makefile 的提示）；
check：检查常见标记错误。源码实现（Doc/Makefile）是先按需安装 pre-commit，再运行 pre_commit run --all-files；
dist（仅 Unix）：创建 HTML、text、PDF、EPUB 等构建的发行归档。

README 未提及但 Makefile 中同样存在、值得了解的还有：

texinfo：生成 python.texi，再用 make info 转成 Texinfo 信息页（Doc/Makefile）；
doctest：运行文档中的 doctest（Doc/Makefile）；
gettext：生成 POT 翻译文件，且使用独立的 build/doctrees-gettext 目录避免污染正常构建缓存（Doc/Makefile）；
html-ids：调用 Doc/tools/check-html-ids.py 收集 HTML ID 到 JSON，用于防止页面锚点 ID 被意外删除（Doc/Makefile）；
autobuild-dev / autobuild-stable：每日自动文档构建入口，通过 --fresh-env --write-all 忽略 Sphinx 缓存以确保链接偏好变更被拾取；稳定版还会用 case $(DISTVERSION) in *[ab]*) 过滤掉 alpha/beta 预发布阶段（Doc/Makefile）。

2.5 dist 归档的内部流程

dist 目标（Doc/Makefile）会依次调用 dist-html、dist-text、dist-pdf、dist-epub、dist-texinfo。以 dist-html 为例，流程是：先清理旧产物，重新执行 make html，把 build/html 复制为 python-<版本>-docs-html 目录，再打包 tar.bz2 与 zip 两种压缩格式。版本字符串来自 tools/extensions/patchlevel.py（Doc/Makefile 第 15 行），因此归档文件名自动带上当前开发版本号。PDF 部分（dist-pdf）额外依赖 sphinxcontrib-svg2pdfconverter，并会用 all-pdf + latexmk 并行编译 A4 版式。

三、不使用 Make：直接调用 sphinx-build

如果不想依赖 Make，README 给出的流程是：

先从 PyPI 安装工具依赖（Sphinx、python-docs-theme 等）；
在 Doc 目录下运行：

sphinx-build -b<builder> . build/<builder>

其中 <builder> 可选 html、text、latex 或 htmlhelp（各 builder 的含义参见上文 Make 目标说明）。

对照 Makefile 中的 ALLSPHINXOPTS（Doc/Makefile），等价的手工完整命令还应包含：

sphinx-build --builder html \
    --doctree-dir build/doctrees \
    --jobs auto \
    --fail-on-warning \
    . build/html

要点：

--doctree-dir build/doctrees：doctree（中间解析树）单独缓存，保证不同 builder 共享解析缓存，加快增量构建；
--jobs auto：Sphinx 并行构建；
--fail-on-warning：由 SPHINXERRORHANDLING 变量提供（Doc/Makefile），即任何 Sphinx 警告都会导致构建失败——这是官方文档对标记错误"零容忍"的关键机制。

另外注意 Doc/conf.py 的 exclude_patterns：includes/*.rst（被嵌入页面但不单独渲染）、venv/* 和 README.rst（即本文档自身）都会被排除在构建之外，所以直接运行 sphinx-build 时这些文件不会出现在产物中。

四、Deprecation Header：用 html_context 显示"过期版本"横幅

README 的 "Deprecation header" 一节描述了一个实用特性：在 html_context 中定义 outdated 变量，即可在每个页面顶部显示一个红色横幅，把读者重定向到 "latest" 版本文档。README 同时指出一个已知限制：跳转链接指向 /3/ 下的同名页面，"遗憾的是目前该过程中会丢失语言信息"（即非英语本地化路径无法保留）。

这一机制的完整实现在 Doc/tools/templates/layout.html 中，它继承主题模板并重写 header 块：

{%- if outdated %}
<div id="outdated-warning" style="...background-color: #FFBABA; color: #6A0E0E;">
    {% trans %}This document is for an old version of Python that is no longer supported.
    You should upgrade, and read the{% endtrans %}
    <a href="/3/{{ pagename }}{{ file_suffix }}">...current stable release...</a>
</div>
{%- endif %}

横幅的跳转目标是 /3/{{ pagename }}，与 README 中"link points to the same page on /3/"完全一致；使用 Jinja2 {% trans %} 包裹文案，说明该提示本身是可翻译的。同一模板还实现了第二种类似横幅：当环境变量表明当前是 Pull Request 部署预览（is_deployment_preview，由 Doc/conf.py 根据 READTHEDOCS_VERSION_TYPE == "external" 计算并注入 html_context）时，页面顶部显示黄色提示条，指明这是来自某个 PR 的预览版本。这解释了 html_context 的通用用法：conf.py 中可注入任意键，模板中即可用 {% if 键名 %} 判断。

五、构建配置的关键细节（conf.py 佐证）

理解 Doc/conf.py 有助于解释 README 中各目标的产物形态。几个值得关注的配置：

自定义扩展（Doc/conf.py）：pyspecific（注册 Python 领域角色与领域，使 :mod:、:func: 等交叉引用生效）、changes（支撑 make changes 的变更汇总）、pydoc_topics（支撑 make pydoc-topics）、issue_role（:issue: 角色）等，均位于 Doc/tools/extensions/；
版本来源：version, release = get_version_info() 从源码树的 Include/patchlevel.h 读取版本，因此文档标题、归档文件名与当前 checkout 的 CPython 版本天然一致；
构建版本下限：needs_sphinx = '8.2.0'（Doc/conf.py），且注释要求与 Doc/requirements.txt 中的 Sphinx 版本保持同步；
主题与页面结构：html_theme = 'python_docs_theme'、html_theme_path = ['tools']，侧边栏通过 html_sidebars 定制，root_doc = 'contents' 指明入口文档即 Doc/contents.rst；
LaTeX 分册：latex_documents 把文档拆成 C API、Extending、Installing、Library Reference、Language Reference、Tutorial 等多本独立手册，这正是 make dist-pdf 能产出多册 PDF 的原因。

六、贡献与问题反馈

README 的 "Contributing" 一节给出了反馈渠道的分工：

内容问题（文档写错了）：报告到 Python 官方 bug tracker（python/cpython 的 issues）；
工具链问题（Sphinx、blurb、python-docs-theme 本身的缺陷）：报告到对应工具自己的仓库；
咨询与求助：在 discuss.python.org 的 documentation 分类留言。

这套分工与构建体系是吻合的：Doc/ 下属于"内容"，而 Doc/tools/ 中的扩展、Doc/tools/templates/ 中的模板以及外部 PyPI 包属于"工具"，出问题时应分别对号入座。

七、快速上手清单

综合 README 与 Makefile，典型工作流可归纳为：

# 1. 进入文档目录（在仓库根目录下）
cd Doc

# 2. 创建虚拟环境并安装锁定版本依赖（首次）
make venv

# 3. 构建 HTML 文档
make html          # 产物位于 build/html/

# 4. 本地实时预览（修改 reST 自动刷新）
make htmllive

# 5. 质量检查
make check         # pre-commit 标记检查
make linkcheck     # 外部链接检查

# 6. 撰写 What's New 时
make changes       # 汇总 versionadded/versionchanged/deprecated

# 7. 生成发行归档
make dist