From d95f3e74554b3e97ad79d3f57d698e9a0dd2c329 Mon Sep 17 00:00:00 2001
From: Bill Sacks <sacks@ucar.edu>
Date: Fri, 6 Mar 2020 10:29:37 -0700
Subject: [PATCH 1/4] Allow versioned documentation with a pull-down menu

This changes the documentation theme to use the readthedocs theme, with
some JavaScript that provides capabilities for a dropdown menu allowing
you to select between different versions.

This mimics the changes in
https://github.com/ESCOMP/CISM-wrapper/pull/23

The changes in this commit assume that sphinx_rtd_theme is installed in
_themes. However, we are not going to do this here: instead, we'll rely
on a pip install of an appropriate branch of sphinx_rtd_theme, using:

pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes

A follow-up commit will fix that.
---
 doc/source/_static                |  0
 doc/source/_static/pop_ver.js     | 37 +++++++++++++++++++++++++++++++
 doc/source/_templates/footer.html |  5 +++++
 doc/source/_templates/layout.html |  3 +++
 doc/source/conf.py                | 23 ++++++++++++++-----
 5 files changed, 62 insertions(+), 6 deletions(-)
 delete mode 100644 doc/source/_static
 create mode 100644 doc/source/_static/pop_ver.js
 create mode 100644 doc/source/_templates/footer.html
 create mode 100644 doc/source/_templates/layout.html

diff --git a/doc/source/_static b/doc/source/_static
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/doc/source/_static/pop_ver.js b/doc/source/_static/pop_ver.js
new file mode 100644
index 00000000000..b8c58658a82
--- /dev/null
+++ b/doc/source/_static/pop_ver.js
@@ -0,0 +1,37 @@
+$(document).ready(function() {
+    /* For a URL that looks like
+    https://blah.github.io/versions/VERSIONFOO/html/bar/index.html, set cur_version_dir to
+    'VERSIONFOO' (i.e., the portion of the path following 'versions').
+    */
+    var proj_end = document.baseURI.indexOf("versions") + 9;
+    var end = document.baseURI.indexOf("/", proj_end);
+    var cur_version_dir = document.baseURI.substring(proj_end, end);
+    var mylist = $("#version-list");
+    mylist.empty();
+    $.getJSON(version_json_loc, function(data) {
+        if (data.hasOwnProperty(cur_version_dir)) {
+            /* First add the current version so that it appears first in the drop-down
+               menu and starts as the selected element of the menu. If you click on the
+               current version, you should stay at the current page.
+
+               The conditional around this block should generally be true, but we check it
+               just in case the current version is missing from the versions.json file for
+               some reason.
+            */
+            cur_version_name = data[cur_version_dir];
+            mylist.append($("<option>", {value: document.baseURI, text: cur_version_name}));
+        }
+        // Now add the other versions
+        $.each(data, function(version_dir, version_name) {
+            if (version_dir != cur_version_dir) {
+                /* If you click on a different version, you should go to the root of the
+                   documentation for that version. This assumes paths like
+                   https://blah.github.io/versions/VERSIONFOO/html/bar/index.html. So we
+                   need to go up two levels from the URL_ROOT (html) to then go back down
+                   into the appropriate version's html directory.
+                */
+                mylist.append($("<option>", {value: DOCUMENTATION_OPTIONS.URL_ROOT + '../../' + version_dir + '/html', text: version_name}));
+            }
+        });
+    });
+});
diff --git a/doc/source/_templates/footer.html b/doc/source/_templates/footer.html
new file mode 100644
index 00000000000..a7c22a302a3
--- /dev/null
+++ b/doc/source/_templates/footer.html
@@ -0,0 +1,5 @@
+{% extends "!footer.html" %}
+{% block extrafooter %}
+    {{ super() }}
+<script>var version_json_loc = "{{ pathto('../../versions.json', 1) }}";</script>
+{% endblock %}
diff --git a/doc/source/_templates/layout.html b/doc/source/_templates/layout.html
new file mode 100644
index 00000000000..6ec6be4302a
--- /dev/null
+++ b/doc/source/_templates/layout.html
@@ -0,0 +1,3 @@
+{% extends "!layout.html" %}
+
+{% set script_files = script_files + ["_static/pop_ver.js"] %}
\ No newline at end of file
diff --git a/doc/source/conf.py b/doc/source/conf.py
index f94a5ec8960..538b9763b8b 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -18,6 +18,7 @@
 #
 import os
 import sys
+#import sphinx_rtd_theme
 sys.path.insert(0, os.path.abspath('../../scripts/lib'))
 sys.path.insert(1, os.path.abspath('../../scripts'))
 
@@ -64,9 +65,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'5.6'
+version = u'master'
 # The full version, including alpha/beta/rc tags.
-release = u'5.6'
+release = u'master'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -78,7 +79,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = []
+exclude_patterns = ["_themes/**"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -94,15 +95,25 @@
 #
 #html_theme = 'alabaster'
 #html_theme = 'bizstyle'
-html_theme = 'classic'
-#html_theme = 'sphinx_rtd_theme'
+#html_theme = 'classic'
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = ["_themes/sphinx_rtd_theme", ]
 #html_theme = 'sphinxdoc'
 
 # 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
 # documentation.
 #
-html_theme_options = {"stickysidebar": "true"}
+#html_theme_options = {"stickysidebar": "true"}
+
+# The 'versions' option needs to have at least two versions to work, but it doesn't need
+# to have all versions: others will be added dynamically. Note that this maps from version
+# names to html links. The current version can link to the current location (i.e., do
+# nothing). For the other version, we just add a place-holder; its name and value are
+# unimportant because these versions will get replaced dynamically.
+html_theme_options = {}
+html_theme_options['versions'] = {version: ''}
+html_theme_options['versions']['[placeholder]'] = ''
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

From 0307839167205fd4f3e2b9ffa94db0a3b1ff4a74 Mon Sep 17 00:00:00 2001
From: Bill Sacks <sacks@ucar.edu>
Date: Fri, 6 Mar 2020 16:26:20 -0700
Subject: [PATCH 2/4] Changes to use sphinx_rtd_theme from pip install rather
 than in _themes

I don't like having this theme as a subtree for two reasons:
- Bloats the cime repo
- If we do this in all projects that need it, that's a maintenance issue
  if we need to update it. It would be better if we could just make
  updates to the themes in one place.

This assumes that we have done a pip install of the correct branch:

pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes
---
 doc/source/conf.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 538b9763b8b..b33a3cf8383 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -18,7 +18,9 @@
 #
 import os
 import sys
-#import sphinx_rtd_theme
+# Note that we need a specific version of sphinx_rtd_theme. This can be obtained with:
+# pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes
+import sphinx_rtd_theme
 sys.path.insert(0, os.path.abspath('../../scripts/lib'))
 sys.path.insert(1, os.path.abspath('../../scripts'))
 
@@ -39,6 +41,7 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.viewcode',
     'sphinx.ext.todo',
+    'sphinx_rtd_theme',
     'sphinxcontrib.programoutput'
 ]
 todo_include_todos=True
@@ -79,7 +82,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_themes/**"]
+exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -96,9 +99,8 @@
 #html_theme = 'alabaster'
 #html_theme = 'bizstyle'
 #html_theme = 'classic'
-html_theme = 'sphinx_rtd_theme'
-html_theme_path = ["_themes/sphinx_rtd_theme", ]
 #html_theme = 'sphinxdoc'
+html_theme = 'sphinx_rtd_theme'
 
 # 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

From 50bdb88c7053364bbba9694f19a35d82aae71eec Mon Sep 17 00:00:00 2001
From: Bill Sacks <sacks@ucar.edu>
Date: Sun, 8 Mar 2020 15:59:44 -0600
Subject: [PATCH 3/4] Remove sphinx_rtd_theme from list of extensions

When it was in the list of extensions, I got this warning when building
documentation:

WARNING: extension 'sphinx_rtd_theme' has no setup() function; is it really a Sphinx extension module?

I'm thinking that we're using an older version of sphinx_rtd_theme that
doesn't support this. From the documentation, I see:

   Adding this theme as an extension is what enables localization of
   theme strings in your translated output. If these strings are not
   translated in your output, either we lack the localized strings for
   your locale, or you are using an old version of the theme.
---
 doc/source/conf.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index b33a3cf8383..a57408fde19 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -41,7 +41,6 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.viewcode',
     'sphinx.ext.todo',
-    'sphinx_rtd_theme',
     'sphinxcontrib.programoutput'
 ]
 todo_include_todos=True

From 758a5b81024ecbf71a1b6867637cd462a60a1e30 Mon Sep 17 00:00:00 2001
From: Bill Sacks <sacks@ucar.edu>
Date: Sun, 8 Mar 2020 16:47:21 -0600
Subject: [PATCH 4/4] Update doc README

Add pip install commands, remove some pieces that are no longer correct.
---
 doc/README | 28 +++++++++++++---------------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/doc/README b/doc/README
index 96462605d3d..b8e0e530e94 100644
--- a/doc/README
+++ b/doc/README
@@ -1,12 +1,17 @@
 
-This requires Sphinx v1.7 or greater. 
+This requires Sphinx v1.7 or greater, as well as some add-ons, which can
+be installed with:
+
+pip install sphinx
+pip install sphinxcontrib-programoutput
+pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes
 
 Check the sphinx version as follows:
 
 >sphinx-build --version
 
 The documentation source is stored with the CIME master code base. However, 
-the built html files are stored seperately in the orphan gh-pages branch
+the built html files are stored separately in the orphan gh-pages branch
 and can be viewed from a browser at URL:
 
 http://esmci.github.io/cime
@@ -19,17 +24,10 @@ https://github.com/ESMCI/cime/wiki/Working-with-Sphinx-and-reStructuredText
 Use the following commands to auto-build the html documentation from the main
 cime/doc directory:
 
->make clean
->make api
->make html
-
-To copy the html to the orphan gh-pages, follow these steps:
-
->git clone -b gh-pages https://github.com/ESMCI/cime.git cime.gh-pages
->cd cime.gh-pages
->rm -rf *
->cp -R /path/to/cime-master/doc/build/html/* .
->git commit -m 'update HTML for PR #...'
->git push origin gh-pages
-
+make clean
+make api
+make html
 
+To publish the docs to the orphan gh-pages branch, follow the steps in
+https://github.com/ESMCI/cime/wiki/Working-with-Sphinx-and-reStructuredText
+to ensure proper versioning of the documentation.