从 PR 到本地构建：ROCm 文档构建全指南（GitHub / 命令行 / VS Code 三路打通）

从 PR 到本地构建：ROCm 文档构建全指南（GitHub / 命令行 / VS Code 三路打通）

【免费下载链接】legacy-rocm-buildAMD ROCm™ Software - GitHub Home项目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build

ROCm 官方文档（本文以当前仓库 legacy-rocm-build 为蓝本）本身就是一个由 Sphinx 驱动的开源项目，贡献者既可以在云端通过 GitHub 与 Read the Docs 集成查看 PR 构建结果，也可以在本地用命令行或 Visual Studio Code 构建出完整 HTML 站点进行预览。本篇指南将完整覆盖这三种构建路径：从提交 PR 后如何定位构建报告，到使用venv+ Sphinx 一键生成文档，再到在 VS Code 中搭建带实时刷新的写作与调试环境，读完即可上手为 ROCm 文档提交并验证自己的改动。

构建前了解：ROCm 文档的技术栈与仓库布局

在动手构建之前，先理解 ROCm 文档在仓库中的组织方式，这有助于解释后续构建命令的各个参数。

核心构建链：Sphinx + rocm-docs-core

根据仓库内的 docs/contribute/toolchain.md，ROCm 文档构建依赖以下开源工具：

• Sphinx：核心文档生成器，负责把 reStructuredText / Markdown 源码编译为 HTML 等输出格式；
• Sphinx External ToC：基于 YAML 导航文件生成左侧目录树，对应仓库中的 docs/sphinx/_toc.yml.in；
• Sphinx-book-theme / rocm-docs-core：负责站点的外观主题与 ROCm 定制（页眉、页脚、选择器等）；
• Sphinx Design：提供卡片、网格与同步标签页（如本文后面命令块中的 Linux/Windows 标签页切换）；
• Doxygen + Breathe：用于从源码注释生成 API 文档。

仓库根目录的 CMakeLists.txt 中有一个BUILD_DOCS开关（默认ON），它控制是否进入 docs/CMakeLists.txt 中的rocm_add_sphinx_doc(...)文档构建目标；而 cmake/Modules/Dependencies.cmake 会在需要时通过FetchContent拉取rocm-cmake来提供该构建模块。这意味着文档构建既可以直接用 Sphinx 命令行，也可以纳入 CMake 的构建流程。

两种文档目录：当前活跃版与归档版

本仓库同时存在两份内容几乎一致的构建指南：

• docs/contribute/building.md：活跃版本，已被 docs/sphinx/_toc.yml.in 的 "Contribute → Building documentation" 目录项引用；
• docs/exclude/about/contribute/building.md：位于exclude（排除）目录下的旧版归档。

本篇指南以归档版文档为主干展开讲解，其内容与活跃版一致，可作为两份文档的通用操作手册。

方式一：通过 GitHub PR 查看云端 Read the Docs 构建

ROCm 文档由 Read the Docs 服务托管构建。作为贡献者，你提交 Pull Request 后并不需要自己先在本地构建，可以先利用云端自动构建结果做一次快速验证。

1. 打开你的 PR，滚动到页面底部的summary panel（摘要面板）；
2. 在commit status（提交状态）区域找到形如docs/readthedocs.com:advanced-micro-devices-demo的状态行，其右侧有一个Details链接；
3. 点击Details即可跳转到 Read the Docs 针对该 PR 的构建页面，查看构建日志与产物。

提示：如果在摘要面板中看不到上述状态行，点击Show all checks（显示全部检查）展开条目化视图即可找到。

云端构建的 Python 版本与依赖包均由项目配置文件决定：Python 版本由 Read the Docs 配置中的build.tools.python指定，Python 依赖清单则来自 docs/sphinx/requirements.txt——注意该文件本身是一个"指针"文件，通过-r引用了rocm-docs-core提供的统一依赖列表，因此在本地构建时同样需要安装该文件内容。

方式二：命令行本地构建（Linux / WSL 与 Windows）

云端构建适合快速验收，但撰写文档时强烈建议在本地构建，以便实时发现语法错误、失效链接和告警。

环境准备

• Python：使用 Read the Docs 指定的版本（见项目 Read the Docs 配置中的build.tools.python设置）；
• Python 包：安装 docs/sphinx/requirements.txt 中列出的全部依赖（包含 Sphinx、rocm-docs-core 及相关扩展）；
• 虚拟环境：使用 Python 标准库的venv隔离依赖，避免污染系统环境。

构建步骤

在项目根目录执行以下命令。Linux 与 WSL 使用sh：

python3 -mvenv .venv .venv/bin/python -m pip install -r docs/sphinx/requirements.txt .venv/bin/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html

Windows 使用 PowerShell（注意解释器路径分隔符为反斜杠）：

python -mvenv .venv .venv\Scripts\python.exe -m pip install -r docs/sphinx/requirements.txt .venv\Scripts\python.exe -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html

构建命令参数逐项解析

以sphinx命令为例，各参数作用如下：

其中docs源目录下的入口文件为 docs/index.md，docs/conf.py 则集中配置了 Sphinx 扩展（selector、matrix、remote_content 等 rocm_docs_custom 扩展）与主题选项。

构建完成后，用浏览器打开_build/html/index.html即可查看完整的本地文档站点。

方式三：Visual Studio Code 高效写作环境

命令行构建适合一次性验证；如果你要长期撰写文档，可以在 VS Code 中搭建一个"改完即刷新生效"的环境，借助两个扩展和两个配置文件即可实现。

1. 安装必需扩展

在 VS Code 扩展市场中安装：

• Python（扩展 ID：ms-python.python）：提供虚拟环境管理与集成终端支持；
• Live Server（扩展 ID：ritwickdey.LiveServer）：提供本地静态站点实时预览与自动刷新。

2. 配置.vscode/settings.json

在工作区的.vscode/settings.json中添加以下条目：

{ "liveServer.settings.root": "/.vscode/build/html", "liveServer.settings.wait": 1000, "python.terminal.activateEnvInCurrentTerminal": true }

各项配置含义：

• liveServer.settings.root：设置 Live Server 服务的站点根目录（即文档输出目录）。注意它必须与下面tasks.json中构建命令的输出目录保持一致，两者需同步修改；
• liveServer.settings.wait：设置刷新前的等待毫秒数。这是为了让 Sphinx 有足够时间重新生成站点内容，避免在构建尚未完成时浏览器就提前刷新；
• python.terminal.activateEnvInCurrentTerminal：在集成终端中自动激活 Python 虚拟环境，使你无需手动source .venv/bin/activate即可在终端里直接构建。

3. 配置.vscode/tasks.json构建任务

将下面的构建任务写入.vscode/tasks.json，它会把"构建文档"注册为 VS Code 的默认构建任务：

{ "version": "2.0.0", "tasks": [ { "label": "Build Docs", "type": "process", "windows": { "command": "${workspaceFolder}/.venv/Scripts/python.exe" }, "command": "${workspaceFolder}/.venv/bin/python3", "args": [ "-m", "sphinx", "-j", "auto", "-T", "-b", "html", "-d", "${workspaceFolder}/.vscode/build/doctrees", "-D", "language=en", "${workspaceFolder}/docs", "${workspaceFolder}/.vscode/build/html" ], "problemMatcher": [ { "owner": "sphinx", "fileLocation": "absolute", "pattern": { "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):(\\d+):\\s+(WARNING|ERROR):\\s+(.*)$", "file": 1, "line": 2, "severity": 3, "message": 4 } }, { "owner": "sphinx", "fileLocation": "absolute", "pattern": { "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):{1,2}\\s+(WARNING|ERROR):\\s+(.*)$", "file": 1, "severity": 2, "message": 3 } } ], "group": { "kind": "build", "isDefault": true } } ] }

任务要点说明：

• 与命令行版本相比，这里多传了-j auto（按 CPU 核数并行构建，加快速度），并将中间产物doctrees与输出目录收敛到工作区内的.vscode/build下，避免污染项目根目录的_build；
• group.kind设为build且isDefault: true，使其成为默认构建任务，可直接用快捷键触发。

实现细节：为什么需要两个 problemMatcher？VS Code 无法容忍 problem 信息中"可能缺失"的捕获组。如果某个警告/错误消息里没有行号，而单个正则的pattern又引用了行号捕获组，VS Code 会直接丢弃整条消息。因此这里定义了第二个正则，允许行号部分（:1:2或:1）整体缺失，确保没有行号的 Sphinx 告警也能被正确采集并显示在"问题"面板中。

4. 创建 Python 虚拟环境

1. 打开命令面板（Ctrl+Shift+P）；
2. 运行Python: Create Environment；
3. 选择venv环境类型；
4. 选择 docs/sphinx/requirements.txt 作为依赖清单。

VS Code 会自动创建.venv并安装全部依赖，同时由于settings.json中的自动激活配置，后续集成终端打开时环境即已就绪。

5. 构建文档

通过以下任一方式启动默认构建任务：

• 按快捷键Ctrl+Shift+B（VS Code 默认的"运行默认构建任务"快捷键）；
• 从命令面板执行Tasks: Run Build Task。

构建完成后，输出将生成到.vscode/build/html/。

6. 打开实时预览

在 VS Code 资源管理器中，右键.vscode/build/html/index.html，选择Open with Live Server。之后每次重新构建文档，Live Server 会自动推送更新，浏览器无需手动刷新即可看到最新内容——这得益于liveServer.settings.wait设置留给 Sphinx 的重建时间窗。

常见问题与排查提示

1. 依赖缺失导致构建报错：如果提示缺少 Python 包，先执行pip install -r docs/sphinx/requirements.txt（Linux 下为pip3 install -r docs/sphinx/requirements.txt），该步骤只需成功执行一次。
2. 改动 Doxygen 注释后结果未更新：若你修改了源码中的 Doxygen 注释，每次构建前应删除docs/doxygen/xml与docs/doxygen/html目录，避免 Breathe 复用陈旧缓存（见 docs/contribute/contributing.md 的相关提示）。
3. 添加新页面后侧边栏没有出现：ROCm 文档的导航由外部目录文件 docs/sphinx/_toc.yml.in 驱动（注意其中${branch}、${url}等变量会在构建时被替换），新增主题后需要在该文件中登记对应的file或url条目。
4. 区分.vscode/build与_build：命令行方式输出到项目根目录的_build/html，VS Code 方式输出到.vscode/build/html。两者互不干扰，但 Live Server 的root配置必须与 VS Code 任务的输出目录保持一致，否则预览会 404。

构建工作流总结

掌握这三种构建方式后，你可以完整走通"本地编写 → 本地验证 → 提交 PR → 云端复查"的 ROCm 文档贡献流程。进一步了解文档写作规范与目录结构，可继续阅读 docs/contribute/contributing.md 与 docs/contribute/toolchain.md。

【免费下载链接】legacy-rocm-buildAMD ROCm™ Software - GitHub Home项目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build