Add GitHub workflows to enforce docs style guide

.github/workflows/docs.yml

@@ -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

doc/README.CHECKLIST.master_tags.md

@@ -27,7 +27,7 @@ https://github.com/ESCOMP/ctsm/wiki/CTSM-development-workflow
    3c -- make sure you understand any changes to the baselines -- to document in ChangeLog
    3d -- Check the log file for run_sys_tests (`../run_sys_test.log`, to make sure that
          submodules are correct (see 2c above)
-   3e -- When Izumi’s baseline is ready, manually open read permissions to all.
+   3e -- When Izumi's baseline is ready, manually open read permissions to all.
 > [!TIP]
 > Always test on your fork with a feature-branch so that we can change tag order if needed. Put
 > baselines in the next tag name, as we can easily change afterwards if needed.

doc/WhatsNewInCTSM5.3.md

@@ -18,7 +18,7 @@ Changes to defaults for `clm6_0` physics:
 
 * Urban explicit A/C turned on (links above).
 * Snow thermal conductivity method is now `Sturm1997`. ([PR \#2348](https://github.com/ESCOMP/CTSM/pull/2348); see also [discussion \#1960](https://github.com/ESCOMP/CTSM/discussions/1960))
-* New initial conditions files for f09 ("1-degree" 1850, 2000), f19 (“2-degree” 1850), and ne30 (1850, 1979, 2000) resolutions.
+* New initial conditions files for f09 ("1-degree" 1850, 2000), f19 ("2-degree" 1850), and ne30 (1850, 1979, 2000) resolutions.
 * New crop calendars. ([PR \#2664](https://github.com/ESCOMP/CTSM/pull/2664); informed by [Rabin et al., 2023](https://gmd.copernicus.org/articles/16/7253/2023/gmd-16-7253-2023.html))
 * Dust emissions method is now `Leung_2023` (links above).
 * Excess ice is turned on. ([PR \#1787](https://github.com/ESCOMP/CTSM/pull/1787))
@@ -35,8 +35,8 @@ Changes for all physics versions:
 
 ### Heads up
 
-* Small glacier changes mean that you can’t use a 5.3 surface dataset with pre-5.3 code and vice versa anymore. (Merged with [PR \#2500](https://github.com/ESCOMP/CTSM/pull/2500))
-* Updates the definition of history variable “time” from *end* of `time_bounds` to *middle* of `time_bounds`. ([PR \#2838](https://github.com/ESCOMP/CTSM/pull/2838); see section below)
+* Small glacier changes mean that you can't use a 5.3 surface dataset with pre-5.3 code and vice versa anymore. (Merged with [PR \#2500](https://github.com/ESCOMP/CTSM/pull/2500))
+* Updates the definition of history variable "time" from *end* of `time_bounds` to *middle* of `time_bounds`. ([PR \#2838](https://github.com/ESCOMP/CTSM/pull/2838); see section below)
 * Standardizes history variable attributes and a history dimension name. ([PR \#2052](https://github.com/ESCOMP/CTSM/pull/2052); see section below)
 
 ##
@@ -49,7 +49,7 @@ Changes for all physics versions:
 
 Startup and hybrid runs no longer run the 0th time step, consistent with the same change in CAM. (Branch and continue runs never had this 0th time step.) This means you will not get an extraneous initial history file anymore. In some circumstances this may also affect the names of history files.
 
-In most cases, the history `time` variable is now defined as the middle of a history file’s `time_bounds` instead of the end, for consistency with the same change in CAM. The exception is if you specify `hist_avgflag_pertape = 'I'` for that file, in which case it will be treated as an “instantaneous” file. Instantaneous history files (a) have their `time` coordinate set to the end of the last timestep (as did all history files before this tag) and (b) do not include `time_bounds`.
+In most cases, the history `time` variable is now defined as the middle of a history file's `time_bounds` instead of the end, for consistency with the same change in CAM. The exception is if you specify `hist_avgflag_pertape = 'I'` for that file, in which case it will be treated as an "instantaneous" file. Instantaneous history files (a) have their `time` coordinate set to the end of the last timestep (as did all history files before this tag) and (b) do not include `time_bounds`.
 
 The history dimension name `hist_interval` (of output variable `time_bounds`) is standardized to be `nbnd`. History variables `time_bounds`, `mcdate`, `mcsec`, `mdcur`, and `mscur` are standardized to include the calendar attribute.
 
@@ -77,7 +77,7 @@ The history dimension name `hist_interval` (of output variable `time_bounds`) is
 
 ### Changes to rpointer files
 
-The rpointer files are simple text files that CESM uses to keep track of how far simulations have progressed, pointing to the filename of the latest restart file for that component. There is one such file for each component, so for CTSM `I` cases that's `lnd`, `cpl`, and `atm` (and `rof` if it's active). Normally, when the user is just extending the length  of simulations, there’s no need to worry about these files.
+The rpointer files are simple text files that CESM uses to keep track of how far simulations have progressed, pointing to the filename of the latest restart file for that component. There is one such file for each component, so for CTSM `I` cases that's `lnd`, `cpl`, and `atm` (and `rof` if it's active). Normally, when the user is just extending the length  of simulations, there's no need to worry about these files.
 
 However, if there was a problem when a simulation shut down, it's possible that different components will have mismatched restarts and rpointer files. In the past, this meant figuring out what restart file should be pointed to in each component rpointer file and correcting it by hand in an editor. There was only the final set of rpointer files that was kept for a case.
 

doc/WhatsNewInCTSM5.4.md

@@ -14,7 +14,7 @@
 
 * Unsupported script that checks for spinup equilibrium in `tools/contrib/` for spectral element grids ([PR #2991](https://github.com/ESCOMP/ctsm/pull/2991)).  
 * New paramfile tools that allow users to query and modify CLM parameter files ([documentation](https://escomp.github.io/CTSM/users_guide/using-clm-tools/paramfile-tools.html))  
-* Optional time-evolving \`leafcn\_target\`. More under “Additional detail” below.  
+* Optional time-evolving \`leafcn\_target\`. More under "Additional detail" below.  
 * New vertical movement scheme for soil nitrate, which is off by default (PR [#2992](https://github.com/ESCOMP/CTSM/pull/2992)).  
 * Documentation improvements and new URL: https://escomp.github.io/CTSM/index.html.  
 * FATES:  
@@ -32,9 +32,9 @@ Changes to defaults for \`clm6\` physics:
 * Updates to MEGAN for BVOCs (https://github.com/ESCOMP/CTSM/pull/3065 https://github.com/ESCOMP/CTSM/pull/3309). Removes dependence on soil moisture from clm6 physics.  
 * New model parameter values that were calibrated to improve carbon cycle representation with CRUJRA.  
 * New model parameter values that were calibrated to improve the fire model. Now using li2024 fire code.  
-* New initial conditions files for f09 ("1-degree" 1850, 2000), f19 (“2-degree” 1850), and ne30 (1850, 1979, 2000\) resolutions.  
+* New initial conditions files for f09 ("1-degree" 1850, 2000), f19 ("2-degree" 1850), and ne30 (1850, 1979, 2000\) resolutions.  
 * Change default for glcmec\_downscale\_longwave to FALSE for clm6 physics as turning off the LW downscaling improves the melt and runoff biases.  
-* See “Changes to FATES and the FATES parameter file” below.  
+* See "Changes to FATES and the FATES parameter file" below.  
 * Namelist defaults change so that  
   * use\_c13/use\_c14 are on only for HistClm60Bgc compsets with CRUJRA2024 or CAM7 forcing; examples of when use\_c13/use\_c14 are now off include SSP and single-point compsets, as well as cases using older forcings, such as CAM6, GSWP3v1, Qian, and CRUv7  
   * when use\_c13 or use\_c14 is on, turn on the corresponding time series file  (responding to the CLM_CMIP_ERA flag)
@@ -44,13 +44,13 @@ Changes to defaults for \`clm6\` physics:
 Changes for all physics versions:
 
 * Parameters updated: Added MIMICS parameter \`mimics\_fi\` (fraction of litter inputs that bypass litter pools, directly contributing to SOM) and updated other MIMICS parameters (https://github.com/ESCOMP/CTSM/pull/2365) to remove NPP control on turnover, fix density dependent control on turnover, add litterfall fluxes that bypass litter pools and contribute directly to soil organic matter.  
-* FATES parameter file updated: ([PR \#2965](https://github.com/ESCOMP/CTSM/pull/2965), [PR \#2904](https://github.com/ESCOMP/CTSM/pull/2904), [PR \#1344](https://github.com/NGEET/fates/pull/1344), [PR \#3087](https://github.com/ESCOMP/CTSM/pull/3087)). See “FATES parameter file” section below for details.  
-* New surface datasets and landuse timeseries files (see “surface datasets” section below).
+* FATES parameter file updated: ([PR \#2965](https://github.com/ESCOMP/CTSM/pull/2965), [PR \#2904](https://github.com/ESCOMP/CTSM/pull/2904), [PR \#1344](https://github.com/NGEET/fates/pull/1344), [PR \#3087](https://github.com/ESCOMP/CTSM/pull/3087)). See "FATES parameter file" section below for details.  
+* New surface datasets and landuse timeseries files (see "surface datasets" section below).
 * CMIP7 C13/C14 atmospheric timeseries data
 
 ## Heads up
 
-* History tapes now split into two files from hX to hXi and hXa, where X is the tape number (e.g. h0i/h0a) and where "i" stands for history file containing instantaneous fields, while "a" stands for history file containing non-instantaneous fields. Details in the “history files” section below and in the PRs https://github.com/ESCOMP/ctsm/pull/2445 https://github.com/ESCOMP/MOSART/pull/117 https://github.com/ESCOMP/RTM/pull/61 and the corresponding issues.  
+* History tapes now split into two files from hX to hXi and hXa, where X is the tape number (e.g. h0i/h0a) and where "i" stands for history file containing instantaneous fields, while "a" stands for history file containing non-instantaneous fields. Details in the "history files" section below and in the PRs https://github.com/ESCOMP/ctsm/pull/2445 https://github.com/ESCOMP/MOSART/pull/117 https://github.com/ESCOMP/RTM/pull/61 and the corresponding issues.  
 * Adding time to 1d weighting fields in transient simulations PR https://github.com/ESCOMP/CTSM/pull/3328  
 * Regarding CMIP7 vs. CMIP6 inputs:  
   * C13/C14 isotope datasets are the new CMIP7 datasets using streams, while when CLM_CMIP_ERA==cmip6, the older cmip6 files are used
@@ -59,14 +59,14 @@ Changes for all physics versions:
   * For DATM we supply only CMIP6 aerosols.  
   * For DATM we supply only CMIP6 CO2.  
 * Issue with DOUT\_S\_SAVE\_INTERIM\_REST [https://github.com/ESCOMP/CTSM/issues/3351](https://github.com/ESCOMP/CTSM/issues/3351) was fixed.  
-* As of ctsm5.3.040, the new ctsm\_pylib conda environment is incompatible with our tools from before ctsm5.3.040 and vice versa. More under “Additional detail” below.
+* As of ctsm5.3.040, the new ctsm\_pylib conda environment is incompatible with our tools from before ctsm5.3.040 and vice versa. More under "Additional detail" below.
 
 # Additional detail
 
 ## Changes related to history files
 
 (Note 1: The same information in this section applies to MOSART and RTM.  
-Note 2: The gist of the information in this section also appears in the [CTSM User’s Guide](https://escomp.github.io/CTSM/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.html#various-ways-to-change-history-output-averaging-flags)).
+Note 2: The gist of the information in this section also appears in the [CTSM User's Guide](https://escomp.github.io/CTSM/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.html#various-ways-to-change-history-output-averaging-flags)).
 
 Following ctsm5.3.018 "Change history time to be the middle of the time bounds" and keeping CLM history consistent with CAM history, the CTSM5.4 change intends to prevent confusion associated with the time corresponding to instantaneous history fields by putting them on separate files than non-instantaneous fields.
 
@@ -99,7 +99,7 @@ The CLM handles empty history (and corresponding history-restart) files by not g
 
 ## Changes to FATES and the FATES parameter file
 
-* See [HLM-FATES compatibility table](https://fates-users-guide.readthedocs.io/en/latest/user/release-tags-compat-table.html) in the FATES user’s guide for all FATES tags associated with CTSM tag updates  
+* See [HLM-FATES compatibility table](https://fates-users-guide.readthedocs.io/en/latest/user/release-tags-compat-table.html) in the FATES user's guide for all FATES tags associated with CTSM tag updates  
 * FATES answer changing updates  
   * The default hydro solver is updated to 2D Picard from 1D Taylor ([ctsm5.3.027](https://github.com/ESCOMP/CTSM/releases/tag/ctsm5.3.027))  
   * Simplified leaf sun-shade fraction for two-stream radiation ([sci.1.83.0\_api.39.0.0](https://github.com/NGEET/fates/releases/tag/sci.1.83.0_api.39.0.0))