title: How to manage multiple versions of documentation with Sphinx?
body: <p>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 <a href="https://groups.google.com/group/sphinx-dev/browse_thread/thread/fb8ba5cfa890b587/" rel="nofollow noreferrer">How to manage many versions?</a> on the <a href="https://groups.google.com/group/sphinx-dev/" rel="nofollow noreferrer">sphinx-dev</a> mailing list <a href="https://groups.google.com/group/sphinx-dev/browse_thread/thread/d907b2447e073cea" rel="nofollow noreferrer">which I have bumped</a> but without extensive follow-up.</p>
  
  <p>How to manage many versions?</p>
  
  <p>I think of basic structure like this:</p>
  
  <pre><code>mylib/     &lt;- website root
  mylib/...
  mylib/tutorial/...
  mylib/doc   &lt;- list of documentation per release version
  mylib/doc/1.0.0
  mylib/doc/2.0.0
  mylib/doc/X.Y.Z
  </code></pre>
  
  <p>I'm trying to figure out best practical configuration for this structure.
  I have root configuration <code>mylib/conf.py</code> where I control the website structure and content.</p>
  
  <p>I could put .rst files into <code>mylib/doc/1.0.0</code> and <code>mylib/doc/2.0.0</code> build them using the root conf.py. But then it seems tricky to control toctree for website and for docs.</p>
  
  <p>So, I think it may be more practical to separate website config/build from per release documentation config/builds:</p>
  
  <pre><code>mylib/conf.py
  mylib/doc/1.0.0/conf.py
  mylib/doc/2.0.0/conf.py
  mylib/doc/X.Y.Z/conf.py
  </code></pre>
  
  <p>but I'd like the main documents in <code>mylib/doc/X.Y.Z/conf.py</code> to use the same layout is the root documents in <code>mylib/</code>, so I can have consistent look, e.g. links in page header, etc.</p>
  
  <p>This way I can easily achieve consistent <code>toctree</code> per documentation release.
  It  should be easy to walk the directories and perform builds for website and for each doc version separately.</p>
  
  <p>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).</p>
  
  <p>Is there any better way to achieve that?</p>
  
  <p>I've found similar question asked in <a href="https://stackoverflow.com/questions/6836080/sphinx-for-multiple-separate-documents">sphinx for multiple, separate documents</a> and I'm wondering if the <a href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html" rel="nofollow noreferrer">Intersphinx plugin</a> is a good idea here.</p>
  
  <p>UPDATE:</p>
  
  <ul>
  <li>2017-04-10: SO answer pointing to an interesting Sphinx extension: <a href="https://stackoverflow.com/a/38927796/151641">sphinxcobtrib-versioning</a></li>
  <li>2011-10-21: Following <a href="https://stackoverflow.com/users/19759/olt">olt</a>'s question in comments, <code>mylib/</code> is not how I mean to structure project in VCS. So, I don't want to maintain multiple versions of documentation in VCS. The <code>mylib/</code> 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.</li>
  </ul>