主要观点：分享用 Bazel 管理 Sphinx 项目的经验，帮助他人决定 Bazel 是否对其 Sphinx 项目有益，包括好的方面（统一 CLI、易环境设置、无需虚拟环境、边车友好、生态系统健壮）、坏的方面（显式构建图、更多间接性）和丑的方面（缺乏增量构建、可能不完整文档、Starlark 猜测游戏）。
关键信息：

• Sphinx 用于编写文档，Bazel 主要用于构建软件，“用 Bazel 管理 Sphinx 项目”指通过 Bazel 构建系统协调核心 Sphinx 工作流。
• 作者有 5 年 Sphinx 经验，曾将雇主文档从 Word 迁移到 Sphinx，近期将 pigweed.dev 迁移到 Bazel。
• 很多 Sphinx 项目不用构建系统，而作者发现基于 Bazel 的构建更易维护，且在中大型项目中有很多优势。
• 选择 Bazel 而非其他构建系统，如 GN，是因为其能提高嵌入式开发人员生产力。
• 统一 CLI 可运行多种工作流；易环境设置只需三步克隆、切换目录和构建；无需虚拟环境，通过 Hermeticity 保证输出一致；边车友好利于软件工程师更新文档；生态系统健壮，大部分所需规则已存在社区模块。
• 采用 Bazel 需前期投入，增加复杂度，如显式构建图需声明所有输入，更多间接性导致生成 HTML 路径不明显。
• Bazel 管理 Sphinx 项目时缺乏增量构建，每次构建都需 10 秒，即使只改一行代码；可能有不完整文档；自定义规则需用 Starlark，其与 Python 有差异，易出错。
  重要细节：
• pigweed.dev有 600 多页内容，集成 3 种 API 参考自动生成管道。
• 以迁移 pigweed.dev为例说明 Bazel 的优势和不足。
• 提到 bzlmod 是共享 Bazel 规则的主要机制，如 rules_python 支持构建 Sphinx 项目。
• 列举了在迁移过程中遇到的具体问题，如核心工具难找、Starlark 出错等。