From bca4618f58e801f20776c48ae5773702369f9139 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Wed, 2 Oct 2024 21:57:51 -0600
Subject: [PATCH 01/40] Point doc-builder to my fork. Avoid old fork of
 sphinx_rtd_theme.

Based on https://github.com/ESMCI/cime/pull/4613. Builds OK, but I'm not sure if the new versions setup works.
---
 .gitmodules                         |  4 +-
 doc/doc-builder                     |  2 +-
 doc/source/_static/pop_ver.js       | 37 -----------------
 doc/source/_templates/layout.html   |  3 --
 doc/source/_templates/versions.html | 64 +++++++++++++++++++++++++++++
 doc/source/conf.py                  | 16 +++++++-
 6 files changed, 81 insertions(+), 45 deletions(-)
 delete mode 100644 doc/source/_static/pop_ver.js
 delete mode 100644 doc/source/_templates/layout.html
 create mode 100644 doc/source/_templates/versions.html

diff --git a/.gitmodules b/.gitmodules
index 7274b9acd2..d60b9bf157 100644
--- a/.gitmodules
+++ b/.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
diff --git a/doc/doc-builder b/doc/doc-builder
index ab9bc93dd0..30d2d6d485 160000
--- a/doc/doc-builder
+++ b/doc/doc-builder
@@ -1 +1 @@
-Subproject commit ab9bc93dd09d0173f8097c7a18c7d061c1cd3b79
+Subproject commit 30d2d6d48549f68ee300a469af5dfe5ac3eeae81
diff --git a/doc/source/_static/pop_ver.js b/doc/source/_static/pop_ver.js
deleted file mode 100644
index b8c58658a8..0000000000
--- a/doc/source/_static/pop_ver.js
+++ /dev/null
@@ -1,37 +0,0 @@
-$(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/layout.html b/doc/source/_templates/layout.html
deleted file mode 100644
index 6ec6be4302..0000000000
--- a/doc/source/_templates/layout.html
+++ /dev/null
@@ -1,3 +0,0 @@
-{% extends "!layout.html" %}
-
-{% set script_files = script_files + ["_static/pop_ver.js"] %}
\ No newline at end of file
diff --git a/doc/source/_templates/versions.html b/doc/source/_templates/versions.html
new file mode 100644
index 0000000000..9d73e5f33f
--- /dev/null
+++ b/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 %}
\ No newline at end of file
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 894e9b6c66..23ef653bed 100644
--- a/doc/source/conf.py
+++ b/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('.'))
 
@@ -190,3 +188,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

From 4c2361dd28b696499a5da6835664cef3b7673c4a Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Wed, 2 Oct 2024 22:05:00 -0600
Subject: [PATCH 02/40] Resolve some sphinx warnings.

---
 doc/source/conf.py                                            | 4 ++--
 doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst      | 4 ++--
 doc/source/users_guide/overview/quickstart.rst                | 2 +-
 .../users_guide/using-clm-tools/building-the-clm-tools.rst    | 1 +
 .../users_guide/using-clm-tools/what-are-the-clm-tools.rst    | 1 +
 5 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 23ef653bed..847f28cf34 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -78,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.
@@ -176,7 +176,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',
diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst
index 9ed8fe280e..4c15ebbf56 100644
--- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst
+++ b/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:
 
diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst
index 63f4afea6f..a7f41d4ae9 100644
--- a/doc/source/users_guide/overview/quickstart.rst
+++ b/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.
diff --git a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst
index c84d2a136d..b0d30d11c7 100644
--- a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst
+++ b/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.
diff --git a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst
index df7988451d..27c7c8efe4 100644
--- a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst
+++ b/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.

From 490d229c25bb91f30c44e950fa3b4f0951cbad04 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Wed, 2 Oct 2024 22:48:44 -0600
Subject: [PATCH 03/40] Fix MOSART conceptual figure references.

---
 .../CLM50_Tech_Note_Crop_Irrigation.rst                |  2 +-
 .../tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst  |  2 +-
 .../Introduction/CLM50_Tech_Note_Introduction.rst      |  2 +-
 doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst | 10 +++++-----
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst
index 2840d37176..ec43a50cd8 100755
--- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst
+++ b/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:
 
diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
index 130629f0eb..988be65dac 100644
--- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
+++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
@@ -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`).
diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst
index abf8898ef0..bb0ab9eef5 100644
--- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst
+++ b/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)`)
 
diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
index 3c10cd4507..674e4cc0b3 100644
--- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
+++ b/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.
 

From 4a9e1a25d1f8b3da684c9b5eccac4db3c9ef0be1 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Wed, 2 Oct 2024 22:49:50 -0600
Subject: [PATCH 04/40] Replace a reference to RTM with MOSART.

---
 doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
index 988be65dac..df7705be8b 100644
--- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
+++ b/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
 

From 497e9916ffe853bf79cb99d5e8c2591c161ffd36 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Wed, 2 Oct 2024 23:24:24 -0600
Subject: [PATCH 05/40] Resolve "WARNING: unsupported theme option 'versions'
 given"

Might break things?
---
 doc/source/conf.py | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 847f28cf34..d012ce888e 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -107,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,

From 3511baa639975b5957e4f896f0c009c548f92cca Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Wed, 2 Oct 2024 23:24:56 -0600
Subject: [PATCH 06/40] Add sphinx_mdinclude.

---
 doc/source/conf.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index d012ce888e..65c187c9a5 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -35,7 +35,9 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.githubpages']
+    'sphinx.ext.githubpages',
+    'sphinx_mdinclude',
+    ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

From dcb2f0f075194b63e7238d4752eed9cb62c4da46 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 12:58:55 -0600
Subject: [PATCH 07/40] Add ctsm-docs.yml.

---
 doc/ctsm-docs.yml | 63 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 doc/ctsm-docs.yml

diff --git a/doc/ctsm-docs.yml b/doc/ctsm-docs.yml
new file mode 100644
index 0000000000..2b7f8669fe
--- /dev/null
+++ b/doc/ctsm-docs.yml
@@ -0,0 +1,63 @@
+name: ctsm-docs
+channels:
+  - conda-forge
+dependencies:
+  - alabaster=0.7.16
+  - attrs=23.2.0
+  - babel=2.14.0
+  - brotli-python=1.1.0
+  - bzip2=1.0.8
+  - ca-certificates=2024.8.30
+  - cattrs=23.2.3
+  - certifi=2024.8.30
+  - charset-normalizer=3.3.2
+  - colorama=0.4.6
+  - docutils=0.20.1
+  - esbonio=0.16.4
+  - exceptiongroup=1.2.0
+  - idna=3.6
+  - imagesize=1.4.1
+  - importlib-metadata=7.0.1
+  - jinja2=3.1.3
+  - libcxx=16.0.6
+  - libexpat=2.5.0
+  - libffi=3.4.2
+  - libsqlite=3.45.1
+  - libzlib=1.2.13
+  - lsprotocol=2023.0.1
+  - markupsafe=2.1.5
+  - mistune=3.0.2
+  - ncurses=6.4
+  - openssl=3.3.2
+  - packaging=23.2
+  - pip=24.0
+  - platformdirs=4.2.0
+  - pygls=1.3.0
+  - pygments=2.17.2
+  - pysocks=1.7.1
+  - pyspellchecker=0.8.0
+  - python=3.12.2
+  - python_abi=3.12
+  - pytz=2024.1
+  - readline=8.2
+  - requests=2.31.0
+  - setuptools=69.1.1
+  - snowballstemmer=2.2.0
+  - sphinx=7.2.6
+  - sphinx-mdinclude=0.6.2
+  - sphinx_rtd_theme=2.0.0
+  - sphinxcontrib-applehelp=1.0.8
+  - sphinxcontrib-devhelp=1.0.6
+  - sphinxcontrib-htmlhelp=2.0.5
+  - sphinxcontrib-jquery=4.1
+  - sphinxcontrib-jsmath=1.0.1
+  - sphinxcontrib-qthelp=1.0.7
+  - sphinxcontrib-serializinghtml=1.1.10
+  - tk=8.6.13
+  - typing-extensions=4.10.0
+  - typing_extensions=4.10.0
+  - tzdata=2024a
+  - urllib3=2.2.1
+  - wheel=0.42.0
+  - xz=5.2.6
+  - zipp=3.17.0

From 94874d22bd9deab26cdacc727ba6b468a7f0f3b1 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 13:00:03 -0600
Subject: [PATCH 08/40] Replace ctsm-docs.yml with equivalent requirements.txt.

---
 doc/ctsm-docs.yml    | 63 --------------------------------------------
 doc/requirements.txt | 59 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 63 deletions(-)
 delete mode 100644 doc/ctsm-docs.yml
 create mode 100644 doc/requirements.txt

diff --git a/doc/ctsm-docs.yml b/doc/ctsm-docs.yml
deleted file mode 100644
index 2b7f8669fe..0000000000
--- a/doc/ctsm-docs.yml
+++ /dev/null
@@ -1,63 +0,0 @@
-name: ctsm-docs
-channels:
-  - conda-forge
-dependencies:
-  - alabaster=0.7.16
-  - attrs=23.2.0
-  - babel=2.14.0
-  - brotli-python=1.1.0
-  - bzip2=1.0.8
-  - ca-certificates=2024.8.30
-  - cattrs=23.2.3
-  - certifi=2024.8.30
-  - charset-normalizer=3.3.2
-  - colorama=0.4.6
-  - docutils=0.20.1
-  - esbonio=0.16.4
-  - exceptiongroup=1.2.0
-  - idna=3.6
-  - imagesize=1.4.1
-  - importlib-metadata=7.0.1
-  - jinja2=3.1.3
-  - libcxx=16.0.6
-  - libexpat=2.5.0
-  - libffi=3.4.2
-  - libsqlite=3.45.1
-  - libzlib=1.2.13
-  - lsprotocol=2023.0.1
-  - markupsafe=2.1.5
-  - mistune=3.0.2
-  - ncurses=6.4
-  - openssl=3.3.2
-  - packaging=23.2
-  - pip=24.0
-  - platformdirs=4.2.0
-  - pygls=1.3.0
-  - pygments=2.17.2
-  - pysocks=1.7.1
-  - pyspellchecker=0.8.0
-  - python=3.12.2
-  - python_abi=3.12
-  - pytz=2024.1
-  - readline=8.2
-  - requests=2.31.0
-  - setuptools=69.1.1
-  - snowballstemmer=2.2.0
-  - sphinx=7.2.6
-  - sphinx-mdinclude=0.6.2
-  - sphinx_rtd_theme=2.0.0
-  - sphinxcontrib-applehelp=1.0.8
-  - sphinxcontrib-devhelp=1.0.6
-  - sphinxcontrib-htmlhelp=2.0.5
-  - sphinxcontrib-jquery=4.1
-  - sphinxcontrib-jsmath=1.0.1
-  - sphinxcontrib-qthelp=1.0.7
-  - sphinxcontrib-serializinghtml=1.1.10
-  - tk=8.6.13
-  - typing-extensions=4.10.0
-  - typing_extensions=4.10.0
-  - tzdata=2024a
-  - urllib3=2.2.1
-  - wheel=0.42.0
-  - xz=5.2.6
-  - zipp=3.17.0
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000000..e377e6530d
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,59 @@
+alabaster == 0.7.16
+attrs == 23.2.0
+babel == 2.14.0
+brotli-python == 1.1.0
+bzip2 == 1.0.8
+ca-certificates == 2024.8.30
+cattrs == 23.2.3
+certifi == 2024.8.30
+charset-normalizer == 3.3.2
+colorama == 0.4.6
+docutils == 0.20.1
+esbonio == 0.16.4
+exceptiongroup == 1.2.0
+idna == 3.6
+imagesize == 1.4.1
+importlib-metadata == 7.0.1
+jinja2 == 3.1.3
+libcxx == 16.0.6
+libexpat == 2.5.0
+libffi == 3.4.2
+libsqlite == 3.45.1
+libzlib == 1.2.13
+lsprotocol == 2023.0.1
+markupsafe == 2.1.5
+mistune == 3.0.2
+ncurses == 6.4
+openssl == 3.3.2
+packaging == 23.2
+pip == 24.0
+platformdirs == 4.2.0
+pygls == 1.3.0
+pygments == 2.17.2
+pysocks == 1.7.1
+pyspellchecker == 0.8.0
+python == 3.12.2
+python_abi == 3.12
+pytz == 2024.1
+readline == 8.2
+requests == 2.31.0
+setuptools == 69.1.1
+snowballstemmer == 2.2.0
+sphinx == 7.2.6
+sphinx-mdinclude == 0.6.2
+sphinx_rtd_theme == 2.0.0
+sphinxcontrib-applehelp == 1.0.8
+sphinxcontrib-devhelp == 1.0.6
+sphinxcontrib-htmlhelp == 2.0.5
+sphinxcontrib-jquery == 4.1
+sphinxcontrib-jsmath == 1.0.1
+sphinxcontrib-qthelp == 1.0.7
+sphinxcontrib-serializinghtml == 1.1.10
+tk == 8.6.13
+typing-extensions == 4.10.0
+typing_extensions == 4.10.0
+tzdata == 2024a
+urllib3 == 2.2.1
+wheel == 0.42.0
+xz == 5.2.6
+zipp == 3.17.0

From 5f54b612584aa7388c278fefd3ac2588dda4b096 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 13:03:02 -0600
Subject: [PATCH 09/40] Copy CIME's docs.yml workflow to our repo.

---
 .github/workflows/docs.yml | 132 +++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 .github/workflows/docs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000000..f819a5ccc9
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,132 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'doc/**'
+
+  pull_request:
+    branches:
+      - master
+    paths:
+      - 'doc/**'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+jobs:
+  cleanup:
+    permissions:
+      contents: write  #  for git push
+    name: Cleanup branch previews
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: 'gh-pages'
+          fetch-depth: 0
+          lfs: true
+          path: gh-pages
+      - name: Remove branch previews
+        run: |
+          pushd $GITHUB_WORKSPACE/gh-pages
+
+          if [[ -e "$GITHUB_WORKSPACE/gh-pages/branch" ]]; then
+            ls -la "$GITHUB_WORKSPACE/gh-pages/branch"
+
+            for name in `ls branch/`
+            do
+              if [[ -z "$(git show-ref --quiet ${name})" ]]
+              then
+                git rm -rf branch/${name}
+
+                echo "Removed $GITHUB_WORKSPACE/gh-pages/branch/${name}"
+              fi
+            done
+
+            git config user.name github-actions[bot]
+            git config user.email github-actions[bot]@users.noreply.github.com
+            git commit -m "Clean up branch previews"
+            git push
+          fi
+
+          echo "Done cleaning branches"
+  build-and-deploy:
+    permissions:
+      contents: write  #  for peaceiris/actions-gh-pages to push
+      pull-requests: write  #  to comment on pull requests
+    needs: cleanup
+    if: ${{ always() }}
+    name: Build and deploy documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Install python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+      # https://github.com/actions/cache/blob/main/examples.md#python---pip
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -r doc/requirements.txt
+      # Build documentation under ${PWD}/_build
+      - name: Build Sphinx docs
+        run: |
+          make BUILDDIR=${PWD}/_build -C doc/ html
+      - name: Push PR preview
+        if: |
+          github.event_name == 'pull_request' &&
+          github.event.pull_request.head.repo.full_name == github.repository
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          publish_dir: './_build/html'
+          destination_dir: './branch/${{ github.event.pull_request.head.ref }}/html'
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+      - name: Comment about previewing documentation
+        if: |
+          github.event_name == 'pull_request' &&
+          github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+
+            const havePosted = comments.map(x => x.user.login).some(x => x === "github-actions[bot]");
+
+            if (!havePosted) {
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: 'You can preview documentation at https://esmci.github.io/cime/branch/${{ github.event.pull_request.head.ref }}/html/index.html'
+              })
+            }
+      - name: Push new docs
+        if: ${{ github.event_name == 'push' }}
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          publish_dir: './_build/html'
+          destination_dir: './versions/master/html'
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

From 18598eb6fd392e7b9ba723556776df7c38a108ef Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 13:07:50 -0600
Subject: [PATCH 10/40] Update docs.yml with our URL.

---
 .github/workflows/docs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index f819a5ccc9..d35cbe1c58 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -118,7 +118,7 @@ jobs:
                 issue_number: context.issue.number,
                 owner: context.repo.owner,
                 repo: context.repo.repo,
-                body: 'You can preview documentation at https://esmci.github.io/cime/branch/${{ github.event.pull_request.head.ref }}/html/index.html'
+                body: 'You can preview documentation at https://escomp.github.io/ctsm/branch/${{ github.event.pull_request.head.ref }}/html/index.html'
               })
             }
       - name: Push new docs

From e95c2914d1464af923c515c25e8e26717fc53fc8 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 13:22:14 -0600
Subject: [PATCH 11/40] Pare down doc/requirements.txt.

---
 doc/requirements.txt | 55 --------------------------------------------
 1 file changed, 55 deletions(-)

diff --git a/doc/requirements.txt b/doc/requirements.txt
index e377e6530d..f282ec48e4 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,59 +1,4 @@
-alabaster == 0.7.16
-attrs == 23.2.0
-babel == 2.14.0
-brotli-python == 1.1.0
-bzip2 == 1.0.8
-ca-certificates == 2024.8.30
-cattrs == 23.2.3
-certifi == 2024.8.30
-charset-normalizer == 3.3.2
-colorama == 0.4.6
-docutils == 0.20.1
 esbonio == 0.16.4
-exceptiongroup == 1.2.0
-idna == 3.6
-imagesize == 1.4.1
-importlib-metadata == 7.0.1
-jinja2 == 3.1.3
-libcxx == 16.0.6
-libexpat == 2.5.0
-libffi == 3.4.2
-libsqlite == 3.45.1
-libzlib == 1.2.13
-lsprotocol == 2023.0.1
-markupsafe == 2.1.5
-mistune == 3.0.2
-ncurses == 6.4
-openssl == 3.3.2
-packaging == 23.2
-pip == 24.0
-platformdirs == 4.2.0
-pygls == 1.3.0
-pygments == 2.17.2
-pysocks == 1.7.1
-pyspellchecker == 0.8.0
-python == 3.12.2
-python_abi == 3.12
-pytz == 2024.1
-readline == 8.2
-requests == 2.31.0
-setuptools == 69.1.1
-snowballstemmer == 2.2.0
 sphinx == 7.2.6
 sphinx-mdinclude == 0.6.2
 sphinx_rtd_theme == 2.0.0
-sphinxcontrib-applehelp == 1.0.8
-sphinxcontrib-devhelp == 1.0.6
-sphinxcontrib-htmlhelp == 2.0.5
-sphinxcontrib-jquery == 4.1
-sphinxcontrib-jsmath == 1.0.1
-sphinxcontrib-qthelp == 1.0.7
-sphinxcontrib-serializinghtml == 1.1.10
-tk == 8.6.13
-typing-extensions == 4.10.0
-typing_extensions == 4.10.0
-tzdata == 2024a
-urllib3 == 2.2.1
-wheel == 0.42.0
-xz == 5.2.6
-zipp == 3.17.0

From c3788bb5b50c2b84116d93465c7d9c2144df4d6c Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 13:34:00 -0600
Subject: [PATCH 12/40] Have PR preview actions run even on branches from forks

---
 .github/workflows/docs.yml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index d35cbe1c58..8da5524ae7 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -89,8 +89,7 @@ jobs:
           make BUILDDIR=${PWD}/_build -C doc/ html
       - name: Push PR preview
         if: |
-          github.event_name == 'pull_request' &&
-          github.event.pull_request.head.repo.full_name == github.repository
+          github.event_name == 'pull_request'
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{secrets.GITHUB_TOKEN}}
@@ -100,8 +99,7 @@ jobs:
           user_email: 'github-actions[bot]@users.noreply.github.com'
       - name: Comment about previewing documentation
         if: |
-          github.event_name == 'pull_request' &&
-          github.event.pull_request.head.repo.full_name == github.repository
+          github.event_name == 'pull_request'
         uses: actions/github-script@v6
         with:
           script: |

From 674ab46804c2ed8f7841c8e35ea1250f1b84482f Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 13:56:28 -0600
Subject: [PATCH 13/40] Add pages:write perms to build-and-deploy action.

---
 .github/workflows/docs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 8da5524ae7..2724557f6f 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -59,6 +59,7 @@ jobs:
     permissions:
       contents: write  #  for peaceiris/actions-gh-pages to push
       pull-requests: write  #  to comment on pull requests
+      pages: write
     needs: cleanup
     if: ${{ always() }}
     name: Build and deploy documentation

From a5063f6ff42ab99bac28187777f9ec195b51a084 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 14:04:35 -0600
Subject: [PATCH 14/40] Update peaceiris/actions-gh-pages from v3 to v4.

---
 .github/workflows/docs.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 2724557f6f..534ea5bd7c 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -91,7 +91,7 @@ jobs:
       - name: Push PR preview
         if: |
           github.event_name == 'pull_request'
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{secrets.GITHUB_TOKEN}}
           publish_dir: './_build/html'
@@ -122,7 +122,7 @@ jobs:
             }
       - name: Push new docs
         if: ${{ github.event_name == 'push' }}
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{secrets.GITHUB_TOKEN}}
           publish_dir: './_build/html'

From a5f4573a22089e721d0040ceb76f0cd6f7c99265 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 14:24:44 -0600
Subject: [PATCH 15/40] Set gibberish publish_branch.

---
 .github/workflows/docs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 534ea5bd7c..1d6608f50a 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -94,6 +94,7 @@ jobs:
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{secrets.GITHUB_TOKEN}}
+          publish_branch: gh-pages-sidnfueriu
           publish_dir: './_build/html'
           destination_dir: './branch/${{ github.event.pull_request.head.ref }}/html'
           user_name: 'github-actions[bot]'

From 442f13d3b9d30b80cf11aa51546fe11a8938d8e9 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 14:45:55 -0600
Subject: [PATCH 16/40] Set external_repository to hopefully publish to user's
 fork.

---
 .github/workflows/docs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 1d6608f50a..afb86a91f5 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -94,6 +94,7 @@ jobs:
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{secrets.GITHUB_TOKEN}}
+          external_repository: ${{github.triggering_actor}}/ctsm
           publish_branch: gh-pages-sidnfueriu
           publish_dir: './_build/html'
           destination_dir: './branch/${{ github.event.pull_request.head.ref }}/html'

From 76c32381a9519059ffe2807eccfcde1d4a5f84a9 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 14:57:28 -0600
Subject: [PATCH 17/40] Remove pages preview/push stuff; only check docs build.

---
 .github/workflows/docs.yml | 47 ++------------------------------------
 1 file changed, 2 insertions(+), 45 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index afb86a91f5..0cfc000b45 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -55,14 +55,14 @@ jobs:
           fi
 
           echo "Done cleaning branches"
-  build-and-deploy:
+  test-build:
     permissions:
       contents: write  #  for peaceiris/actions-gh-pages to push
       pull-requests: write  #  to comment on pull requests
       pages: write
     needs: cleanup
     if: ${{ always() }}
-    name: Build and deploy documentation
+    name: Test building documentation
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -88,46 +88,3 @@ jobs:
       - name: Build Sphinx docs
         run: |
           make BUILDDIR=${PWD}/_build -C doc/ html
-      - name: Push PR preview
-        if: |
-          github.event_name == 'pull_request'
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{secrets.GITHUB_TOKEN}}
-          external_repository: ${{github.triggering_actor}}/ctsm
-          publish_branch: gh-pages-sidnfueriu
-          publish_dir: './_build/html'
-          destination_dir: './branch/${{ github.event.pull_request.head.ref }}/html'
-          user_name: 'github-actions[bot]'
-          user_email: 'github-actions[bot]@users.noreply.github.com'
-      - name: Comment about previewing documentation
-        if: |
-          github.event_name == 'pull_request'
-        uses: actions/github-script@v6
-        with:
-          script: |
-            const comments = await github.paginate(github.rest.issues.listComments, {
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number
-            });
-
-            const havePosted = comments.map(x => x.user.login).some(x => x === "github-actions[bot]");
-
-            if (!havePosted) {
-              await github.rest.issues.createComment({
-                issue_number: context.issue.number,
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                body: 'You can preview documentation at https://escomp.github.io/ctsm/branch/${{ github.event.pull_request.head.ref }}/html/index.html'
-              })
-            }
-      - name: Push new docs
-        if: ${{ github.event_name == 'push' }}
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{secrets.GITHUB_TOKEN}}
-          publish_dir: './_build/html'
-          destination_dir: './versions/master/html'
-          user_name: 'github-actions[bot]'
-          user_email: 'github-actions[bot]@users.noreply.github.com'

From 03857fffdc89fc659bcc41fc796897703f5520ca Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 14:59:13 -0600
Subject: [PATCH 18/40] Remove write perms for test-build action.

---
 .github/workflows/docs.yml | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 0cfc000b45..ee1b77351c 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -56,10 +56,6 @@ jobs:
 
           echo "Done cleaning branches"
   test-build:
-    permissions:
-      contents: write  #  for peaceiris/actions-gh-pages to push
-      pull-requests: write  #  to comment on pull requests
-      pages: write
     needs: cleanup
     if: ${{ always() }}
     name: Test building documentation

From dccbcddb0061a2bf3bec7a4c3e647573e4eb64b7 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 15:01:44 -0600
Subject: [PATCH 19/40] Delete cleanup job.

---
 .github/workflows/docs.yml | 38 --------------------------------------
 1 file changed, 38 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ee1b77351c..523641c5be 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -18,45 +18,7 @@ on:
 permissions:
   contents: read
 jobs:
-  cleanup:
-    permissions:
-      contents: write  #  for git push
-    name: Cleanup branch previews
-    runs-on: ubuntu-latest
-    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          ref: 'gh-pages'
-          fetch-depth: 0
-          lfs: true
-          path: gh-pages
-      - name: Remove branch previews
-        run: |
-          pushd $GITHUB_WORKSPACE/gh-pages
-
-          if [[ -e "$GITHUB_WORKSPACE/gh-pages/branch" ]]; then
-            ls -la "$GITHUB_WORKSPACE/gh-pages/branch"
-
-            for name in `ls branch/`
-            do
-              if [[ -z "$(git show-ref --quiet ${name})" ]]
-              then
-                git rm -rf branch/${name}
-
-                echo "Removed $GITHUB_WORKSPACE/gh-pages/branch/${name}"
-              fi
-            done
-
-            git config user.name github-actions[bot]
-            git config user.email github-actions[bot]@users.noreply.github.com
-            git commit -m "Clean up branch previews"
-            git push
-          fi
-
-          echo "Done cleaning branches"
   test-build:
-    needs: cleanup
     if: ${{ always() }}
     name: Test building documentation
     runs-on: ubuntu-latest

From 868e0d06f15f58419f001add4425534edef594fd Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 15:19:58 -0600
Subject: [PATCH 20/40] If PR branch is from ESCOMP/CTSM (not fork), run
 build-and-deploy.

---
 .github/workflows/docs.yml | 119 +++++++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 523641c5be..323b06d3ec 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -18,6 +18,9 @@ on:
 permissions:
   contents: read
 jobs:
+
+  # The test-build job will run regardless of whether the PR branch is from ESCOMP/CTSM or a fork.
+
   test-build:
     if: ${{ always() }}
     name: Test building documentation
@@ -46,3 +49,119 @@ jobs:
       - name: Build Sphinx docs
         run: |
           make BUILDDIR=${PWD}/_build -C doc/ html
+
+# The following jobs will only run if the PR branch is in ESCOMP/CTSM, not a fork.
+
+  cleanup:
+    permissions:
+      contents: write  #  for git push
+    name: Cleanup branch previews
+    runs-on: ubuntu-latest
+    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: 'gh-pages'
+          fetch-depth: 0
+          lfs: true
+          path: gh-pages
+      - name: Remove branch previews
+        run: |
+          pushd $GITHUB_WORKSPACE/gh-pages
+
+          if [[ -e "$GITHUB_WORKSPACE/gh-pages/branch" ]]; then
+            ls -la "$GITHUB_WORKSPACE/gh-pages/branch"
+
+            for name in `ls branch/`
+            do
+              if [[ -z "$(git show-ref --quiet ${name})" ]]
+              then
+                git rm -rf branch/${name}
+
+                echo "Removed $GITHUB_WORKSPACE/gh-pages/branch/${name}"
+              fi
+            done
+
+            git config user.name github-actions[bot]
+            git config user.email github-actions[bot]@users.noreply.github.com
+            git commit -m "Clean up branch previews"
+            git push
+          fi
+
+          echo "Done cleaning branches"
+  build-and-deploy:
+    permissions:
+      contents: write  #  for peaceiris/actions-gh-pages to push
+      pull-requests: write  #  to comment on pull requests
+    needs: cleanup
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    name: Build and deploy documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Install python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+      # https://github.com/actions/cache/blob/main/examples.md#python---pip
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -r doc/requirements.txt
+      # Build documentation under ${PWD}/_build
+      - name: Build Sphinx docs
+        run: |
+          make BUILDDIR=${PWD}/_build -C doc/ html
+      - name: Push PR preview
+        if: |
+          github.event_name == 'pull_request' &&
+          github.event.pull_request.head.repo.full_name == github.repository
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          publish_dir: './_build/html'
+          destination_dir: './branch/${{ github.event.pull_request.head.ref }}/html'
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+      - name: Comment about previewing documentation
+        if: |
+          github.event_name == 'pull_request' &&
+          github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+
+            const havePosted = comments.map(x => x.user.login).some(x => x === "github-actions[bot]");
+
+            if (!havePosted) {
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: 'You can preview documentation at https://escomp.github.io/ctsm/branch/${{ github.event.pull_request.head.ref }}/html/index.html'
+              })
+            }
+      - name: Push new docs
+        if: ${{ github.event_name == 'push' }}
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          publish_dir: './_build/html'
+          destination_dir: './versions/master/html'
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+

From 1fa1eb521172b73e09114c415b039705bc823e0d Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 15:28:10 -0600
Subject: [PATCH 21/40] Only do test-build if the PR branch is from a fork, not
 ESCOMP/CTSM.

---
 .github/workflows/docs.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 323b06d3ec..a577039083 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -19,10 +19,10 @@ permissions:
   contents: read
 jobs:
 
-  # The test-build job will run regardless of whether the PR branch is from ESCOMP/CTSM or a fork.
+  # The test-build job will run only if the PR branch is from a fork, not ESCOMP/CTSM.
 
   test-build:
-    if: ${{ always() }}
+    if: github.event.pull_request.head.repo.full_name != github.repository
     name: Test building documentation
     runs-on: ubuntu-latest
     steps:

From 9d5a455ffe5434a93e3accdb15e89f1a8cd61f3d Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 17:00:50 -0600
Subject: [PATCH 22/40] build_docs will now fail if sphinx warnings are
 generated.

Via updating doc-builder external to c51795f; branch update-20241002: Merge branch 'warnings-as-errors' into update-20241002
---
 .gitmodules     | 2 +-
 doc/doc-builder | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.gitmodules b/.gitmodules
index d60b9bf157..cd462315c3 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -124,7 +124,7 @@ fxDONOTUSEurl = https://github.com/NCAR/ParallelIO
 [submodule "doc-builder"]
 path = doc/doc-builder
 url = https://github.com/samsrabin/doc-builder
-fxtag = 30d2d6d48549f68ee300a469af5dfe5ac3eeae81
+fxtag = c51795f65d230803418c932bfd8639c85c33a19a
 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
diff --git a/doc/doc-builder b/doc/doc-builder
index 30d2d6d485..c51795f65d 160000
--- a/doc/doc-builder
+++ b/doc/doc-builder
@@ -1 +1 @@
-Subproject commit 30d2d6d48549f68ee300a469af5dfe5ac3eeae81
+Subproject commit c51795f65d230803418c932bfd8639c85c33a19a

From ee947537142984f0fe2bc7a12e95bad105dde8de Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 17:15:03 -0600
Subject: [PATCH 23/40] TEST: Introduce Sphinx errors. Github workflow should
 fail.

---
 doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 2 +-
 doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
index df7705be8b..3048bf0da7 100644
--- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
+++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
@@ -1,4 +1,4 @@
-.. _rst_Hydrology:
+.. _rst_Hydrolowerwegy:
 
 Hydrology
 ============
diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
index 674e4cc0b3..5a2f8d7490 100644
--- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
+++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
@@ -1,4 +1,4 @@
-.. _rst_MOSART:
+.. _rst_MOwererSART:
 
 Model for Scale Adaptive River Transport (MOSART)
 ====================================================

From a893eb5287a19b6f13ca85d9af5c3462245e5419 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:16:22 -0600
Subject: [PATCH 24/40] docs.yml now fails when sphinx has warnings.

---
 .github/workflows/docs.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index a577039083..f550bd70b0 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -48,7 +48,7 @@ jobs:
       # Build documentation under ${PWD}/_build
       - name: Build Sphinx docs
         run: |
-          make BUILDDIR=${PWD}/_build -C doc/ html
+          make SPHINXOPTS=-W --keep-going BUILDDIR=${PWD}/_build -C doc/ html
 
 # The following jobs will only run if the PR branch is in ESCOMP/CTSM, not a fork.
 
@@ -120,7 +120,7 @@ jobs:
       # Build documentation under ${PWD}/_build
       - name: Build Sphinx docs
         run: |
-          make BUILDDIR=${PWD}/_build -C doc/ html
+          make SPHINXOPTS=-W --keep-going BUILDDIR=${PWD}/_build -C doc/ html
       - name: Push PR preview
         if: |
           github.event_name == 'pull_request' &&

From dc8dd92c17cdf5c80c689992b2e46ece7318a825 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:19:50 -0600
Subject: [PATCH 25/40] Revert "Only do test-build if the PR branch is from a
 fork, not ESCOMP/CTSM."

This reverts commit 1fa1eb521172b73e09114c415b039705bc823e0d.
---
 .github/workflows/docs.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index f550bd70b0..412dde9314 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -19,10 +19,10 @@ permissions:
   contents: read
 jobs:
 
-  # The test-build job will run only if the PR branch is from a fork, not ESCOMP/CTSM.
+  # The test-build job will run regardless of whether the PR branch is from ESCOMP/CTSM or a fork.
 
   test-build:
-    if: github.event.pull_request.head.repo.full_name != github.repository
+    if: ${{ always() }}
     name: Test building documentation
     runs-on: ubuntu-latest
     steps:

From adb99fc6a2de2c0a780cf9839f1d169e8e1ad3bd Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:22:32 -0600
Subject: [PATCH 26/40] Add docs.yml job to test doc-builder.

---
 .github/workflows/docs.yml | 37 +++++++++++++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 412dde9314..90d8a22501 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -19,11 +19,11 @@ permissions:
   contents: read
 jobs:
 
-  # The test-build job will run regardless of whether the PR branch is from ESCOMP/CTSM or a fork.
+  # These first jobs will run regardless of whether the PR branch is from ESCOMP/CTSM or a fork.
 
-  test-build:
+  test-build-makefile:
     if: ${{ always() }}
-    name: Test building documentation
+    name: Test building documentation with makefile
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -46,10 +46,39 @@ jobs:
         run: |
           pip install -r doc/requirements.txt
       # Build documentation under ${PWD}/_build
-      - name: Build Sphinx docs
+      - name: Build Sphinx docs with makefile
         run: |
           make SPHINXOPTS=-W --keep-going BUILDDIR=${PWD}/_build -C doc/ html
 
+  test-doc-builder:
+    if: ${{ always() }}
+    name: Test building documentation with doc-builder
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Install python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+      # https://github.com/actions/cache/blob/main/examples.md#python---pip
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -r doc/requirements.txt
+      # Build documentation under ${PWD}/_build
+      - name: Build Sphinx docs with doc-builder
+        run: |
+          ./build_docs -b ${PWD}/_build -c
+
 # The following jobs will only run if the PR branch is in ESCOMP/CTSM, not a fork.
 
   cleanup:

From da0a8bd178990c5cde5860ccbffa5d9d44e59180 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:28:02 -0600
Subject: [PATCH 27/40] Fix SPHINXOPTS in test-build-makefile.

---
 .github/workflows/docs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 90d8a22501..2154f2b99e 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -48,7 +48,7 @@ jobs:
       # Build documentation under ${PWD}/_build
       - name: Build Sphinx docs with makefile
         run: |
-          make SPHINXOPTS=-W --keep-going BUILDDIR=${PWD}/_build -C doc/ html
+          make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build -C doc/ html
 
   test-doc-builder:
     if: ${{ always() }}

From 3575ea4df97eb825f95a89ad9fb7d778184e4fac Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:28:39 -0600
Subject: [PATCH 28/40] Fix working dir of test-doc-builder.

---
 .github/workflows/docs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 2154f2b99e..95e7966e09 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -77,7 +77,7 @@ jobs:
       # Build documentation under ${PWD}/_build
       - name: Build Sphinx docs with doc-builder
         run: |
-          ./build_docs -b ${PWD}/_build -c
+          cd doc && ./build_docs -b ${PWD}/_build -c
 
 # The following jobs will only run if the PR branch is in ESCOMP/CTSM, not a fork.
 

From 6fb71bc4a2002a484079a61cbbb6605f2547c3be Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:29:33 -0600
Subject: [PATCH 29/40] Revert "TEST: Introduce Sphinx errors. Github workflow
 should fail."

This reverts commit ee947537142984f0fe2bc7a12e95bad105dde8de.
---
 doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 2 +-
 doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
index 3048bf0da7..df7705be8b 100644
--- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
+++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
@@ -1,4 +1,4 @@
-.. _rst_Hydrolowerwegy:
+.. _rst_Hydrology:
 
 Hydrology
 ============
diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
index 5a2f8d7490..674e4cc0b3 100644
--- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
+++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
@@ -1,4 +1,4 @@
-.. _rst_MOwererSART:
+.. _rst_MOSART:
 
 Model for Scale Adaptive River Transport (MOSART)
 ====================================================

From 8bbdf9417d327f8699e395f62460a7b4ebfb4bf6 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 17:15:03 -0600
Subject: [PATCH 30/40] TEST: Introduce Sphinx errors. Github workflow should
 fail.

---
 doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 2 +-
 doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
index df7705be8b..3048bf0da7 100644
--- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
+++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
@@ -1,4 +1,4 @@
-.. _rst_Hydrology:
+.. _rst_Hydrolowerwegy:
 
 Hydrology
 ============
diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
index 674e4cc0b3..5a2f8d7490 100644
--- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
+++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
@@ -1,4 +1,4 @@
-.. _rst_MOSART:
+.. _rst_MOwererSART:
 
 Model for Scale Adaptive River Transport (MOSART)
 ====================================================

From eb748741da180c529e398a9e0ca85a8de990c7fd Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:35:20 -0600
Subject: [PATCH 31/40] Revert "TEST: Introduce Sphinx errors. Github workflow
 should fail."

This reverts commit 8bbdf9417d327f8699e395f62460a7b4ebfb4bf6.
---
 doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 2 +-
 doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
index 3048bf0da7..df7705be8b 100644
--- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
+++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst
@@ -1,4 +1,4 @@
-.. _rst_Hydrolowerwegy:
+.. _rst_Hydrology:
 
 Hydrology
 ============
diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
index 5a2f8d7490..674e4cc0b3 100644
--- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
+++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
@@ -1,4 +1,4 @@
-.. _rst_MOwererSART:
+.. _rst_MOSART:
 
 Model for Scale Adaptive River Transport (MOSART)
 ====================================================

From 6a3049e856ba6017810cdbe504a1ec1996c72764 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:49:24 -0600
Subject: [PATCH 32/40] Disable "Push new docs."

---
 .github/workflows/docs.yml | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 95e7966e09..f45481f68b 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -184,13 +184,13 @@ jobs:
                 body: 'You can preview documentation at https://escomp.github.io/ctsm/branch/${{ github.event.pull_request.head.ref }}/html/index.html'
               })
             }
-      - name: Push new docs
-        if: ${{ github.event_name == 'push' }}
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{secrets.GITHUB_TOKEN}}
-          publish_dir: './_build/html'
-          destination_dir: './versions/master/html'
-          user_name: 'github-actions[bot]'
-          user_email: 'github-actions[bot]@users.noreply.github.com'
+    #   - name: Push new docs
+    #     if: ${{ github.event_name == 'push' }}
+    #     uses: peaceiris/actions-gh-pages@v3
+    #     with:
+    #       github_token: ${{secrets.GITHUB_TOKEN}}
+    #       publish_dir: './_build/html'
+    #       destination_dir: './versions/master/html'
+    #       user_name: 'github-actions[bot]'
+    #       user_email: 'github-actions[bot]@users.noreply.github.com'
 

From 259ad13168f795e1736663d903b6489a6ee9668c Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:53:45 -0600
Subject: [PATCH 33/40] Disable "needs: cleanup" for build-and-deploy.

---
 .github/workflows/docs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index f45481f68b..496b0fd48d 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -122,7 +122,7 @@ jobs:
     permissions:
       contents: write  #  for peaceiris/actions-gh-pages to push
       pull-requests: write  #  to comment on pull requests
-    needs: cleanup
+    # needs: cleanup
     if: github.event.pull_request.head.repo.full_name == github.repository
     name: Build and deploy documentation
     runs-on: ubuntu-latest

From afd87b6a06d1d4b60bd07a1d3edf80c22bdb963c Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Thu, 3 Oct 2024 18:59:40 -0600
Subject: [PATCH 34/40] Publish preview to gh-pages-preview instead of
 gh-pages.

---
 .github/workflows/docs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 496b0fd48d..dadf9e34a7 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -157,6 +157,7 @@ jobs:
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{secrets.GITHUB_TOKEN}}
+          publish_branch: gh-pages-preview
           publish_dir: './_build/html'
           destination_dir: './branch/${{ github.event.pull_request.head.ref }}/html'
           user_name: 'github-actions[bot]'

From 71c4386142f0fde59f68df1a0cd5ff2d7700a78f Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Mon, 7 Oct 2024 16:03:34 -0600
Subject: [PATCH 35/40] Delete docs cleanup and build-and-deploy jobs.

---
 .github/workflows/docs.yml | 119 -------------------------------------
 1 file changed, 119 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index dadf9e34a7..e78748f25b 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -19,8 +19,6 @@ permissions:
   contents: read
 jobs:
 
-  # These first jobs will run regardless of whether the PR branch is from ESCOMP/CTSM or a fork.
-
   test-build-makefile:
     if: ${{ always() }}
     name: Test building documentation with makefile
@@ -78,120 +76,3 @@ jobs:
       - name: Build Sphinx docs with doc-builder
         run: |
           cd doc && ./build_docs -b ${PWD}/_build -c
-
-# The following jobs will only run if the PR branch is in ESCOMP/CTSM, not a fork.
-
-  cleanup:
-    permissions:
-      contents: write  #  for git push
-    name: Cleanup branch previews
-    runs-on: ubuntu-latest
-    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.event.pull_request.head.repo.full_name == github.repository
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          ref: 'gh-pages'
-          fetch-depth: 0
-          lfs: true
-          path: gh-pages
-      - name: Remove branch previews
-        run: |
-          pushd $GITHUB_WORKSPACE/gh-pages
-
-          if [[ -e "$GITHUB_WORKSPACE/gh-pages/branch" ]]; then
-            ls -la "$GITHUB_WORKSPACE/gh-pages/branch"
-
-            for name in `ls branch/`
-            do
-              if [[ -z "$(git show-ref --quiet ${name})" ]]
-              then
-                git rm -rf branch/${name}
-
-                echo "Removed $GITHUB_WORKSPACE/gh-pages/branch/${name}"
-              fi
-            done
-
-            git config user.name github-actions[bot]
-            git config user.email github-actions[bot]@users.noreply.github.com
-            git commit -m "Clean up branch previews"
-            git push
-          fi
-
-          echo "Done cleaning branches"
-  build-and-deploy:
-    permissions:
-      contents: write  #  for peaceiris/actions-gh-pages to push
-      pull-requests: write  #  to comment on pull requests
-    # needs: cleanup
-    if: github.event.pull_request.head.repo.full_name == github.repository
-    name: Build and deploy documentation
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-          lfs: true
-      - name: Install python 3.x
-        uses: actions/setup-python@v2
-        with:
-          python-version: '3.x'
-      # https://github.com/actions/cache/blob/main/examples.md#python---pip
-      - name: Cache pip
-        uses: actions/cache@v3
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
-      - name: Install dependencies
-        run: |
-          pip install -r doc/requirements.txt
-      # Build documentation under ${PWD}/_build
-      - name: Build Sphinx docs
-        run: |
-          make SPHINXOPTS=-W --keep-going BUILDDIR=${PWD}/_build -C doc/ html
-      - name: Push PR preview
-        if: |
-          github.event_name == 'pull_request' &&
-          github.event.pull_request.head.repo.full_name == github.repository
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{secrets.GITHUB_TOKEN}}
-          publish_branch: gh-pages-preview
-          publish_dir: './_build/html'
-          destination_dir: './branch/${{ github.event.pull_request.head.ref }}/html'
-          user_name: 'github-actions[bot]'
-          user_email: 'github-actions[bot]@users.noreply.github.com'
-      - name: Comment about previewing documentation
-        if: |
-          github.event_name == 'pull_request' &&
-          github.event.pull_request.head.repo.full_name == github.repository
-        uses: actions/github-script@v6
-        with:
-          script: |
-            const comments = await github.paginate(github.rest.issues.listComments, {
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number
-            });
-
-            const havePosted = comments.map(x => x.user.login).some(x => x === "github-actions[bot]");
-
-            if (!havePosted) {
-              await github.rest.issues.createComment({
-                issue_number: context.issue.number,
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                body: 'You can preview documentation at https://escomp.github.io/ctsm/branch/${{ github.event.pull_request.head.ref }}/html/index.html'
-              })
-            }
-    #   - name: Push new docs
-    #     if: ${{ github.event_name == 'push' }}
-    #     uses: peaceiris/actions-gh-pages@v3
-    #     with:
-    #       github_token: ${{secrets.GITHUB_TOKEN}}
-    #       publish_dir: './_build/html'
-    #       destination_dir: './versions/master/html'
-    #       user_name: 'github-actions[bot]'
-    #       user_email: 'github-actions[bot]@users.noreply.github.com'
-

From 76e2c6eb6548083192a9dc8adbe7c88b70478b16 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Mon, 7 Oct 2024 16:03:53 -0600
Subject: [PATCH 36/40] Docs workflow should run on PRs going to b4b-dev too.

---
 .github/workflows/docs.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index e78748f25b..a2dca612c2 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -4,12 +4,14 @@ on:
   push:
     branches:
       - master
+      - b4b-dev
     paths:
       - 'doc/**'
 
   pull_request:
     branches:
       - master
+      - b4b-dev
     paths:
       - 'doc/**'
 

From 2d60500d6811b74aaec16c5ea4efda38e0bbfb49 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Mon, 7 Oct 2024 16:05:20 -0600
Subject: [PATCH 37/40] Remove action version specifiers from docs workflow.

---
 .github/workflows/docs.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index a2dca612c2..b0bc266c0b 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -26,17 +26,17 @@ jobs:
     name: Test building documentation with makefile
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout
         with:
           fetch-depth: 0
           lfs: true
       - name: Install python 3.x
-        uses: actions/setup-python@v2
+        uses: actions/setup-python
         with:
           python-version: '3.x'
       # https://github.com/actions/cache/blob/main/examples.md#python---pip
       - name: Cache pip
-        uses: actions/cache@v3
+        uses: actions/cache
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
@@ -55,17 +55,17 @@ jobs:
     name: Test building documentation with doc-builder
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout
         with:
           fetch-depth: 0
           lfs: true
       - name: Install python 3.x
-        uses: actions/setup-python@v2
+        uses: actions/setup-python
         with:
           python-version: '3.x'
       # https://github.com/actions/cache/blob/main/examples.md#python---pip
       - name: Cache pip
-        uses: actions/cache@v3
+        uses: actions/cache
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}

From b7c888e763bfd9e6160a60a4cfd0e6320a99a19c Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Mon, 7 Oct 2024 16:08:15 -0600
Subject: [PATCH 38/40] Remove branches specifiers from docs workflow.

---
 .github/workflows/docs.yml | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index b0bc266c0b..9b8621e765 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -2,16 +2,10 @@ name: docs
 
 on:
   push:
-    branches:
-      - master
-      - b4b-dev
     paths:
       - 'doc/**'
 
   pull_request:
-    branches:
-      - master
-      - b4b-dev
     paths:
       - 'doc/**'
 

From 0752bec7dc3722f706e15b1c5401a385b67382d9 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Mon, 7 Oct 2024 16:51:12 -0600
Subject: [PATCH 39/40] Revert "Remove action version specifiers from docs
 workflow."

This reverts commit 2d60500d6811b74aaec16c5ea4efda38e0bbfb49.
---
 .github/workflows/docs.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 9b8621e765..f8d7b49624 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -20,17 +20,17 @@ jobs:
     name: Test building documentation with makefile
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout
+      - uses: actions/checkout@v3
         with:
           fetch-depth: 0
           lfs: true
       - name: Install python 3.x
-        uses: actions/setup-python
+        uses: actions/setup-python@v2
         with:
           python-version: '3.x'
       # https://github.com/actions/cache/blob/main/examples.md#python---pip
       - name: Cache pip
-        uses: actions/cache
+        uses: actions/cache@v3
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
@@ -49,17 +49,17 @@ jobs:
     name: Test building documentation with doc-builder
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout
+      - uses: actions/checkout@v3
         with:
           fetch-depth: 0
           lfs: true
       - name: Install python 3.x
-        uses: actions/setup-python
+        uses: actions/setup-python@v2
         with:
           python-version: '3.x'
       # https://github.com/actions/cache/blob/main/examples.md#python---pip
       - name: Cache pip
-        uses: actions/cache
+        uses: actions/cache@v3
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}

From 5fed746116b9c6a6c10741d7809efe3b6d9f3c51 Mon Sep 17 00:00:00 2001
From: Sam Rabin <samrabin@ucar.edu>
Date: Mon, 7 Oct 2024 16:56:37 -0600
Subject: [PATCH 40/40] Revert doc-builder to canonical v1.0.8.

---
 .gitmodules     | 4 ++--
 doc/doc-builder | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.gitmodules b/.gitmodules
index cd462315c3..7274b9acd2 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -123,8 +123,8 @@ fxDONOTUSEurl = https://github.com/NCAR/ParallelIO
 
 [submodule "doc-builder"]
 path = doc/doc-builder
-url = https://github.com/samsrabin/doc-builder
-fxtag = c51795f65d230803418c932bfd8639c85c33a19a
+url = https://github.com/ESMCI/doc-builder
+fxtag = v1.0.8
 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
diff --git a/doc/doc-builder b/doc/doc-builder
index c51795f65d..ab9bc93dd0 160000
--- a/doc/doc-builder
+++ b/doc/doc-builder
@@ -1 +1 @@
-Subproject commit c51795f65d230803418c932bfd8639c85c33a19a
+Subproject commit ab9bc93dd09d0173f8097c7a18c7d061c1cd3b79