文档工具与环境准备¶

使用本参考准备维护中的文档环境。已验证构建组合是 Linux x86_64 与 CPython 3.12。本地准备使用 CPython 3.12.14；CI 选择同一补丁版本。文档工具资格不授予固件、硬件或产品资格。

先准备固定源码与递归依赖。清单与工具锁必须来自同一选定源码版本。

权威依赖闭包¶

dependencies/docs-tools.lock.json 维护归档身份、目标约束、直接依赖和许可来源。完整 Python 依赖也在 dependencies/docs-python-linux-cp312.txt 中列出，使用精确版本与 SHA-256。docs/sphinx/requirements.txt 引用该文件，不定义另一份解析输入。

工具或资源	维护身份	用途
Sphinx	7.4.7	严格 HTML 与 gettext 构建器
MyST parser	4.0.1	Markdown 指令、角色与导航
Breathe	4.35.0	从新生成 Doxygen XML 提供公共 API
Docutils	0.21.2	结构化文档处理
Alabaster	0.7.16	本地 HTML 主题资源
polib	1.2.0	翻译消息目录验证
Python 闭包	28 个分别记录摘要的 wheel 包	全部运行时传递依赖包
Doxygen	官方 Linux 1.14.0 归档	公共头文件 XML 与 HTML
Graphviz	Debian 2.42.4-3 归档	已审查 DOT 图示
Noto CJK	Debian 20240730+repack1-1 归档	精确 CJK 字形与度量
Native 闭包	46 个分别记录摘要的 Debian 归档	加载器、库、渲染器与字体数据

Native 闭包包含 libc 加载器、C/C++ 运行库、Graphviz core／dot／Pango 插件、fontconfig，以及这些执行文件和渲染器实际链接的每个库。准备流程执行锁定加载器的 --list，拒绝 prefix 外路径。它移除不支持的渲染器，不发现主机 GTK、GD 或 Ghostscript 安装。此工具集支持维护中的 DOT／SVG／Cairo 图链，不支持每一种 Graphviz 渲染器。

Linux 内核、CPython／venv 引导、dpkg-deb 和 POSIX shell 是明确主机前提，其实测值记录在准备回执中。本锁不宣称主机镜像可复现或内核逐字节相同。

准备新 prefix¶

从仓库根目录、在 CPython 3.12 可用的条件下执行：

python3.12 tools/documentation/install.py \
    --prefix build/docs-tools --cache build/docs-tool-cache

准备流程可以通过 HTTPS 下载归档。它先验证整个归档闭包，再创建 prefix。wheel 包安装随后使用 --no-index、--find-links 和 --require-hashes；没有传递依赖留给新的在线解析。Native 包在本地解包，不使用 sudo 或系统包安装。

从此前准备的缓存进行独立安装：

python3.12 tools/documentation/install.py \
    --prefix build/docs-tools-restored --cache build/docs-tool-cache --offline

预期结果是退出码零，以及新 prefix 中的 installation.json。它记录工具锁摘要、实测版本、内核、解析后的 ELF 闭包、归档摘要、已安装文件摘要与复制许可摘要。安装后的 bin/fc-match 必须从锁定字体包解析 Noto Sans CJK SC。归档缺失、字节变化、命令失败或字体不匹配都会使准备失败，不留下成功 prefix。

已有 prefix 会被拒绝。升级时选择新路径，不得静默改变已经被构建证据引用的安装。缓存归档损坏同样失败，不通过重新下载静默替换。

使用唯一文档 CLI¶

使用准备好的 Python 和显式工具 prefix 运行维护 CLI：

build/docs-tools/venv/bin/python tools/dev/dev.py docs doctor \
    --tool-prefix build/docs-tools
build/docs-tools/venv/bin/python tools/dev/dev.py docs check \
    --report build/docs-check.json
build/docs-tools/venv/bin/python tools/dev/dev.py docs build \
    --tool-prefix build/docs-tools --language all --output build/documentation
build/docs-tools/venv/bin/python tools/dev/dev.py docs package \
    --build build/documentation --output ../nexus-documentation-packages

install.environment(prefix) 返回已验证的子进程环境，将锁定执行文件放在 PATH 首位。install.diagnose(prefix) 在报告工具身份前拒绝变化的工具锁、已安装文件或许可。两者均不安装或下载工具。构建必须生成新的 XML 与 HTML；旧成功输出不能补救失败命令。

scripts/tools/docs.py、.sh、.ps1 和 .bat 入口只转发到此 CLI。旧 all、doxygen 和 sphinx 目标都选择同一完整严格构建。已移除的生成修饰选项会被拒绝；包装入口不能创建回退 Doxyfile 或 Sphinx 配置。Windows 与 macOS 包装入口保留 CLI 转发，正式构建仍要求维护中的 Linux 工具组合。

重放 API 移动端布局回归¶

此可选诊断除了已说明的 Sphinx 工具组合，还需要已有的 Chromium 和 Playwright。它不会安装工具。请使用单独准备的浏览器测试环境；正式文档构建和默认 stdlib 测试套件不导入 Playwright。

在仓库根目录执行，并提供已有的浏览器可执行文件：

python tools/documentation/check_browser_layout.py \
    --chromium /path/to/chromium --report build/quality/api-layout.json

该工具使用生产主题构建临时的中英文 C API 夹具。在 390 CSS 像素视口下，它检查长签名、未改变的符号和锚点、通过内部滚动保留的完整代码及表格内容，以及未裁切的页面。缺少工具或检查失败时返回非零值。成功记录只验证该夹具和实际观察的浏览器；全站响应式验收和归档验证仍需分别执行。

搜索当前站点¶

中英文搜索页面分别使用本地 Sphinx 索引和当前语言的元数据。中文分词器不依赖外部分词词典，可处理汉字序列和拉丁字符标识符。组合查询时使用空格分隔关键词，例如 借用排空 或 借用 HAL。

结果展示版本、内容类型、源语言和实际语言，以及正文摘要。搜索资源仅在搜索页面加载。归档链接和原始资格记录保留其冻结的源码与语言范围。

CI 权限边界¶

docs-build.yml 只有 contents: read。它显式准备工具、执行源码检查、构建两种语言、打包离线输出并记录实测任务身份。构建失败时没有成功文档上传。包生产器在源码 checkout 外写入。CI 随后将已验证结果复制到新的忽略上传暂存目录，比较归档摘要，并在已有任务身份门禁前验证复制后的清单与内容文件。该暂存复制不重建或替换原始包。

docs-publish.yml 只为已审查的 docs-delivery 分支运行。其只读任务在上传 Pages 产物前验证已准备的公开字节与发布回执。只有独立部署任务具有 Pages 和 OIDC 写权限，并使用 nexus-documentation 环境。它从不 checkout 或执行外部 pull 请求源码。部署分支规则与实际远程执行仍是必须独立观察的仓库状态。

许可与升级处理¶

每个 Native 归档携带 Debian copyright 文件。锁定 base-files 归档提供 licenses/common-licenses/ 中所有被引用完整文本；共享许可引用缺失时准备会拒绝。wheel 包许可从已验证 wheel 包复制；五个未包含许可文本的上游 wheel 包使用从各自精确已验证源发行包提取并检入的文本。工具锁记录源归档摘要、成员和提取文本摘要。Doxygen 归档携带完整许可。准备将文本复制到 prefix/licenses/；打包保留适用许可内容文件。

升级时审查上游变更与许可，解析一份新的精确闭包，同时更新工具锁与摘要约束，执行新在线准备及独立离线准备，再运行严格双语构建、图示新鲜度、包验证和恢复。保留原始失败与结果；仅更新版本字符串不足以建立验收证据。