From bd9f3ba2a1d9b3c3ad39d350fe6ecb01c9a08cbf Mon Sep 17 00:00:00 2001
From: Sam Tygier <sam.tygier@stfc.ac.uk>
Date: Fri, 11 Dec 2020 09:06:36 +0000
Subject: [PATCH] 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.
https://github.com/Holzhaus/sphinx-multiversion/pull/62
---
 docs/_static/extra.css          |  1 +
 docs/_templates/layout.html     | 17 +++++++++++++++++
 docs/_templates/versioning.html | 21 +++++++++++++++++++++
 docs/conf.py                    | 26 +++++++++++++++++---------
 4 files changed, 56 insertions(+), 9 deletions(-)
 create mode 100644 docs/_static/extra.css
 create mode 100644 docs/_templates/layout.html
 create mode 100644 docs/_templates/versioning.html

diff --git a/docs/_static/extra.css b/docs/_static/extra.css
new file mode 100644
index 00000000000..f4a81a403ba
--- /dev/null
+++ b/docs/_static/extra.css
@@ -0,0 +1 @@
+div.versions {margin-top: 10px}
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
new file mode 100644
index 00000000000..5063ccfd25f
--- /dev/null
+++ b/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 %}
+
diff --git a/docs/_templates/versioning.html b/docs/_templates/versioning.html
new file mode 100644
index 00000000000..58f8f9a706f
--- /dev/null
+++ b/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', '2.0.0'] %}
+  <li><a href="{{ pathto("",1)}}{{ item }}/index.html">{{ item }}</a></li>
+  {%- endfor %}
+</ul>
+</div>
+{% endif %}
diff --git a/docs/conf.py b/docs/conf.py
index 4e97849e062..31b76c512a1 100644
--- a/docs/conf.py
+++ b/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"