.. _multiversion:

How multiple versions of the docs are created
=============================================

To make the generation and update of multiple versions of the docs faster,
we rely on a hack around
`sphinx-multiversion <https://github.com/Holzhaus/sphinx-multiversion>`_.

Shortcommings of sphinx-multiversion
------------------------------------

With `sphinx-multiversion <https://github.com/Holzhaus/sphinx-multiversion>`_
there is no way to select a specific subset of the versions for a rebuild.
Because of this one has to rebuild all the versions all the time.
This is quite wasteful on CI resources.

We want to be able to build only specific versions of the docs,
without having to rebuild all the others.

Workaround
----------

Two problems need to get solved here:

1. When building a selected subset of the versions,
   the build process needs to know about other
   non-selected versions.
   
2. When a new version was built and added,
   the older versions should mention the new version
   in their version panel.

The first problem is solved by adding information to the html-context.
The second problem is solved by making all version panels
grab their information from the develop branch,
which is always up to date.

Augmenting the html context
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The html context is a dictonary accessible from the html templates.
Using git, we add a list of all available tags to it.

.. note::
   This is done in `conf.py` since it doesn't seem possible
   to pass this information otherwise.
   There might be a better way that was overseen.

Dynamic version panel
^^^^^^^^^^^^^^^^^^^^^
The html code for the version panel is simply
copied from the panel in develop.

This is done with a javascript call that gets the relevant string
directly from the main html page of the develop folder.

.. note::
   This makes it necessary to run a http sever when browsing multiple versions
   of the docs locally, since the local filesystem is accessed.