Updates to documentation build for maint56

doc/Makefile

@@ -27,10 +27,26 @@ Tools_api:
 
 Tools_user:
 	rm -f $(SOURCEDIR)/$@/*.rst
-	rm -f $(SOURCEDIR)/$@/temp_files/*.*
+	rm -f $(SOURCEDIR)/$@/temp_files/*
 	./tools_autodoc.py
 
-.PHONY: help Makefile CIME_api Tools_api Tools_user
+# It's too easy to forget to run 'make api' before running 'make html',
+# so add a rule that ensures that the api documentation is regenerated
+# whenever regenerating the html.
+html: api
+
+clean: clean_api
+
+# Note that all of the files removed here are built using 'make api';
+# these are not - or at least, should not be - files that exist in the
+# repository.
+clean_api:
+	rm -f $(SOURCEDIR)/CIME_api/*.rst
+	rm -f $(SOURCEDIR)/Tools_api/*.rst
+	rm -f $(SOURCEDIR)/Tools_user/*.rst
+	rm -f $(SOURCEDIR)/Tools_user/temp_files/*
+
+.PHONY: help Makefile CIME_api Tools_api Tools_user clean_api
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

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,9 +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
-
-
+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.

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}));
+            }
+        });
+    });
+});

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 %}

doc/source/_templates/layout.html

@@ -0,0 +1,3 @@
+{% extends "!layout.html" %}
+
+{% set script_files = script_files + ["_static/pop_ver.js"] %}

doc/source/conf.py

@@ -18,6 +18,9 @@
 #
 import os
 import sys
+# 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'))
 
@@ -64,9 +67,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'5.6'
+version = u'cime5.6'
 # The full version, including alpha/beta/rc tags.
-release = u'5.6'
+release = u'cime5.6'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -94,15 +97,24 @@
 #
 #html_theme = 'alabaster'
 #html_theme = 'bizstyle'
-html_theme = 'classic'
-#html_theme = 'sphinx_rtd_theme'
+#html_theme = 'classic'
 #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
 # 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,