Merge pull request #165 from billsacks/versioned_docs_cesm21

Update documentation format to versioned documentation - for cesm2.1

Description of changes
Similar to #164 but for cesm2.1-alphabranch.

Also updates documentation source on cesm2.1-alphabranch to bring in changes that were made on master.

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/cesm_configurations.rst

@@ -12,9 +12,9 @@ a science and technical perspective. CESM supports numerous
 <http://www.cesm.ucar.edu/models/cesm2/cesm/compsets.html>`_.  In
 addition, each model component has input options to configure specific
 `model settings
-<http://www.cesm.ucar.edu/models/cesm2/component_xml/index.html>`_
+<http://www.cesm.ucar.edu/models/cesm2/settings/current>`_
 and `parameterizations
-<http://www.cesm.ucar.edu/models/cesm2/component_namelists/index.html>`_.
+<http://www.cesm.ucar.edu/models/cesm2/settings/current>`_.
 
 
 CESM2 Components
@@ -35,7 +35,7 @@ and an external system processing component
 - external system processing (esp) 
 
 In addition CESM2 is accompanied by a `driver/coupler (cpl7)
-<http://esmci.github.io/cime/driver_cpl/index.html>`_ that coordinates
+<http://esmci.github.io/cime/versions/master/html/driver_cpl/index.html>`_ that coordinates
 the time evolution of geophysical components and periodically permits
 the components to exchange data.  Each component is represented in one
 of several modes: "active," "data," "dead," or "stub" that permits the
@@ -73,32 +73,32 @@ The CESM2 components can be summarized as follows:
    :widths: 12, 10, 10, 10, 60
 
    "atmosphere","atm","cam", "active","The `Community Atmosphere Model (CAM) <http://www.cesm.ucar.edu/models/cesm2/atmosphere/>`_ is a global atmospheric general circulation model developed from the NCAR CCM3."                                                                                                                                      
-   "atmosphere","atm","datm", "data", "The `data atmosphere <http://esmci.github.io/cime/data_models/data-atm.html>`_ component is a pure data component that reads in atmospheric forcing data"
+   "atmosphere","atm","datm", "data", "The `data atmosphere <http://esmci.github.io/cime/versions/master/html/data_models/data-atm.html>`_ component is a pure data component that reads in atmospheric forcing data"
    "atmosphere","atm", "xatm", "dead", "Used only for testing the driver/coupler"
    "atmosphere","atm", "satm", "stub", "Used only to satisy the interface requirements"
    "land", "lnd", "clm", "active", "The `Community Land Model (CLM) <http://www.cesm.ucar.edu/models/cesm2/land/>`_ is the result of a collaborative project between scientists in the Terrestrial Sciences Section of the Climate and Global Dynamics Division (CGD) at NCAR and the CESM Land Model Working Group. Other principal working groups that also contribute to the CLM are Biogeochemistry, Paleoclimate, and Climate Change and Assessment."
-   "land", "lnd", "dlnd", "data", "The `data land component <http://esmci.github.io/cime/data_models/data-lnd.html>`_ is a purely data-land component (reading in coupler history data for atm/land fluxes and land albedos produced by a previous run, or snow surface mass balance fields) or both."
+   "land", "lnd", "dlnd", "data", "The `data land component <http://esmci.github.io/cime/versions/master/html/data_models/data-lnd.html>`_ is a purely data-land component (reading in coupler history data for atm/land fluxes and land albedos produced by a previous run, or snow surface mass balance fields) or both."
    "land", "lnd", "xlnd", "dead", "Used only for testing the driver/coupler"
    "land", "lnd", "slnd", "stub", "Used only to satisy the interface requirements"
    "river", "rof", "rtm", "active", "The `river transport model (RTM) <http://www.cesm.ucar.edu/models/cesm2/river/>`_ was previously part of CLM and was developed to route total runoff from the land surface model to either the active ocean or marginal seas which enables the hydrologic cycle to be closed (Branstetter 2001, Branstetter and Famiglietti 1999). This is needed to model ocean convection and circulation, which is affected by freshwater input."
    "river", "rof", "mosart", "active", "`MOdel for Scale Adaptive River Transport (MOSART) <http://www.cesm.ucar.edu/models/cesm2/river/>`_ , a new large-scale river routing model. MOSART improves the magnitude and timing of river flow simulations."
-   "river", "rof", "drof", "data", "The `data runoff model <http://esmci.github.io/cime/data_models/data-river.html>`_ was previously part of the data land model and functions as a purely data-runoff model (reading in runoff data)."
+   "river", "rof", "drof", "data", "The `data runoff model <http://esmci.github.io/cime/versions/master/html/data_models/data-river.html>`_ was previously part of the data land model and functions as a purely data-runoff model (reading in runoff data)."
    "river", "rof", "xrof", "dead", "Used only for testing the driver/coupler"
    "river", "rof", "srof", "stub", "Used only to satisy the interface requirements"
    "ocean", "ocn", "pop", "active", "The ocean model is an extension of the `Parallel Ocean Program (POP) <http://www.cesm.ucar.edu/models/cesm2/ocean/>`_ Version 2 from Los Alamos National Laboratory (LANL)."
-   "ocean", "ocn", "docn", "data", "The `data ocean <http://esmci.github.io/cime/data_models/data-ocean.html>`_ component has two distinct modes of operation. It can run as a pure data model, reading ocean SSTs (normally climatological) from input datasets, interpolating in space and time, and then passing these to the coupler. Alternatively, docn can compute updated SSTs based on a slab ocean model where bottom ocean heat flux convergence and boundary layer depths are read in and used with the atmosphere/ocean and ice/ocean fluxes obtained from the coupler."
+   "ocean", "ocn", "docn", "data", "The `data ocean <http://esmci.github.io/cime/versions/master/html/data_models/data-ocean.html>`_ component has two distinct modes of operation. It can run as a pure data model, reading ocean SSTs (normally climatological) from input datasets, interpolating in space and time, and then passing these to the coupler. Alternatively, docn can compute updated SSTs based on a slab ocean model where bottom ocean heat flux convergence and boundary layer depths are read in and used with the atmosphere/ocean and ice/ocean fluxes obtained from the coupler."
    "ocean", "ocn", "xocn", "dead"
    "ocean", "ocn", "socn", "stub"
    "sea-ice", "ice", "cice", "active", "The `sea-ice component (CICE) <http://www.cesm.ucar.edu/models/cesm2/sea-ice/>`_ is an extension of the Los Alamos National Laboratory (LANL) sea-ice model and was developed though collaboration within the CESM Polar Climate Working Group (PCWG). In CESM, CICE can run as a fully prognostic component or in prescribed mode where ice coverage (normally climatological) is read in."
-   "sea-ice", "ice", "dice", "data", "The `data ice <http://esmci.github.io/cime/data_models/data-seaice.html>`_ component is a partially prognostic model. The model reads in ice coverage and receives atmospheric forcing from the coupler, and then it calculates the ice/atmosphere and ice/ocean fluxes. The data ice component acts very similarly to CICE running in prescribed mode."
+   "sea-ice", "ice", "dice", "data", "The `data ice <http://esmci.github.io/cime/versions/master/html/data_models/data-seaice.html>`_ component is a partially prognostic model. The model reads in ice coverage and receives atmospheric forcing from the coupler, and then it calculates the ice/atmosphere and ice/ocean fluxes. The data ice component acts very similarly to CICE running in prescribed mode."
    "sea-ice", "ice", "xice", "dead", "Used only for testing the driver/coupler"
    "sea-ice", "ice", "sice", "stub"
    "land-ice", "glc", "cism", "active", The `CISM component <http://www.cesm.ucar.edu/models/cesm2/land-ice/>`_ is an extension of the Glimmer ice sheet model.                                                                                                                                                                                        
    "land-ice", "glc", "sglc", "stub", "Used only to satisy the interface requirements"
    "ocean-wave", "wav", "wav", "ww3","The `ww3 <http://www.cesm.ucar.edu/models/cesm2/wave/>`_ component adds prognostic ocean waves to the system" 
    "ocean-wave", "wav", "xwav", "dead", "Used only for testing the driver/coupler"
    "ocean-wave", "wav", "swav", "stub", "Used only to satisy the interface requirements"
-   "coupler", "cpl", "cpl", "active", "The `CESM coupler <http://esmci.github.io/cime/driver_cpl/index.html>`_ was built primarily through a collaboration of the NCAR CESM Software Engineering Group and the Argonne National Laboratory (ANL). The MCT coupling library provides much of the infrastructure."
+   "coupler", "cpl", "cpl", "active", "The `CESM coupler <http://esmci.github.io/cime/versions/master/html/driver_cpl/index.html>`_ was built primarily through a collaboration of the NCAR CESM Software Engineering Group and the Argonne National Laboratory (ANL). The MCT coupling library provides much of the infrastructure."
 
 
 CESM2 Component Sets
@@ -181,7 +181,7 @@ files to fill in information required for the target platform. This
 functionality is handy in accelerating the porting process and quickly
 getting a case running on a new platform. For more information on
 porting, see the `CIME porting guide
-<http://esmci.github.io/cime/users_guide/porting-cime.html>`_.  The
+<http://esmci.github.io/cime/versions/master/html/users_guide/porting-cime.html>`_.  The
 list of available machines are documented in `CESM supported machines
 <http://www.cesm.ucar.edu/models/cesm2/cesm/machines.html>`_.
 Running **query_config** with the ``--machines`` option will also show
@@ -204,7 +204,7 @@ These control runs should be scientifically reproducible on the
 original platform or other platforms. Bit-for-bit reproducibility
 cannot be guaranteed due to variations in compiler or system
 versions. Users should carry out their own `port validations
-<http://esmci.github.io/cime/users_guide/porting-cime.html#validating-your-port>`_
+<http://esmci.github.io/cime/versions/master/html/users_guide/porting-cime.html#validating-your-port>`_
 on any platform prior to doing scientific runs or scientific analysis
 and documentation.
 

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'CESM2.1'
 # The full version, including alpha/beta/rc tags.
-release = u''
+release = u'CESM2.1'
 
 # 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

@@ -8,15 +8,15 @@ Downloading the code and scripts
 --------------------------------
 
 Starting with CESM2, releases are available through a public GitHub
-repository, `http://github.com/ESCOMP/cesm <http://github.com/ESCOMP/cesm>`_. 
+repository, `http://github.com/ESCOMP/CESM <http://github.com/ESCOMP/CESM>`_. 
 
 Access to the code requires both git and Subversion client software in
 place that is compatible with GitHub and our Subversion server
 software.  You will need access to the command line clients, ``git``
 (v1.8 or greater) and ``svn`` (v1.8 or greater but less than v1.11).  
 Currently, our Subversion server
 software is at version 1.8.17. For more information or to download
-open source tools, visit `Subversion <http://subversion.tigris.org/>`_
+open source tools, visit `Subversion <http://subversion.apache.org/>`_
 and `git downloads <https://git-scm.com/downloads>`_.
 
 With valid git and svn clients installed on the machine where CESM will be
@@ -25,7 +25,7 @@ code:
 
 .. code-block:: console
 
-    git clone -b release-cesm2.1.0 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:
@@ -51,7 +51,7 @@ The **checkout_externals** script will read the configuration file called ``Exte
 will download all the external component models and CIME into /path/to/my_cesm_sandbox. 
 
 Details regarding the CESM checkout process are available in the CESM GitHub repo
-`README <http://github.com/ESCOMP/cesm/blob/master/README.rst>`_
+`README <http://github.com/ESCOMP/CESM/blob/master/README.rst>`_
 To see more details regarding the checkout_externals script from the command line, type:
 
 .. code-block:: console

doc/source/introduction.rst

@@ -66,7 +66,7 @@ into the Earth's past, present, and future climate states.
 CESM can be run on a number of different `hardware platforms
 <http://www.cesm.ucar.edu/models/cesm2/cesm/machines.html>`__, and
 has a relatively flexible design with respect to `processor layout
-<http://esmci.github.io/cime/users_guide/pes-threads.html>`__
+<http://esmci.github.io/cime/versions/master/html/users_guide/pes-threads.html>`__
 of components.
 
 The CESM project is a cooperative effort among U.S. climate
@@ -113,7 +113,7 @@ installing and running CESM2.
 
 -  `pnetcdf 1.7.0 is required and 1.8.1 is optional but recommended <http://trac.mcs.anl.gov/projects/parallel-netcdf/>`_
 
--  `Trilinos <http://trilinos.gov/>`_ may be required for certain configurations 
+-  `Trilinos <https://trilinos.github.io/>`_ may be required for certain configurations 
 
 -  `LAPACK <http://www.netlib.org/lapack/>`_ and `BLAS <http://www.netlib.org/blas/>`_