c++ - 如何使用 Sphinx 管理多个版本的文档？

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改善这个问题吗？更新问题，以便可以通过 editing this post 用事实和引文回答问题.

3年前关闭。




Improve this question




我维护一个用 C++ 编写的小型库项目。
我想使用 Sphinx 来维护每个发布版本的库网站 + 用户文档。我找到了[类似的问题How to manage many versions?在 sphinx-dev邮件列表 which I have bumped但没有广泛的后续行动。

如何管理多个版本？

我认为基本结构是这样的:

mylib/     <- website root
mylib/...
mylib/tutorial/...
mylib/doc   <- list of documentation per release version
mylib/doc/1.0.0
mylib/doc/2.0.0
mylib/doc/X.Y.Z

我正在尝试找出这种结构的最佳实用配置。
我有 root 配置 mylib/conf.py我控制网站结构和内容的地方。

我可以将 .rst 文件放入 mylib/doc/1.0.0和 mylib/doc/2.0.0使用根 conf.py 构建它们。但是，控制网站和文档的 toctree 似乎很棘手。

因此，我认为将网站配置/构建与每个发布文档的配置/构建分开可能更实用:

mylib/conf.py
mylib/doc/1.0.0/conf.py
mylib/doc/2.0.0/conf.py
mylib/doc/X.Y.Z/conf.py

但我想要 mylib/doc/X.Y.Z/conf.py 中的主要文件使用相同的布局是 mylib/ 中的根文档，所以我可以有一致的外观，例如页眉中的链接等。

这样我就可以轻松实现一致 toctree每个文档版本。
浏览目录并分别为网站和每个文档版本执行构建应该很容易。

关于搜索文档，我不介意搜索引擎扫描每个查询的所有版本的文档，也不介意搜索引擎特定于特定版本(搜索框显示在同一位置，但取决于正在读取的内容，它仅扫描当前版本的索引)。

有没有更好的方法来实现这一目标？

我在 sphinx for multiple, separate documents 中发现了类似的问题我想知道 Intersphinx plugin这里是个好主意。

更新:

2017-04-10:SO 答案指向一个有趣的 Sphinx 扩展:sphinxcobtrib-versioning

2011-10-21:关注 olt评论中的问题，mylib/不是我想在 VCS 中构建项目的意思。所以，我不想在 VCS 中维护多个版本的文档。 mylib/只是为了更容易可视化的结构。它也可以是我将 Sphinx 源放在一起的工作目录(例如，从版本分支中提取等)以及我启动 Sphinx 以构建输出的位置。

Answer 1

在我看来，文档应该与同一存储库中的代码保持一致。否则，您将需要手动管理文档源，例如，当您将功能从版本 B 向后移植到 A 时。使用单个存储库，您只需检查该版本并重新构建文档。

你应该看看SQLAlchemy项目，他们在同一站点上提供了多个版本的文档。文档位于同一个存储库中，它们 copy the output每个版本的静态主页文件夹。