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

Question

我维护一个用C++编写的小型库项目.我想使用Sphinx维护每个发布版本的库网站+用户文档.我发现[类似问题如何管理多个版本？在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

我正试图找出这种结构的最佳实用配置.我有root配置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版本执行构建.

关于搜索文档,我不介意搜索引擎扫描每个查询的所有文档版本以及我不介意将搜索引擎特定于特定版本(搜索框显示在同一个地方,但取决于正在阅读什么,它只扫描当前版本的索引).

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

我在sphinx中找到了类似的问题,要求提供多个单独的文档,我想知道Intersphinx插件在这里是不是一个好主意.

更新:

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

Answer 1

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

您应该查看SQLAlchemy项目，他们在同一站点上提供了多个版本的文档。文档位于同一存储库中，他们将每个版本的输出复制到其静态主页文件夹中。