Skip to content

Commit e1f563b

Browse files
slevis-lmwgslevis-lmwg
authored
Merge pull request ESCOMP#4000 from slevis-lmwg/merge-b4bdev-20260507
Merge b4bdev 20260507
2 parents 1dc62aa + a68fe66 commit e1f563b

57 files changed

Lines changed: 2366 additions & 990 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 30 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,41 @@
1+
<!-- Please fill this out to the best of your ability when opening your PR! -->
2+
3+
<!-- **NOTE: Be sure to check your coding style against the standard
4+
(https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
5+
the list of common problems to watch out for
6+
(https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).** -->
7+
8+
19
### Description of changes
210

11+
<!-- Description goes here -->
12+
313
### Specific notes
414

5-
Contributors other than yourself, if any:
15+
**Contributors other than yourself, if any:**
16+
- (Replace this text and add more list items as needed)
617

7-
CTSM Issues Fixed (include github issue #):
18+
**CTSM issues resolved or otherwise addressed, if any:**
19+
- (Replace this text, including GitHub issue #, and add more list items as needed)
20+
<!-- Put each issue on its own line, like "Resolves #3986" or "Contributes to #3151". -->
21+
<!-- "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 -->
822

9-
Are answers expected to change (and if so in what way)?
23+
**If answers are expected to change, describe (delete this line otherwise):**
1024

11-
Any User Interface Changes (namelist or namelist defaults changes)?
25+
**Any user interface changes (namelist or namelist defaults changes)?**
1226

13-
Does this create a need to change or add documentation? Did you do so?
27+
**Testing planned or performed, if any:**
28+
- [ ] (Replace this text and add more list items as needed)
29+
<!-- (List what testing you did to show your changes worked as expected) -->
1430

15-
Testing performed, if any:
16-
(List what testing you did to show your changes worked as expected)
17-
(This can be manual testing or running of the different test suites)
18-
(Documentation on system testing is here: https://github.com/ESCOMP/ctsm/wiki/System-Testing-Guide)
19-
(aux_clm on derecho for intel/gnu and izumi for intel/gnu/nag/nvhpc is the standard for tags on master)
2031

21-
**NOTE: Be sure to check your coding style against the standard
22-
(https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
23-
the list of common problems to watch out for
24-
(https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).**
2532

26-
**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).**
33+
### Requirements before merge:
34+
- [ ] I have followed the [CTSM contribution guidelines](https://github.com/ESCOMP/CTSM/blob/master/CONTRIBUTING.md).
35+
<!-- Delete all list items below if this PR is purely Tech Note and/or User's Guide updates -->
36+
- [ ] The code in this PR branch builds with no errors.
37+
- [ ] The code in this PR branch runs with no errors. **Briefly describe tested configuration(s):**
38+
- [ ] 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?:**
39+
<!-- If (c) above, include your analyses in the "Description of changes" section. -->
40+
- [ ] 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:**
41+
- [ ] 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‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ on:
1111
- '!doc/*ChangeSum*'
1212
- '!doc/UpdateChangelog.pl'
1313
# Include all include::ed files outside doc/ directory!
14-
- 'src/README.unit_testing'
15-
- 'tools/README'
14+
- 'src/README.unit_testing.md'
15+
- 'tools/README.md'
1616
- 'doc/test/test_container_eq_ctsm_pylib.sh'
1717

1818
# Allows you to run this workflow manually from the Actions tab

‎.github/workflows/docs.yml‎

Lines changed: 139 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ on:
1313
- '!doc/UpdateChangelog.pl'
1414
- '.github/workflows/docs-common.yml'
1515
# Include all include::ed files outside doc/ directory!
16-
- 'src/README.unit_testing'
17-
- 'tools/README'
16+
- 'src/README.unit_testing.md'
17+
- 'tools/README.md'
1818
- 'doc/test/test_container_eq_ctsm_pylib.sh'
1919

2020
pull_request:
@@ -27,8 +27,8 @@ on:
2727
- '!doc/UpdateChangelog.pl'
2828
- '.github/workflows/docs-common.yml'
2929
# Include all include::ed files outside doc/ directory!
30-
- 'src/README.unit_testing'
31-
- 'tools/README'
30+
- 'src/README.unit_testing.md'
31+
- 'tools/README.md'
3232
- 'doc/test/test_container_eq_ctsm_pylib.sh'
3333

3434
workflow_dispatch:
@@ -82,3 +82,138 @@ jobs:
8282
with:
8383
name: test-build-docs-container_failed
8484
path: build-logs/
85+
86+
check-docs-style:
87+
if: ${{ always() }}
88+
name: Check documentation against style guide
89+
runs-on: ubuntu-latest
90+
steps:
91+
92+
- name: Checkout repository
93+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
94+
95+
- name: Disallow fake degree signs
96+
if: always()
97+
# Prevents anyone from using the masculine ordinal indicator, as well as superscript-o/O if
98+
# preceded by a digit in
99+
# - Markdown math style,
100+
# - reStructuredText math style,
101+
# - MyST text style, and
102+
# - reStructuredText text style,
103+
# with or without curly brackets and/or spaces.
104+
#
105+
# What follows is an explanation of the regex. Keep in mind that the superscript-o will
106+
# match whether it's an uppercase O or lowercase o because of the -i flag to grep, so that's
107+
# not handled in the regex.
108+
#
109+
# Markdown math style:
110+
# Markdown math superscripts look like $^o$. There can also be curly brackets, like
111+
# $^{o}$, which would allow you to put multiple characters (including spaces) in the
112+
# superscript. The preceding digit can be inside or outside the dollar signs, again with
113+
# or without spaces.
114+
#
115+
# There are two regex patterns separated by |, to handle the cases where the preceding
116+
# digit is outside or inside the dollar signs, respectively:
117+
# [0-9]\s*\\$\s*\^\{?\s*o
118+
# [0-9] Any digit
119+
# \s* Any number of spaces, including none
120+
# \\$ A literal dollar sign
121+
# \s* Any number of spaces, including none
122+
# \^ A literal caret
123+
# \{? Optionally a literal left curly bracket
124+
# \s* Any number of spaces, including none
125+
# o Lowercase o
126+
# \\\$[0-9]+\s*\^\{?\s*o\s*\}?
127+
# \\\$ A literal dollar sign
128+
# [0-9]+ One or more digits
129+
# \s* Any number of spaces, including none
130+
# \^ A literal caret
131+
# \{? Optionally a literal left curly bracket
132+
# \s* Any number of spaces, including none
133+
# o Lowercase o
134+
# \s* Any number of spaces, including none
135+
# \}? Optionally a literal right curly bracket
136+
#
137+
# MyST text style:
138+
# MyST text superscripts look like {sup}`o`. Here's the regex:
139+
# [0-9]\s*\{sup}\`\s*o\`
140+
# [0-9] Any digit
141+
# \s* Any number of spaces, including none
142+
# \{ A literal left curly bracket
143+
# sup The text "sup" designating the superscript role
144+
# \} A literal right curly bracket
145+
# \` A literal backtick
146+
# \s* Any number of spaces, including none
147+
# o Lowercase o
148+
# \` A literal backtick
149+
#
150+
# reStructuredText text style
151+
# Similar to MyST text superscripts, but with colons instead of curly brackets: :sup:`o`.
152+
# Another difference is that spaces aren't allowed inside the backticks. Also, there has
153+
# to be a space preceding the first colon; this can be preceded by a backslash to avoid
154+
# putting an extraneous space in the rendered text. Here's the regex:
155+
# [0-9]\\\? :sup:\`o\`
156+
# [0-9] Any digit
157+
# \\\? Optionally a literal backslash
158+
# (A literal space)
159+
# :sup: The text ":sup:" designating the superscript role
160+
# \` A literal backtick
161+
# o Lowercase o
162+
# \` A literal backtick
163+
#
164+
# reStructuredText math style
165+
# Mostly the same as reStructuredText text superscripts, but with :math: instead of
166+
# :sup:. In addition, the superscript can optionally be in curly brackets. There can be
167+
# a space after the first backtick but not before the last one.
168+
#
169+
# There are two regex patterns separated by |, to handle the cases where the preceding
170+
# digit is outside or inside the dollar signs, respectively:
171+
# [0-9]\\\? :math:\`\s*\^\{?\s*o\s*\}?\`
172+
# [0-9] Any digit
173+
# \\\? Optionally a literal backslash
174+
# (A literal space)
175+
# :math: The text ":math:" designating the math role
176+
# \` A literal backtick
177+
# \s* Any number of spaces, including none
178+
# \^ A literal caret
179+
# \{? Optionally a literal left curly bracket
180+
# \s* Any number of spaces, including none
181+
# o Lowercase o
182+
# \s* Any number of spaces, including none
183+
# \}? Optionally a literal right curly bracket
184+
# \` A literal backtick
185+
# :math:\`\s*[0-9]+\s*\^\{?\s*o\s*\}?\`
186+
# :math: The text ":math:" designating the math role
187+
# \` A literal backtick
188+
# \s* Any number of spaces, including none
189+
# [0-9]+ One or more digits
190+
# \s* Any number of spaces, including none
191+
# \^ A literal caret
192+
# \{? Optionally a literal left curly bracket
193+
# \s* Any number of spaces, including none
194+
# o Lowercase o
195+
# \s* Any number of spaces, including none
196+
# \}? Optionally a literal right curly bracket
197+
# \` A literal backtick
198+
run: |
199+
set +e
200+
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"))"
201+
set -e
202+
if [[ "$instances_of_fake_degree_signs" ]] then
203+
echo -e "Instances of superscript-o or masculine ordinal indicator (º) instead of degree sign (°):\n${instances_of_fake_degree_signs}"
204+
echo -e "\nSee https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-style-guide.html"
205+
exit 1
206+
fi
207+
exit 0
208+
209+
- name: Disallow curly apostrophes/quotes
210+
if: always()
211+
run: |
212+
set +e
213+
instances_of_curlies="$(grep -onE "“|”|‘|’" $(find doc -name "*.md" -or -name "*.rst"))"
214+
set -e
215+
if [[ "$instances_of_curlies" ]] then
216+
echo -e "Instances of curly apostrophes and/or quote marks:\n${instances_of_curlies}"
217+
exit 1
218+
fi
219+
exit 0

‎.gitmodules‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/mpi-serial
124124
[submodule "doc-builder"]
125125
path = doc/doc-builder
126126
url = https://github.com/ESMCI/doc-builder
127-
fxtag = v3.1.0
127+
fxtag = v3.1.1
128128
fxrequired = ToplevelOptional
129129
# Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
130130
fxDONOTUSEurl = https://github.com/ESMCI/doc-builder

0 commit comments

Comments
 (0)