Update docs infrastructure

.gitmodules

@@ -123,8 +123,8 @@ fxDONOTUSEurl = https://github.com/NCAR/ParallelIO
 
 [submodule "doc-builder"]
 path = doc/doc-builder
-url = https://github.com/ESMCI/doc-builder
-fxtag = v1.0.8
+url = https://github.com/samsrabin/doc-builder
+fxtag = 30d2d6d48549f68ee300a469af5dfe5ac3eeae81
 fxrequired = ToplevelOptional
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/ESMCI/doc-builder

doc/source/_templates/versions.html

@@ -0,0 +1,64 @@
+{% if READTHEDOCS or display_lower_left %}
+{# Add rst-badge after rst-versions for small badge style. #}
+  <script type="text/javascript">
+    let baseUriRegex = /(.*\/cime)\/.*/g;
+    let parsedUri = baseUriRegex.exec(document.baseURI);
+
+    if (parsedUri != null && parsedUri.length == 2) {
+      let baseUri = parsedUri[1];
+
+      $.get(`${baseUri}/versions/versions.json`, function(data) {
+        let versionElement = $("#versions");
+
+        Object.keys(data).forEach(function(key) {
+          let value = data[key];
+
+          let item = `<dd><a href="${baseUri}/versions/${key}/html/">${value}</a></dd>`
+
+          versionElement.append(item);
+        });
+      });
+    }
+  </script>
+  <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+    <span class="rst-current-version" data-toggle="rst-current-version">
+      <span class="fa fa-book"> Read the Docs</span>
+      v: {{ current_version }}
+      <span class="fa fa-caret-down"></span>
+    </span>
+    <div class="rst-other-versions">
+      {% if languages|length >= 1 %}
+      <dl>
+        <dt>{{ _('Languages') }}</dt>
+        {% for slug, url in languages %}
+          {% if slug == current_language %} <strong> {% endif %}
+          <dd><a href="{{ url }}">{{ slug }}</a></dd>
+          {% if slug == current_language %} </strong> {% endif %}
+        {% endfor %}
+      </dl>
+      {% endif %}
+      <dl id="versions">
+        <dt>Versions</dt>
+      </dl>
+      {% if downloads|length >= 1 %}
+      <dl>
+        <dt>{{ _('Downloads') }}</dt>
+        {% for type, url in downloads %}
+          <dd><a href="{{ url }}">{{ type }}</a></dd>
+        {% endfor %}
+      </dl>
+      {% endif %}
+      {% if READTHEDOCS %}
+      <dl>
+        <dt>{{ _('On Read the Docs') }}</dt>
+          <dd>
+            <a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/?fromdocs={{ slug }}">{{ _('Project Home') }}</a>
+          </dd>
+          <dd>
+            <a href="//{{ PRODUCTION_DOMAIN }}/builds/{{ slug }}/?fromdocs={{ slug }}">{{ _('Builds') }}</a>
+          </dd>
+      </dl>
+      {% endif %}
+    </div>
+  </div>
+{% endif %}

doc/source/conf.py

@@ -18,8 +18,6 @@
 #
 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('.'))
 
@@ -80,7 +78,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -109,9 +107,10 @@
 # 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]'] = ''
+### Sam Rabin 2024-10-02: Commented out to resolve "WARNING: unsupported theme option 'versions' given". Might break things!
+### 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,
@@ -178,7 +177,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/', None)}
 
 numfig = True
 numfig_format = {'figure': 'Figure %s',
@@ -190,3 +189,17 @@
 
 def setup(app):
     app.add_css_file('css/custom.css')
+
+try:
+    html_context
+except NameError:
+    html_context = dict()
+
+html_context["display_lower_left"] = True
+
+html_context["current_language"] = language
+
+current_version = "master"
+
+html_context["current_version"] = current_version
+html_context["version"] = current_version

doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst

@@ -720,7 +720,7 @@ Note that :math:`w_{target}` is truly supposed to give the target soil moisture
 
 :math:`N_{irr}` is the index of the soil layer corresponding to a specified depth :math:`z_{irrig}` (:numref:`Table Irrigation parameters`) and :math:`\Delta z_{j}` is the thickness of the soil layer in layer :math:`j` (section :numref:`Vertical Discretization`). :math:`\theta_{j}` is the volumetric soil moisture in layer :math:`j` (section :numref:`Soil Water`). :math:`\theta_{target}` and :math:`\theta_{wilt}` are the target and wilting point volumetric soil moisture values, respectively, and are determined by inverting :eq:`7.94` using soil matric potential parameters :math:`\Psi_{target}` and :math:`\Psi_{wilt}` (:numref:`Table Irrigation parameters`). After the soil moisture deficit :math:`D_{irrig}` is calculated, irrigation in an amount equal to :math:`\frac{D_{irrig}}{T_{irrig}}` (mm/s) is applied uniformly over the irrigation period :math:`T_{irrig}` (s). Irrigation water is applied directly to the ground surface, bypassing canopy interception (i.e., added to :math:`{q}_{grnd,liq}`: section :numref:`Canopy Water`).
 
-To conserve mass, irrigation is removed from river water storage (Chapter :numref:`rst_River Transport Model (RTM)`). When river water storage is inadequate to meet irrigation demand, there are two options: 1) the additional water can be removed from the ocean model, or 2) the irrigation demand can be reduced such that river water storage is maintained above a specified threshold.
+To conserve mass, irrigation is removed from river water storage (Chapter :numref:`rst_MOSART`). When river water storage is inadequate to meet irrigation demand, there are two options: 1) the additional water can be removed from the ocean model, or 2) the irrigation demand can be reduced such that river water storage is maintained above a specified threshold.
 
 .. _Table Irrigation parameters:
 

doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst

@@ -102,11 +102,11 @@ The default behaviors for the world's glacier and ice sheet regions are describe
 
 .. note::
 
-It is possible to have non-virtual, non-SMB-computing areas within the CISM domain (as is the case for the portion of CISM's Greenland domain outside of Greenland itself). However, these areas will send 0 SMB and will not be able to adjust to CISM-dictated changes in glacier area. Therefore, it is best to set up the glacier regions and their behaviors so that as much of the CISM domain as possible is covered by virtual, SMB-computing areas.
+   It is possible to have non-virtual, non-SMB-computing areas within the CISM domain (as is the case for the portion of CISM's Greenland domain outside of Greenland itself). However, these areas will send 0 SMB and will not be able to adjust to CISM-dictated changes in glacier area. Therefore, it is best to set up the glacier regions and their behaviors so that as much of the CISM domain as possible is covered by virtual, SMB-computing areas.
 
 .. note::
 
- The combination of the ``Glacial melt = Replaced by ice`` and the ``Ice runoff = Melted`` behaviors results in particularly non-physical behavior: During periods of glacial melt, a negative ice runoff is generated (due to the ``Glacial melt = Replaced by ice`` behavior); this negative ice runoff is converted to a negative liquid runoff plus a positive sensible heat flux (due to the ``Ice runoff = Melted`` behavior). The net result is zero runoff but a positive sensible heat flux generated from glacial melt. Because of how physically unrealistic this is, CLM does not allow this combination of behaviors.
+   The combination of the ``Glacial melt = Replaced by ice`` and the ``Ice runoff = Melted`` behaviors results in particularly non-physical behavior: During periods of glacial melt, a negative ice runoff is generated (due to the ``Glacial melt = Replaced by ice`` behavior); this negative ice runoff is converted to a negative liquid runoff plus a positive sensible heat flux (due to the ``Ice runoff = Melted`` behavior). The net result is zero runoff but a positive sensible heat flux generated from glacial melt. Because of how physically unrealistic this is, CLM does not allow this combination of behaviors.
 
 .. _Multiple elevation class scheme:
 

doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst

@@ -923,7 +923,7 @@ Runoff from glaciers and snow-capped surfaces
 
 All surfaces are constrained to have a snow water equivalent :math:`W_{sno} \le W_{cap} = 10,000` kg m\ :sup:`-2`. For snow-capped columns, any addition of mass at the top (precipitation, dew/riping) is balanced by an equally large mass flux at the bottom of the snow column. This so-called capping flux is separated into solid :math:`q_{snwcp,ice}` \ and liquid :math:`q_{snwcp,liq}` runoff terms. The partitioning of these phases is based on the phase ratio in the bottom snow layer at the time of the capping, such that phase ratio in this layer is unaltered.
 
-The :math:`q_{snwcp,ice}` runoff is sent to the River Transport Model (RTM) (Chapter 11) where it is routed to the ocean as an ice stream and, if applicable, the ice is melted there.
+The :math:`q_{snwcp,ice}` runoff is sent to MOSART (Chapter :numref:`rst_MOSART`) where it is routed to the ocean as an ice stream and, if applicable, the ice is melted there.
 
 For snow-capped surfaces other than glaciers and lakes the :math:`q_{snwcp,liq}` runoff is assigned to the glaciers and lakes runoff term :math:`q_{rgwl}` (e.g. :math:`q_{rgwl} =q_{snwcp,liq}` ). For glacier surfaces the runoff term :math:`q_{rgwl}` is calculated from the residual of the water balance
 
@@ -939,4 +939,4 @@ where :math:`W_{b}^{n}` and :math:`W_{b}^{n+1}` are the water balances at the be
 
    W_{b} =W_{can} +W_{sno} +\sum _{i=1}^{N}\left(w_{ice,i} +w_{liq,i} \right) .
 
-Currently, glaciers are non-vegetated and :math:`E_{v} =W_{can} =0`. The contribution of lake runoff to :math:`q_{rgwl}` is described in section :numref:`Precipitation, Evaporation, and Runoff Lake`. The runoff term :math:`q_{rgwl}` may be negative for glaciers and lakes, which reduces the total amount of runoff available to the river routing model (Chapter :numref:`rst_River Transport Model (RTM)`).
+Currently, glaciers are non-vegetated and :math:`E_{v} =W_{can} =0`. The contribution of lake runoff to :math:`q_{rgwl}` is described in section :numref:`Precipitation, Evaporation, and Runoff Lake`. The runoff term :math:`q_{rgwl}` may be negative for glaciers and lakes, which reduces the total amount of runoff available to the river routing model (Chapter :numref:`rst_MOSART`).

doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst

@@ -263,7 +263,7 @@ Biogeophysical and biogeochemical processes are simulated for each subgrid land
 
 #. Glacier processes (Chapter :numref:`rst_Glaciers`)
 
-#. River routing and river flow (Chapter :numref:`rst_River Transport Model (RTM)`)
+#. River routing and river flow (Chapter :numref:`rst_MOSART`)
 
 #. Urban energy balance and climate (Chapter :numref:`rst_Urban Model (CLMU)`)
 

doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst

@@ -1,7 +1,7 @@
-.. _rst_River Transport Model (RTM):
+.. _rst_MOSART:
 
 Model for Scale Adaptive River Transport (MOSART)
-=================================================
+====================================================
 
 .. _Overview MOSART:
 
@@ -21,9 +21,9 @@ MOSART divides each spatial unit such as a lat/lon grid or watershed into three
 
 .. _Figure MOSART conceptual diagram:
 
-.. figure:: mosart_diagram.png
-    :width: 800px
-    :height: 400px
+.. Figure:: mosart_diagram.png
+
+ MOSART conceptual diagram
 
 MOSART only routes positive runoff, although negative runoff can be generated occasionally by the land model (e.g., :math:`q_{gwl}`). Negative runoff in any runoff component including :math:`q_{sur}`, :math:`q_{sub}`, :math:`q_{gwl}` is not routed through MOSART, but instead is mapped directly from the spatial unit where it is generated at any time step to the coupler.
 

doc/source/users_guide/overview/quickstart.rst

@@ -11,7 +11,7 @@ Running the CLM requires a suite of UNIX utilities and programs and you should m
 List of utilities required for CESM in the `Software/OS Prerequisites <https://www2.cesm.ucar.edu/models/cesm1.2/cesm/doc/usersguide/x32.html#software_system_prerequisites>`_ section of the CESM User's Guide.
 
 - UNIX bash shell (for some of the CLM tools scripts)
-- NCL (for some of the offline tools for creating/modifying CLM input datasets; see :ref:`using-ncl` for more information)
+- NCL (for some of the offline tools for creating/modifying CLM input datasets)
 - Python
 
 Before working with |version| read the `CESM QuickStart Guide <https://escomp.github.io/CESM/versions/cesm2.2/html/>`_. Once you are familiar with how to setup cases for any type of simulation with CESM you will want to direct your attention to the specifics of using CLM.

doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst

@@ -6,6 +6,7 @@
 
 .. todo::
   Update the below, as domain files aren't needed with nuopc.
+
 The tools **cprnc** and **gen_domain** use the CIME configure/build system which is described in the next section.
 
 The only CLM FORTRAN tool is mksurfdata_esmf which has it's own build system that takes advantage of the cime build.

doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst

@@ -23,6 +23,7 @@ The list of generally important scripts and programs are as follows.
 
 .. todo::
     Update the below, as domain files aren't needed with nuopc.
+
 #. *$CIMEROOT/tools/mapping/gen_domain_files/gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH datm AND CLM to define the grid and land-mask.
 
 #. ``$CIMEROOT/tools/mapping/gen_domain_files/gen_domain`` to create a domain file for datm from a mapping file. The domain file is then used by BOTH datm AND CLM to define the grid and land-mask.