Skip to content

Commit 780938e

Browse files
ekluzekekluzek
authored
Merge pull request #3147 from samsrabin/release-clm5.0-update-20250523
Update release-clm5.0 docs
2 parents e7285f6 + 6cd61c9 commit 780938e

12 files changed

Lines changed: 198 additions & 139 deletions

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,3 +116,7 @@ core.*
116116
*.log !run.log
117117
*.pyc
118118
Depends
119+
120+
# Docs output
121+
_build*/
122+
_publish*/

‎Externals.cfg‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ required = True
3737
local_path = doc/doc-builder
3838
protocol = git
3939
repo_url = https://github.com/ESMCI/doc-builder
40-
tag = v1.0.4
40+
tag = v2.0.0
4141
required = False
4242

4343
[externals_description]

‎doc/Makefile‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,13 @@ BUILDDIR = build
1212
help:
1313
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1414

15-
# 'make fetch-images' should be run before building the
16-
# documentation. (If building via https://github.com/ESMCI/doc-builder,
17-
# this is run automatically for you.) This is needed because we have
18-
# configured this repository (via an .lfsconfig file at the top level)
19-
# to NOT automatically fetch any of the large files when cloning /
20-
# fetching.
15+
# 'make fetch-images' should be run before building the documentation. (If building via
16+
# the build_docs command, this is run automatically for you.) This is needed because we
17+
# have configured this repository (via an .lfsconfig file at the top level) to NOT
18+
# automatically fetch any of the large files when cloning / fetching.
2119
fetch-images:
22-
git lfs pull --exclude=""
20+
git lfs install --force
21+
git lfs pull --exclude="" --include=""
2322

2423
.PHONY: help fetch-images Makefile
2524

‎doc/build_docs‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,17 @@
11
#!/usr/bin/env bash
2+
set -e
23

3-
if [ -f doc-builder/build_docs ]; then
4-
echo "Running: doc-builder/build_docs --fetch-images $@"
5-
doc-builder/build_docs --fetch-images "$@"
6-
else
7-
echo "Obtain doc-builder by running ./manage_externals/checkout_externals -o from the top-level"
4+
if [ ! -f doc-builder/build_docs ]; then
5+
script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
6+
pushd "${script_dir}/.." 1>/dev/null
7+
manage_externals/checkout_externals doc-builder
8+
popd 1>/dev/null
89
fi
10+
11+
echo "Running: make fetch-images"
12+
make fetch-images
13+
14+
echo "Running: ./doc-builder/build_docs $@"
15+
./doc-builder/build_docs "$@"
16+
17+
exit 0

‎doc/source/conf.py‎

Lines changed: 104 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,5 @@
11
# -*- coding: utf-8 -*-
22
#
3-
# clmdoc documentation build configuration file, created by
4-
# sphinx-quickstart on Thu Feb 23 17:14:30 2017.
5-
#
63
# This file is execfile()d with the current directory set to its
74
# containing dir.
85
#
@@ -18,10 +15,15 @@
1815
#
1916
import os
2017
import sys
21-
# Note that we need a specific version of sphinx_rtd_theme. This can be obtained with:
22-
# pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes
2318
import sphinx_rtd_theme
24-
# sys.path.insert(0, os.path.abspath('.'))
19+
20+
# Assumes you have substitutions.py on your path
21+
# pylint: disable=wrong-import-position
22+
dir2add = os.path.join(os.path.dirname(__file__))
23+
print(dir2add)
24+
sys.path.insert(0, dir2add)
25+
import substitutions as subs # pylint: disable=import-error
26+
from version_list import VERSION_LIST
2527

2628

2729
# -- General configuration ------------------------------------------------
@@ -37,51 +39,43 @@
3739
'sphinx.ext.autodoc',
3840
'sphinx.ext.todo',
3941
'sphinx.ext.coverage',
40-
'sphinx.ext.imgmath',
41-
'sphinx.ext.githubpages']
42+
'sphinx.ext.githubpages',
43+
'sphinx_mdinclude',
44+
]
4245

4346
# Add any paths that contain templates here, relative to this directory.
4447
templates_path = ['_templates']
4548

4649
# The suffix(es) of source filenames.
4750
# You can specify multiple suffix as a list of string:
4851
#
49-
# source_suffix = ['.rst', '.md']
50-
source_suffix = '.rst'
52+
source_suffix = ['.rst', '.md']
53+
# source_suffix = '.rst'
5154

5255
# The master toctree document.
53-
master_doc = 'index'
56+
source_start_file = 'index'
5457

55-
# General information about the project.
56-
project = u'ctsm'
57-
copyright = u'2020, UCAR'
58-
author = u''
59-
60-
# The version info for the project you're documenting, acts as replacement for
61-
# |version| and |release|, also used in various other places throughout the
62-
# built documents.
63-
#
64-
# The short X.Y version.
65-
version = u'CLM5.0'
66-
# The full version, including alpha/beta/rc tags.
67-
release = u'release-clm5.0'
68-
# CTSM-specific: version label used at the top of some pages.
69-
version_label = 'CLM5.0 (CESM2.1)'
58+
# Save standard Sphinx substitution vars separately
59+
project = subs.project
60+
copyright = subs.copyright # pylint: disable=redefined-builtin
61+
author = subs.author
62+
version = subs.version
63+
release = subs.release
7064

7165
# version_label is not a standard sphinx variable, so we need some custom rst to allow
7266
# pages to use it. We need a separate replacement for the bolded version because it
7367
# doesn't work to have variable replacements within formatting.
7468
rst_epilog = """
7569
.. |version_label| replace:: {version_label}
7670
.. |version_label_bold| replace:: **{version_label}**
77-
""".format(version_label=version_label)
71+
""".format(version_label=subs.version_label)
7872

7973
# The language for content autogenerated by Sphinx. Refer to documentation
8074
# for a list of supported languages.
8175
#
8276
# This is also used if you do content translation via gettext catalogs.
8377
# Usually you set "language" from the command line for these cases.
84-
language = None
78+
language = "en"
8579

8680
# List of patterns, relative to source directory, that match files and
8781
# directories to ignore when looking for source files.
@@ -94,8 +88,6 @@
9488
# If true, `todo` and `todoList` produce output, else they produce nothing.
9589
todo_include_todos = True
9690

97-
imgmath_image_format = 'svg'
98-
9991
# -- Options for HTML output ----------------------------------------------
10092

10193
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -106,15 +98,6 @@
10698
# Theme options are theme-specific and customize the look and feel of a theme
10799
# further. For a list of options available for each theme, see the
108100
# documentation.
109-
#
110-
# The 'versions' option needs to have at least two versions to work, but it doesn't need
111-
# to have all versions: others will be added dynamically. Note that this maps from version
112-
# names to html links. The current version can link to the current location (i.e., do
113-
# nothing). For the other version, we just add a place-holder; its name and value are
114-
# unimportant because these versions will get replaced dynamically.
115-
html_theme_options = {}
116-
html_theme_options['versions'] = {version: ''}
117-
html_theme_options['versions']['[placeholder]'] = ''
118101

119102
# Add any paths that contain custom static files (such as style sheets) here,
120103
# relative to this directory. They are copied after the builtin static files,
@@ -124,64 +107,70 @@
124107

125108
# -- Options for HTMLHelp output ------------------------------------------
126109

127-
# Output file base name for HTML help builder.
128-
htmlhelp_basename = 'clmdocdoc'
110+
if getattr(subs, "htmlhelp", False):
111+
htmlhelp_basename = subs.htmlhelp["basename"]
129112

130113

131114
# -- Options for LaTeX output ---------------------------------------------
132-
133-
latex_elements = {
134-
# The paper size ('letterpaper' or 'a4paper').
135-
#
136-
# 'papersize': 'letterpaper',
137-
138-
# The font size ('10pt', '11pt' or '12pt').
139-
#
140-
# 'pointsize': '10pt',
141-
142-
# Additional stuff for the LaTeX preamble.
143-
#
144-
'preamble': '\\usepackage{hyperref}',
145-
146-
'fncychap': '\\usepackage[Conny]{fncychap}',
147-
148-
# Latex figure (float) alignment
149-
#
150-
# 'figure_align': 'htbp',
151-
}
152-
153-
# Grouping the document tree into LaTeX files. List of tuples
154-
# (source start file, target name, title,
155-
# author, documentclass [howto, manual, or own class]).
156-
latex_documents = [(master_doc, 'clmdoc.tex', u'CLM5 Documentation', '', 'manual'),]
157-
158-
159-
# -- Options for manual page output ---------------------------------------
160-
161-
# One entry per manual page. List of tuples
162-
# (source start file, name, description, authors, manual section).
163-
man_pages = [
164-
(master_doc, 'clmdoc', u'clmdoc Documentation',
165-
[author], 1)
166-
]
167-
168-
169-
# -- Options for Texinfo output -------------------------------------------
170-
171-
# Grouping the document tree into Texinfo files. List of tuples
172-
# (source start file, target name, title, author,
173-
# dir menu entry, description, category)
174-
texinfo_documents = [
175-
(master_doc, 'clmdoc', u'clmdoc Documentation',
176-
author, 'clmdoc', 'One line description of project.',
177-
'Miscellaneous'),
178-
]
179-
180-
181-
115+
if getattr(subs, "latex", False):
116+
117+
latex_elements = {
118+
# The paper size ('letterpaper' or 'a4paper').
119+
#
120+
# 'papersize': 'letterpaper',
121+
122+
# The font size ('10pt', '11pt' or '12pt').
123+
#
124+
# 'pointsize': '10pt',
125+
126+
# Additional stuff for the LaTeX preamble.
127+
#
128+
'preamble': '\\usepackage{hyperref}',
129+
130+
'fncychap': '\\usepackage[Conny]{fncychap}',
131+
132+
# Latex figure (float) alignment
133+
#
134+
# 'figure_align': 'htbp',
135+
}
136+
137+
# Grouping the document tree into LaTeX files. List of tuples
138+
# (source start file, target name, title,
139+
# author, documentclass [howto, manual, or own class]).
140+
latex_documents = [(
141+
source_start_file,
142+
subs.latex["target_name"],
143+
subs.latex["title"],
144+
author,
145+
subs.latex["category"],
146+
)]
147+
148+
149+
# Options for manual page and Texinfo output
150+
if getattr(subs, "mantex", False):
151+
152+
# One entry per manual page. List of tuples
153+
# (source start file, name, title, authors, manual section).
154+
man_pages = [
155+
(source_start_file, subs.mantex["name"], subs.mantex["title"], [author], 1),
156+
]
157+
158+
if getattr(subs, "tex", False):
159+
# Grouping the document tree into Texinfo files. List of tuples
160+
# (source start file, target name, title, author,
161+
# dir menu entry, description, category)
162+
texinfo_documents = [(
163+
source_start_file,
164+
subs.mantex["name"],
165+
subs.mantex["title"],
166+
author,
167+
subs.tex["dirmenu_entry"],
168+
subs.tex["description"],
169+
subs.tex["category"]),
170+
]
182171

183172
# Example configuration for intersphinx: refer to the Python standard library.
184-
intersphinx_mapping = {'https://docs.python.org/': None}
173+
intersphinx_mapping = {'python': ('https://docs.python.org/', None)}
185174

186175
numfig = True
187176
numfig_format = {'figure': 'Figure %s',
@@ -192,4 +181,26 @@
192181
numfig_secnum_depth = 2
193182

194183
def setup(app):
195-
app.add_stylesheet('css/custom.css')
184+
app.add_css_file('css/custom.css')
185+
186+
try:
187+
html_context
188+
except NameError:
189+
html_context = dict()
190+
191+
html_context["display_lower_left"] = True
192+
193+
# Whether to show the version dropdown. If not set as environment variable, or environment variable
194+
# is Python-falsey, do not show it.
195+
version_dropdown = os.environ.get("version_dropdown")
196+
197+
if version_dropdown:
198+
html_context["current_version"] = os.environ["version_display_name"]
199+
200+
html_context["versions"] = []
201+
pages_root = os.environ["pages_root"]
202+
for this_version in VERSION_LIST:
203+
html_context["versions"].append([
204+
this_version.display_name,
205+
os.path.join(pages_root, this_version.subdir()),
206+
])

‎doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,9 @@ and discharges the water to its downstream spatial unit or the ocean.
4747
4848
.. _Figure MOSART conceptual diagram:
4949

50-
.. figure:: mosart_diagram.png
51-
:width: 800px
52-
:height: 400px
50+
.. Figure:: mosart_diagram.png
51+
52+
MOSART conceptual diagram
5353

5454
MOSART only routes positive runoff, although negative runoff can be generated
5555
occasionally by the land model (e.g., :math:`q_{gwl}`). Negative runoff in any

‎doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,3 @@ Example 6-1. Example of running PTCLMmkdata for US-UMB on cheyenne
134134

135135

136136
PTCLMmkdata includes a README file that gives some extra details and a simple example.
137-
138-
.. include:: ../../../../tools/PTCLM/README
139-
:literal:

‎doc/source/users_guide/testing/testing.rst‎

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,6 @@ tests as well as lists of tests. The standard testname for CLM is "aux_clm" for
2626
well as the CGD machine hobart for intel, nag, and pgi compilers. There's also a shorter test list called "clm_short". Also
2727
see the `CTSM Wiki on Testing <https://github.com/ESCOMP/ctsm/wiki/System-Testing-Guide>`_.
2828

29-
CTSM Tools Testing
30-
==================
31-
32-
.. include:: ../../../../test/tools/README
33-
:literal:
34-
3529
CTSM Fortran Unit Tests
3630
=======================
3731

@@ -46,16 +40,3 @@ Run the following perl tester that
4640
::
4741
> cd bld/unit_testers
4842
> ./build-namelist_test.pl
49-
50-
51-
Testing PTCLM
52-
=============
53-
54-
.. include:: ../../../../tools/PTCLM/README
55-
:literal:
56-
57-
To run on cheyenne, you do the following:
58-
59-
60-
.. include:: ../../../../tools/PTCLM/test/README.run_cheyenne
61-
:literal:

‎doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,6 @@ More details on each environment variable.
9797

9898
.. note:: There are several files that are copies of the original files. By having copies the tools can all be made stand-alone, but any changes to the originals will have to be put into the tool directories as well.
9999

100-
The *README.filecopies* (which can be found in ``$CTSMROOT/tools``) is repeated here.
101-
102-
.. include:: ../../../../tools/README.filecopies
103-
:literal:
104-
105100
================================================================
106101
Building the CLM tools that use the CIME configure/build system
107102
================================================================

0 commit comments

Comments
 (0)