From 59d056694115bd346c6e02995f97bcc9e470082c 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                    | 10 +++++++++-
 4 files changed, 48 insertions(+), 1 deletion(-)
 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..bd384e497ee
--- /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'] %}
+  <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 52b6b7011df..745a0a2ad56 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -34,7 +34,7 @@
 # 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.viewcode', 'sphinx.ext.githubpages', 'sphinx.ext.imgmath', 'sphinx_multiversion',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -92,6 +92,7 @@
         'localtoc.html',
         'relations.html',
         'searchbox.html',
+        'versioning.html'
     ]
 }
 
@@ -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"