Use sphinx_multiversion to make multiversioned docs

sphinx-multiversion can build a copy of the documentation for each tag
and place in a subfolder. The existing spinx setup can build the top
level latest version. versioning.html gives links to version in the
sidebar. layout.html overrides the main template to use correct versions
in the title and top navigation bar.

Note this requires a patch to sphinx_multiversion to allow calling a
prebuild command. This is used to call the docs_api for each checkout.
sphinx-contrib/multiversion#62

Author: samtygier-stfc

deps/dev-requirements.pip

@@ -6,6 +6,7 @@ mock==3.0.5
 flake8
 pylint
 sphinx
+sphinx-multiversion
 mypy
 yapf
 pytest

docs/_static/extra.css

@@ -0,0 +1 @@
+div.versions {margin-top: 10px}

docs/_templates/layout.html

@@ -0,0 +1,17 @@
+{%- extends "!layout.html" %}
+{%- block htmltitle %}
+  {% if versions %}
+    <title>{{ title|striptags|e }} - {{ project }} {{ current_version.name }} Documentation</title>
+  {% else %}
+    <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
+  {% endif %}
+{%- endblock %}
+
+{%- block rootrellink %}
+  {% if versions %}
+        <li class="nav-item nav-item-0"><a href="{{ pathto(master_doc)|e }}">{{ project }} {{ current_version.name }} Documentation</a>{{ reldelim1 }}</li>
+  {% else %}
+        <li class="nav-item nav-item-0"><a href="{{ pathto(master_doc)|e }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
+  {% endif %}
+{%- endblock %}
+

docs/_templates/versioning.html

@@ -0,0 +1,21 @@
+{% if versions %}
+<div class="versions">
+<h3>{{ _('Versions') }}</h3>
+<ul>
+  <li><a href="../{{ pathto("",1)}}index.html">Latest</a></li>
+  {%- for item in versions %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+</div>
+{% else %}
+<div class="versions">
+<h3>{{ _('Versions') }}</h3>
+<ul>
+  <li><a href="{{ pathto("",1)}}index.html">Latest</a></li>
+  {%- for item in ['0.9.0', '1.0.0', '1.1.0'] %}
+  <li><a href="{{ pathto("",1)}}{{ item }}/index.html">{{ item }}</a></li>
+  {%- endfor %}
+</ul>
+</div>
+{% endif %}

docs/conf.py

@@ -33,8 +33,15 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage',
-    'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'sphinx.ext.imgmath'
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.imgmath',
+    'sphinx_multiversion',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -87,13 +94,7 @@
 # a list of builtin themes.
 html_theme = 'classic'
 
-html_sidebars = {
-    '**': [
-        'localtoc.html',
-        'relations.html',
-        'searchbox.html',
-    ]
-}
+html_sidebars = {'**': ['localtoc.html', 'relations.html', 'searchbox.html', 'versioning.html']}
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -106,6 +107,7 @@
 html_static_path = ['_static']
 
 # -- Options for HTMLHelp output ------------------------------------------
+html_css_files = ['extra.css']
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'MantidImagingdoc'
@@ -158,3 +160,9 @@
 
 # Stop sphinx from being a smartypants and merging the -- into a single unicode dash
 html_use_smartypants = False
+
+# sphinx-multiversion
+smv_tag_whitelist = r'^\d+\.\d+\.\d+$'  # tags that look like versions
+smv_branch_whitelist = None  # No branches
+smv_released_pattern = r''
+smv_prebuild_command = "python setup.py docs_api"

environment.yml

@@ -27,7 +27,8 @@ dependencies:
       - mock
       - pylint
       - sphinx
+      - sphinx-multiversion
       - pytest-randomly
       - pytest-parallel
       - psutil
-      - isort
+      - isort