From 801d32a751529f12874ccfc042bb1d6e88d6c1c2 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
---
 deps/dev-requirements.pip       |  1 +
 docs/_static/extra.css          |  1 +
 docs/_templates/layout.html     | 17 +++++++++++++++++
 docs/_templates/versioning.html | 21 +++++++++++++++++++++
 docs/conf.py                    | 26 +++++++++++++++++---------
 environment.yml                 |  3 ++-
 6 files changed, 59 insertions(+), 10 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/deps/dev-requirements.pip b/deps/dev-requirements.pip
index ed3b90f5da9..d48a43e3d3e 100644
--- a/deps/dev-requirements.pip
+++ b/deps/dev-requirements.pip
@@ -5,6 +5,7 @@ gitpython == 3.1.0
 flake8
 pylint
 sphinx
+sphinx-multiversion
 mypy
 yapf
 pytest
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 4bc40fbb566..df9b5ce97d2 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"
diff --git a/environment.yml b/environment.yml
index e4838852e14..dde06dc3aa2 100644
--- a/environment.yml
+++ b/environment.yml
@@ -27,7 +27,8 @@ dependencies:
       - mock
       - pylint
       - sphinx
+      - sphinx-multiversion
       - pytest-randomly
       - pytest-parallel
       - psutil
-      - isort
\ No newline at end of file
+      - isort