Merge pull request #164 from billsacks/versioned_docs

Update documentation format to versioned documentation

Description of changes
Switch to versioned documentation using sphinx rtd theme

Follows instructions here
https://drive.google.com/drive/u/0/folders/1WWlz6O1uBPUx7WdgQ24REFnuBrgpCM5U
and here ESMCI/cime#3439

See the result here: https://escomp.github.io/CESM

Specific notes
Contributors other than yourself, if any: none

Fixes: none

User interface changes?: No

Testing performed (automated tests and/or manual tests): none

doc/README

@@ -1,12 +1,35 @@
+
+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 CESM master code base. However, 
+the built html files are stored separately in the orphan gh-pages branch
+and can be viewed from a browser at URL:
+
+http://escomp.github.io/cesm
+
+Details for working with the documentation are contained in the following
+wiki page:
+
+https://github.com/ESMCI/cime/wiki/Working-with-Sphinx-and-reStructuredText
+
+(The procedure is the same for the CESM documentation as for the CIME
+documentation.)
+
 Use the following commands to auto-build the html documentation from the main
 cesm/doc directory:
 
->make clean
->make html
-
-The build/html files should be copied to the appropriate release or
-development https://github.com/ESCOMP/CESM gh-pages orphan branch
-subdirectory and commited to that branch separately.
+make clean
+make html
 
-Only the doc/source files are stored with the code on the master
-branch.
+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('../../manage_externals'))
 
 
@@ -53,17 +56,17 @@
 
 # General information about the project.
 project = u'CESM'
-copyright = u'2018, U.S. National Science Foundation'
+copyright = u'2020, U.S. National Science Foundation'
 author = u'Staff of NSF/NCAR CESM Software Engineering Group' 
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u''
+version = u'master'
 # The full version, including alpha/beta/rc tags.
-release = u''
+release = u'master'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -89,18 +92,25 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'classic'
+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"}
+# 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,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

doc/source/downloading_cesm.rst

@@ -25,7 +25,7 @@ code:
 
 .. code-block:: console
 
-    git clone -b release-cesm2.1.1 https://github.com/ESCOMP/CESM.git my_cesm_sandbox
+    git clone -b release-cesm2.1.3 https://github.com/ESCOMP/CESM.git my_cesm_sandbox
     cd my_cesm_sandbox
 
 To checkout a previous version of CESM, first view the available versions: