Merge b4bdev 20260507

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,26 +1,41 @@
+<!-- Please fill this out to the best of your ability when opening your PR! -->
+
+<!-- **NOTE: Be sure to check your coding style against the standard
+(https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
+the list of common problems to watch out for
+(https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).** -->
+
+
 ### Description of changes
 
+<!-- Description goes here -->
+
 ### Specific notes
 
-Contributors other than yourself, if any:
+**Contributors other than yourself, if any:**
+- (Replace this text and add more list items as needed)
 
-CTSM Issues Fixed (include github issue #):
+**CTSM issues resolved or otherwise addressed, if any:**
+- (Replace this text, including GitHub issue #, and add more list items as needed)
+<!-- Put each issue on its own line, like "Resolves #3986" or "Contributes to #3151". -->
+<!-- "Resolves" is a magic word; see them all at https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue -->
 
-Are answers expected to change (and if so in what way)?
+**If answers are expected to change, describe (delete this line otherwise):**
 
-Any User Interface Changes (namelist or namelist defaults changes)?
+**Any user interface changes (namelist or namelist defaults changes)?**
 
-Does this create a need to change or add documentation? Did you do so?
+**Testing planned or performed, if any:**
+- [ ] (Replace this text and add more list items as needed)
+<!-- (List what testing you did to show your changes worked as expected) -->
 
-Testing performed, if any:
-(List what testing you did to show your changes worked as expected)
-(This can be manual testing or running of the different test suites)
-(Documentation on system testing is here: https://github.com/ESCOMP/ctsm/wiki/System-Testing-Guide)
-(aux_clm on derecho for intel/gnu and izumi for intel/gnu/nag/nvhpc is the standard for tags on master)
 
-**NOTE: Be sure to check your coding style against the standard
-(https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
-the list of common problems to watch out for
-(https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).**
 
-**If this PR changes the CTSM web documentation, please see our [contribution guidelines for documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines).**
+### Requirements before merge:
+- [ ] I have followed the [CTSM contribution guidelines](https://github.com/ESCOMP/CTSM/blob/master/CONTRIBUTING.md).
+<!-- Delete all list items below if this PR is purely Tech Note and/or User's Guide updates -->
+- [ ] The code in this PR branch builds with no errors.
+- [ ] The code in this PR branch runs with no errors. **Briefly describe tested configuration(s):**
+- [ ] This either (a) does not change answers, (b) it only changes answers at roundoff level, or (c) I have performed a scientific evaluation of the answer changes. **Which?:**
+<!-- If (c) above, include your analyses in the "Description of changes" section. -->
+- [ ] I have reviewed relevant parts of the CLM documentation [Tech Note](https://escomp.github.io/CTSM/tech_note/index.html) or [User's Guide](https://escomp.github.io/CTSM/users_guide/index.html) to determine if anything needs to be changed or added. **If it does, describe:**
+- [ ] This PR either (a) does not create a need to update the documentation or (b) includes required documentation updates (see [guidelines for contributing documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines)). **Which?:**

.github/workflows/docs-build-and-deploy.yml

@@ -11,8 +11,8 @@ on:
       - '!doc/*ChangeSum*'
       - '!doc/UpdateChangelog.pl'
       # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'src/README.unit_testing.md'
+      - 'tools/README.md'
       - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   # Allows you to run this workflow manually from the Actions tab

.github/workflows/docs.yml

@@ -13,8 +13,8 @@ on:
       - '!doc/UpdateChangelog.pl'
       - '.github/workflows/docs-common.yml'
       # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'src/README.unit_testing.md'
+      - 'tools/README.md'
       - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   pull_request:
@@ -27,8 +27,8 @@ on:
       - '!doc/UpdateChangelog.pl'
       - '.github/workflows/docs-common.yml'
       # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'src/README.unit_testing.md'
+      - 'tools/README.md'
       - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   workflow_dispatch:
@@ -82,3 +82,138 @@ jobs:
         with:
           name: test-build-docs-container_failed
           path: build-logs/
+
+  check-docs-style:
+    if: ${{ always() }}
+    name: Check documentation against style guide
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Disallow fake degree signs
+        if: always()
+        # Prevents anyone from using the masculine ordinal indicator, as well as superscript-o/O if
+        # preceded by a digit in
+        # - Markdown math style,
+        # - reStructuredText math style,
+        # - MyST text style, and
+        # - reStructuredText text style,
+        # with or without curly brackets and/or spaces.
+        #
+        # What follows is an explanation of the regex. Keep in mind that the superscript-o will
+        # match whether it's an uppercase O or lowercase o because of the -i flag to grep, so that's
+        # not handled in the regex.
+        #
+        # Markdown math style:
+        #   Markdown math superscripts look like $^o$. There can also be curly brackets, like
+        #   $^{o}$, which would allow you to put multiple characters (including spaces) in the
+        #   superscript. The preceding digit can be inside or outside the dollar signs, again with
+        #   or without spaces.
+        #
+        #   There are two regex patterns separated by |, to handle the cases where the preceding
+        #   digit is outside or inside the dollar signs, respectively:
+        #       [0-9]\s*\\$\s*\^\{?\s*o
+        #           [0-9]   Any digit
+        #           \s*     Any number of spaces, including none
+        #           \\$     A literal dollar sign
+        #           \s*     Any number of spaces, including none
+        #           \^      A literal caret
+        #           \{?     Optionally a literal left curly bracket
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #       \\\$[0-9]+\s*\^\{?\s*o\s*\}?
+        #           \\\$    A literal dollar sign
+        #           [0-9]+  One or more digits
+        #           \s*     Any number of spaces, including none
+        #           \^      A literal caret
+        #           \{?     Optionally a literal left curly bracket
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #           \s*     Any number of spaces, including none
+        #           \}?     Optionally a literal right curly bracket
+        #
+        # MyST text style:
+        #   MyST text superscripts look like {sup}`o`. Here's the regex:
+        #       [0-9]\s*\{sup}\`\s*o\`
+        #           [0-9]   Any digit
+        #           \s*     Any number of spaces, including none
+        #           \{      A literal left curly bracket
+        #           sup     The text "sup" designating the superscript role
+        #           \}      A literal right curly bracket
+        #           \`      A literal backtick
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #           \`      A literal backtick
+        #
+        # reStructuredText text style
+        #   Similar to MyST text superscripts, but with colons instead of curly brackets: :sup:`o`.
+        #   Another difference is that spaces aren't allowed inside the backticks. Also, there has
+        #   to be a space preceding the first colon; this can be preceded by a backslash to avoid
+        #   putting an extraneous space in the rendered text. Here's the regex:
+        #       [0-9]\\\? :sup:\`o\`
+        #           [0-9]   Any digit
+        #           \\\?    Optionally a literal backslash
+        #             (A literal space)
+        #           :sup:   The text ":sup:" designating the superscript role
+        #           \`      A literal backtick
+        #           o       Lowercase o
+        #           \`      A literal backtick
+        #
+        # reStructuredText math style
+        #    Mostly the same as reStructuredText text superscripts, but with :math: instead of
+        #    :sup:. In addition, the superscript can optionally be in curly brackets. There can be
+        #    a space after the first backtick but not before the last one.
+        #
+        #   There are two regex patterns separated by |, to handle the cases where the preceding
+        #   digit is outside or inside the dollar signs, respectively:
+        #       [0-9]\\\? :math:\`\s*\^\{?\s*o\s*\}?\`
+        #           [0-9]   Any digit
+        #           \\\?    Optionally a literal backslash
+        #             (A literal space)
+        #           :math:  The text ":math:" designating the math role
+        #           \`      A literal backtick
+        #           \s*     Any number of spaces, including none
+        #           \^      A literal caret
+        #           \{?     Optionally a literal left curly bracket
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #           \s*     Any number of spaces, including none
+        #           \}?     Optionally a literal right curly bracket
+        #           \`      A literal backtick
+        #       :math:\`\s*[0-9]+\s*\^\{?\s*o\s*\}?\`
+        #           :math:  The text ":math:" designating the math role
+        #           \`      A literal backtick
+        #           \s*     Any number of spaces, including none
+        #           [0-9]+  One or more digits
+        #           \s*     Any number of spaces, including none
+        #           \^      A literal caret
+        #           \{?     Optionally a literal left curly bracket
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #           \s*     Any number of spaces, including none
+        #           \}?     Optionally a literal right curly bracket
+        #           \`      A literal backtick
+        run: |
+          set +e
+          instances_of_fake_degree_signs="$(grep -ionE "[0-9]\s*\\$\s*\^\{?\s*o|\\\$[0-9]+\s*\^\{?\s*o\s*\}?|[0-9]\s*\{sup}\`\s*o\`|[0-9]\\\? :sup:\`o\`|[0-9]\\\? :math:\`\s*\^\{?\s*o\s*\}?\`| :math:\`\s*[0-9]+\s*\^\{?\s*o\s*\}?\`|º" $(find doc -name "*.md" -or -name "*.rst"))"
+          set -e
+          if [[ "$instances_of_fake_degree_signs" ]] then
+            echo -e "Instances of superscript-o or masculine ordinal indicator (º) instead of degree sign (°):\n${instances_of_fake_degree_signs}"
+            echo -e "\nSee https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-style-guide.html"
+            exit 1
+          fi
+          exit 0
+
+      - name: Disallow curly apostrophes/quotes
+        if: always()
+        run: |
+          set +e
+          instances_of_curlies="$(grep -onE "“|”|‘|’" $(find doc -name "*.md" -or -name "*.rst"))"
+          set -e
+          if [[ "$instances_of_curlies" ]] then
+            echo -e "Instances of curly apostrophes and/or quote marks:\n${instances_of_curlies}"
+            exit 1
+          fi
+          exit 0

.gitmodules

@@ -124,7 +124,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/mpi-serial
 [submodule "doc-builder"]
 path = doc/doc-builder
 url = https://github.com/ESMCI/doc-builder
-fxtag = v3.1.0
+fxtag = v3.1.1
 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