I maintain a small library project written in C++. I'd like to use Sphinx to maintain the library website + user documentation per release version. I have found [similar question asked How to manage many versions? on the sphinx-dev mailing list which I have bumped but without extensive follow-up.
我维护一个用c++编写的小型库项目。我想使用Sphinx来维护每个版本版本的库网站+用户文档。我发现[类似的问题是如何管理多个版本?在sphinx-dev邮件列表中，我遇到了一些问题，但没有进行广泛的跟踪。
How to manage many versions?
如何管理多个版本?
I think of basic structure like this:
我想到的基本结构是这样的:
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
I'm trying to figure out best practical configuration for this structure. I have root configuration mylib/conf.py where I control the website structure and content.
我想找出这个结构的最佳实际配置。我有根配置mylib/conf。py，我控制网站结构和内容。
I could put .rst files into mylib/doc/1.0.0 and mylib/doc/2.0.0 build them using the root conf.py. But then it seems tricky to control toctree for website and for docs.
我可以将.rst文件放入mylib/doc/1.0.0中，mylib/doc/2.0.0使用root conf.py构建它们。但对于网站和文档来说，似乎很难控制toctree。
So, I think it may be more practical to separate website config/build from per release documentation config/builds:
因此，我认为将网站配置/构建与每个发布文档配置/构建分开可能更实用:
mylib/conf.py
mylib/doc/1.0.0/conf.py
mylib/doc/2.0.0/conf.py
mylib/doc/X.Y.Z/conf.py
but I'd like the main documents in mylib/doc/X.Y.Z/conf.py to use the same layout is the root documents in mylib/, so I can have consistent look, e.g. links in page header, etc.
但是我想要主要文件在mylib/doc/X.Y.Z/conf。使用相同布局的py是mylib/中的根文档，因此我可以有一致的外观，例如页眉中的链接等。
This way I can easily achieve consistent toctree per documentation release. It should be easy to walk the directories and perform builds for website and for each doc version separately.
通过这种方式，我可以轻松地实现每个文档发布的一致的toctree。应该很容易遍历目录并分别为网站和每个doc版本执行构建。
Regarding searching the documentation, I don't mind the search engine to scan all versions of documentation per single query as well as I don't mind to have search engine specific to particular version (search box is displayed in the same place, but depending what is being read, it scans index of current version only).
关于搜索的文档,我不介意搜索引擎扫描所有版本的文档每单查询以及我不介意有搜索引擎针对特定版本(搜索框显示在同一个地方,但被阅读,它仅扫描索引的当前版本)。
Is there any better way to achieve that?
有更好的方法实现这一点吗?
I've found similar question asked in sphinx for multiple, separate documents and I'm wondering if the Intersphinx plugin is a good idea here.
我在sphinx中发现了类似的问题，用于多个独立的文档，我想知道Intersphinx插件是否是个好主意。
UPDATE:
更新:
- 2017-04-10: SO answer pointing to an interesting Sphinx extension: sphinxcobtrib-versioning
- 2017-04-10:回答指向一个有趣的Sphinx扩展:sphinxcobtrib版本控制
- 2011-10-21: Following olt's question in comments,
mylib/is not how I mean to structure project in VCS. So, I don't want to maintain multiple versions of documentation in VCS. Themylib/is just structure for easier visualisation. It can be also working directory where I put Sphinx sources together (e.g. pull from version branches, etc.) and where I launch Sphinx to build the output. - 2011-10-21:根据olt在评论中的问题，mylib/不是我在vc中构建项目的意思。因此，我不希望在VCS中维护文档的多个版本。mylib/只是结构，便于可视化。它也可以是工作目录，我将Sphinx源代码放在一起(例如，从版本分支中提取)，以及在哪里启动Sphinx来构建输出。
1 个解决方案
#1
2
In my opinion, the documentation should stay with the code in the same repository. Otherwise you would need to manage the documentation source manually, for example when you backport a feature from version B to A. With a single repository, you just check out that version and re-build the documentation.
在我看来，文档应该保留在同一个存储库中的代码。否则，您将需要手动管理文档源，例如，当您将一个特性从版本B返回到a时，您只需检查该版本并重新构建文档。
You should look at SQLAlchemy project, they have multiple versions of their documentation available on the same site. The documentation is in the same repository and they copy the output of each version into their static homepage folders.
您应该查看SQLAlchemy项目，它们在同一个站点上有多个版本的文档。文档位于同一个存储库中，它们将每个版本的输出复制到它们的静态主页文件夹中。
#1
2
In my opinion, the documentation should stay with the code in the same repository. Otherwise you would need to manage the documentation source manually, for example when you backport a feature from version B to A. With a single repository, you just check out that version and re-build the documentation.
在我看来，文档应该保留在同一个存储库中的代码。否则，您将需要手动管理文档源，例如，当您将一个特性从版本B返回到a时，您只需检查该版本并重新构建文档。
You should look at SQLAlchemy project, they have multiple versions of their documentation available on the same site. The documentation is in the same repository and they copy the output of each version into their static homepage folders.
您应该查看SQLAlchemy项目，它们在同一个站点上有多个版本的文档。文档位于同一个存储库中，它们将每个版本的输出复制到它们的静态主页文件夹中。