How to manage multiple versions of documentation using Sphinx?

Question

I support a small library project written in C ++. I would like to use Sphinx to support the library website + user documentation for each version. I found [a similar question asked How to manage many versions? on the sphinx-dev mailing list that I came across , but without detailed observation.

How to manage many versions?

I think of the basic structure as follows:

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/XYZ 

I am trying to find the best practical configuration for this structure. I have a root configuration of mylib/conf.py where I control the structure and contents of the website.

I could put .rst files in mylib/doc/1.0.0 and mylib/doc/2.0.0 them using root conf.py. But then it seems difficult to control toctree for a website and for documents.

So, I think it may be more practical to separate the website configuration / assembly from each version of the config / builds documentation:

 mylib/conf.py mylib/doc/1.0.0/conf.py mylib/doc/2.0.0/conf.py mylib/doc/XYZ/conf.py 

but I would like the main documents in mylib/doc/XYZ/conf.py use the same layout - these are the root documents in mylib/ , so I can have a consistent look, for example. links in the page title, etc.

That way, I can easily achieve a consistent toctree for the release of documentation. This should be easy to navigate through directories and build for the website and for each version of the doc separately.

Regarding the search for documentation, I do not mind that the search engine crawls all versions of the documentation for one request, and I do not mind the presence of a search system for a specific version (the search window appears in the same place, but depending on what is being read, it checks current version index only).

Is there a better way to achieve this?

I found a similar question in sphinx for several separate documents , and I wonder if the Intersphinx Plugin is a good idea.

UPDATE:

• 2017-04-10: SO answer indicating an interesting Sphinx extension: sphinxcobtrib-versioning
• 2011-10-21: Following olt in the comments, mylib/ does not mean that I want to structure the project in VCS. Therefore, I do not want to support multiple versions of the documentation in VCS. mylib/ is just a structure to simplify visualization. It can also be a working directory in which I add Sphinx sources (for example, pull from version branches, etc.) and where I run Sphinx to create output.

Answer 1

In my opinion, the documentation should remain with the code in the same repository. Otherwise, you will need to manually manage the source of the documentation, for example, when you transfer the function back from version B to A. With a single repository, you simply check this version and rebuild the documentation.

You should look at the SQLAlchemy project, they have several versions of their documentation available on the same site. The documentation is in the same repository, and they copy the output of each version to their static folders on the home page.