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

Question

我维护一个用C ++编写的小型库项目。 我想使用Sphinx维护每个发布版本的库网站+用户文档。我在[{3}}邮件列表How to manage many versions?上找到[类似问题sphinx-dev，但没有进行大量跟进。

如何管理多个版本？

我想到这样的基本结构：

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

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

我可以将.rst文件放入mylib/doc/1.0.0，mylib/doc/2.0.0使用root 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。 它应该很容易遍历目录并分别为网站和每个doc版本执行构建。

关于搜索文档，我不介意搜索引擎扫描每个查询的所有文档版本以及我不介意将搜索引擎特定于特定版本（搜索框显示在同一个地方，但根据所读取的内容，它仅扫描当前版本的索引。

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

我在which I have bumped中发现了类似的问题，我想知道sphinx for multiple, separate documents在这里是不是一个好主意。

更新：

• 2017-04-10：SO答案指向一个有趣的Sphinx扩展：Intersphinx plugin
• 2011-10-21：在评论中提到sphinxcobtrib-versioning的问题，mylib/并不是我在VCS中构建项目的意思。所以，我不想在VCS中维护多个版本的文档。 mylib/只是简化可视化的结构。它也可以是我将Sphinx源放在一起的工作目录（例如从版本分支中取出等）以及我在哪里启动Sphinx来构建输出。

Answer 1

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

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