Update docs builder 2

.git-blame-ignore-revs

@@ -51,3 +51,4 @@ aa04d1f7d86cc2503b98b7e2b2d84dbfff6c316b
 1a49e547ba3c48fa483f9ae81a8f05adcd6b888c
 045d90f1d80f713eb3ae0ac58f6c2352937f1eb0
 753fda3ff0147837231a73c9c728dd9ce47b5997
+f112ba0bbf96a61d5a4d354dc0dcbd8b0c68145c

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+name: docs
+
+on:
+  push:
+    paths:
+      - 'doc/**'
+
+  pull_request:
+    paths:
+      - 'doc/**'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+jobs:
+
+  test-build-makefile:
+    if: ${{ always() }}
+    name: Test building documentation with makefile
+    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 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: |
+          cd doc && ./build_docs -b ${PWD}/_build -c

bld/CLMBuildNamelist.pm

@@ -2756,6 +2756,13 @@ SIMYR:    foreach my $sim_yr ( @sim_years ) {
         $log->fatal_error("$useinitvar is being set for you but a $var was not found, so $useinitvar, init_interp_attributes, and finidat must not be set correctly for this configuration in the namelist_default file" );
      }
   }
+
+  # this check has to be here and not earlier since use_init_interp is set here and hillslope is already set above in setup_logic_hillslope
+  if ( &value_is_true($nl->get_value($useinitvar)) && value_is_true($nl->get_value("use_hillslope")) ) {
+     $log->warning("WARNING: You have set use_hillslope while $useinitvar is TRUE.\n This means all hillslope columns in a gridcell will read identical values" .
+                   " from initial conditions. If you are sure you want this behaviour:")
+  }
+
 } # end initial conditions
 
 #-------------------------------------------------------------------------------

bld/unit_testers/build-namelist_test.pl

@@ -163,7 +163,7 @@ sub cat_and_create_namelistinfile {
 #
 # Figure out number of tests that will run
 #
-my $ntests = 3994;
+my $ntests = 3997;
 
 if ( defined($opts{'compare'}) ) {
    $ntests += 2437;
@@ -1359,6 +1359,10 @@ sub cat_and_create_namelistinfile {
                                      namelst=>"fsurdat='build-namelist_test.pl'",
                                      phys=>"clm6_0",
                                    },
+     "hillslope with init_interp"=>{ options=>"-bgc bgc -envxml_dir .",
+                                     namelst=>"use_init_interp=.true.,use_hillslope=.true.",
+                                     phys=>"clm6_0",
+                                   },
                );
 foreach my $key ( keys(%warntest) ) {
    print( "$key\n" );

cime_config/testdefs/ExpectedTestFails.xml

@@ -37,6 +37,50 @@
   </test>
 
   <!-- aux_clm test suite failures -->
+  <test name="SMS_Ld2_D_PS.f09_g17.I1850Clm50BgcCropCmip6.derecho_intel.clm-basic_interp">
+    <phase name="RUN">
+      <status>FAIL</status>
+      <issue>#2787</issue>
+      <comment>The issue shows how to fix it.</comment>
+    </phase>
+  </test>
+  <test name="ERS_Ly3.f10_f10_mg37.I1850Clm50BgcCropCmip6.derecho_intel.clm-basic">
+    <phase name="RUN">
+      <status>FAIL</status>
+      <issue>#2787</issue>
+      <comment>The issue shows how to fix it.</comment>
+    </phase>
+  </test>
+  <test name="SMS_Lm1.f10_f10_mg37.I1850Clm50BgcCropCmip6waccm.derecho_gnu.clm-basic">
+    <phase name="RUN">
+      <status>FAIL</status>
+      <issue>#2787</issue>
+      <comment>The issue shows how to fix it.</comment>
+    </phase>
+  </test>
+
+  <test name="SMS_Ld10_D_Mmpi-serial.CLM_USRDAT.I1PtClm60Bgc.izumi_nag.clm-default--clm-NEON-HARV--clm-matrixcnOn">
+    <phase name="RUN">
+      <status>FAIL</status>
+      <issue>#2780</issue>
+      <comment>Crashes in the matrix solver.</comment>
+    </phase>
+  </test>
+  <test name="SMS_Ld10_D_Mmpi-serial.CLM_USRDAT.I1PtClm60Bgc.derecho_gnu.clm-default--clm-NEON-HARV--clm-matrixcnOn">
+    <phase name="RUN">
+      <status>FAIL</status>
+      <issue>#2780</issue>
+      <comment>Crashes in the matrix solver.</comment>
+    </phase>
+  </test>
+  <test name="SMS_D.1x1_brazil.I1850Clm60BgcCrop.derecho_gnu.clm-mimics_matrixcn">
+    <phase name="RUN">
+      <status>FAIL</status>
+      <issue>#2780</issue>
+      <comment>Crashes in the matrix solver.</comment>
+    </phase>
+  </test>
+
   <test name="ERP_P64x2_Lm13.f10_f10_mg37.IHistClm60Bgc.derecho_intel.clm-monthly--clm-matrixcnOn_ignore_warnings">
     <phase name="BASELINE">
       <status>FAIL</status>
@@ -51,6 +95,13 @@
       <comment>This failure relates to the preceding ERP failure.</comment>
     </phase>
   </test>
+  <test name="REP_P64x2_Lm13.f10_f10_mg37.IHistClm60Bgc.derecho_intel.clm-monthly--clm-matrixcnOn_ignore_warnings">
+    <phase name="BASELINE">
+      <status>FAIL</status>
+      <issue>#2619</issue>
+      <comment>This failure relates to the preceding ERP failure.</comment>
+    </phase>
+  </test>
 
   <test name="PEM_D_Ld9.ne30pg3_t232.I1850Clm60BgcCropG.derecho_intel.clm-clm60cam7LndTuningMode">
     <phase name="COMPARE_base_modpes">

cime_config/testdefs/testmods_dirs/clm/Hillslope/shell_commands

@@ -2,3 +2,6 @@
 DIN_LOC_ROOT=$(./xmlquery --value DIN_LOC_ROOT)
 meshfile=$DIN_LOC_ROOT/lnd/clm2/testdata/ESMFmesh_10x15_synthetic_cosphill_1.0.nc
 ./xmlchange ATM_DOMAIN_MESH=${meshfile},LND_DOMAIN_MESH=${meshfile}
+
+# -ignore_warnings is needed as long as we don't allow use_hillslope and use_init_interp together
+./xmlchange --append CLM_BLDNML_OPTS=-ignore_warnings

doc/ChangeLog

@@ -1,4 +1,89 @@
 ===============================================================
+Tag name: ctsm5.3.001
+Originator(s): slevis (Samuel Levis,UCAR/TSS,303-665-1310)
+Date: Thu 26 Sep 2024 03:10:40 PM MDT
+One-line Summary: Merge b4b-dev
+
+Purpose and description of changes
+----------------------------------
+
+- Keith fixed comments on urban thermal variables.
+- Sam R removed references to PTCLM*.
+- Sam R made updates to the documentation.
+- Sam R made improvements to mesh_plotter.
+- Matvey and Sam R worked on hillslope hydrology warnings.
+- Matvey added a test and a warning.
+
+Significant changes to scientifically-supported configurations
+--------------------------------------------------------------
+
+Does this tag change answers significantly for any of the following physics configurations?
+(Details of any changes will be given in the "Answer changes" section below.)
+
+    [Put an [X] in the box for any configuration with significant answer changes.]
+
+[ ] clm6_0
+
+[ ] clm5_1
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed
+----------
+List of CTSM issues fixed (include CTSM Issue # and description) [one per line]:
+PR #2770 documentation fixes and improvements
+PR #2772 mesh_plotter improvements
+PR #2765 fix comments on urban thermal variables
+PR #2703 add a namelist warning
+
+Notes of particular relevance for users
+---------------------------------------
+Changes to documentation:
+ Yes, see "bugs fixed" above.
+
+
+Notes of particular relevance for developers:
+---------------------------------------------
+Changes to tests or testing:
+ Test(s) added to bld/unit_testers/build-namelist_test.pl
+
+
+Testing summary:
+----------------
+
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  build-namelist tests (if CLMBuildNamelist.pm has changed):
+
+    derecho - PASS
+
+  python testing (if python code has changed; see instructions in python/README.md; document testing done):
+
+    derecho - PASS
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    derecho ----- OK
+    izumi ------- OK
+
+
+Answer changes
+--------------
+Changes answers relative to baseline: No
+
+
+Other details
+-------------
+Pull Requests that document the changes (include PR ids):
+ https://github.com/ESCOMP/ctsm/pull/2792
+
+===============================================================
+===============================================================
 Tag name: ctsm5.3.0
 Originator(s): multiple (see below)
 Date: Wed 25 Sep 2024 01:22:06 AM MDT

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.3.001 multiple 09/26/2024 Merge b4b-dev
          ctsm5.3.0 multiple 09/24/2024 Update surface datasets, CN Matrix, CLM60: excess ice on, explicit A/C on, crop calendars, Sturm snow, Leung dust emissions, prigent roughness data
        ctsm5.2.029 multiple 09/24/2024 New surface datasets: double tag of ctsm5.3.0
        ctsm5.2.028   rgknox 09/05/2024 FATES history flushing update

doc/requirements.txt

@@ -0,0 +1,4 @@
+esbonio == 0.16.4
+sphinx == 7.2.6
+sphinx-mdinclude == 0.6.2
+sphinx_rtd_theme == 2.0.0

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