特色：文档非集中式管理

  • 多版本管理：使用拓展sphinx_multiversion。此拓展原理是搜索ref并为每个ref创建一个临时目录，使用当前conf.py运行该临时目录，因此可以起到统一格式的效果。
  • 问题：无法变更ref.name，例如希望将main分支指定为latest，则无法达到这种效果（因为sphinx_multiversion的versions.json是自动生成的，其中可以指定outputdir，但依赖的是pyformat，无法嵌入字典替换

多版本 Sphinx 文档管理实践（2025年9月23日）

背景

之前项目一直采用 sphinx_multiversion 来做多版本文档管理，但由于项目中存在大量文件的增删改需求，虽然尝试通过一些轻度 hack 实现所需功能，整个流程却极其繁琐冗余。sphinx_multiversion 作为一个插件，构建前内部会将大量数据缓存固化，导致必须在 conf.py 中用复杂的 Sphinx 生命周期钩子反复插手处理这些缓存，改完后还要重新覆盖缓存数据，维护和调试成本极高，开发体验很差。

所以前段时间，抽空在 data-juicer (v1.4.3) 仓库中尝试实现了一个不依赖 sphinx_multiversion 的多版本文档管理方案，核心思想是利用 git worktree 创建并管理独立的工作树，避免了冗余克隆和繁复的缓存操作，支持每个版本随意增删改文件，完整实现见：
docs/sphinx_doc/build_versions.py

核心思路

  • 利用 git worktree 创建独立工作目录用来检出不同版本的源码。
  • 相比传统的临时文件夹 + git clone 或 git checkout，用 git worktree 更简洁，且运行高效。
  • 多个工作树共享同一个 .git 目录和 Git 对象数据库，节约空间。

优劣点及注意事项

  • 优势：
    • 只需一次仓库，避免重复克隆和重复存储。
    • 简化版本切换和管理流程。
    • 方便清理，不留垃圾。
  • 潜在问题：
    • 在 GitHub Actions（GHA）这类 CI 环境中，某些情况下可能会出现 git worktree 相关问题（不过本人迄今未遇见影响构建的情况，整体运行稳定）。

与其他多版本管理方案的对比

方面 本方案 (git worktree) sphinx_multiversion ReadTheDocs
额外文件集成 支持对每个版本构建前随意增删改文件，灵活修复历史版本文档 不支持（conf.py 嵌入插件，难以灵活扩展） 每个版本挂载于不同分支，各版本独立，维护复杂样式难统一
统一文档样式 文档模板固定使用当前仓库最新版本，保证样式一致性 也是统一的，但取消使用较麻烦 版本隔离，样式可能不一致
易用性 脚本独立于 conf.py，不修改 Sphinx 配置文件；构建灵活可控 必须改动 conf.py，不方便禁用 由平台统一管理，但版本隔离且混乱
灵活度 支持版本间互相覆盖、文件增删改 插件功能受限 平台托管限制较多

总结

  • 该基于 git worktree 的多版本管理方案融合了从 ReadTheDocs 和 sphinx_multiversion 中学到的优点。
  • 实现了真正自由且高效的多版本文档构建，特别是额外文件灵活集成，对历史版本修复特别友好。
  • 兼顾文档样式统一和构建灵活可控，自我感觉是当前市面上少有的简洁且实用的 Sphinx 多版本管理方法。
  • 推荐在有条件的项目中采用此方案，替代 ReadTheDocs 内置或 sphinx_multiversion 插件。