Update release-clm5.0 docs

.gitignore

@@ -116,3 +116,7 @@ core.*
 *.log !run.log
 *.pyc
 Depends
+
+# Docs output
+_build*/
+_publish*/

Externals.cfg

@@ -37,7 +37,7 @@ required = True
 local_path = doc/doc-builder
 protocol = git
 repo_url = https://github.com/ESMCI/doc-builder
-tag = v1.0.4
+tag = v2.0.0
 required = False
 
 [externals_description]

doc/Makefile

@@ -12,14 +12,13 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-# 'make fetch-images' should be run before building the
-# documentation. (If building via https://github.com/ESMCI/doc-builder,
-# this is run automatically for you.) This is needed because we have
-# configured this repository (via an .lfsconfig file at the top level)
-# to NOT automatically fetch any of the large files when cloning /
-# fetching.
+# 'make fetch-images' should be run before building the documentation. (If building via
+# the build_docs command, this is run automatically for you.) This is needed because we
+# have configured this repository (via an .lfsconfig file at the top level) to NOT
+# automatically fetch any of the large files when cloning / fetching.
 fetch-images:
-	git lfs pull --exclude=""
+	git lfs install --force
+	git lfs pull --exclude="" --include=""
 
 .PHONY: help fetch-images Makefile
 

doc/build_docs

@@ -1,8 +1,17 @@
 #!/usr/bin/env bash
+set -e
 
-if [ -f doc-builder/build_docs ]; then
-    echo "Running: doc-builder/build_docs --fetch-images $@"
-    doc-builder/build_docs --fetch-images "$@"
-else
-    echo "Obtain doc-builder by running ./manage_externals/checkout_externals -o from the top-level"
+if [ ! -f doc-builder/build_docs ]; then
+    script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+    pushd "${script_dir}/.." 1>/dev/null
+    manage_externals/checkout_externals doc-builder
+    popd 1>/dev/null
 fi
+
+echo "Running: make fetch-images"
+make fetch-images
+
+echo "Running: ./doc-builder/build_docs $@"
+./doc-builder/build_docs "$@"
+
+exit 0

doc/source/conf.py

@@ -1,8 +1,5 @@
 # -*- coding: utf-8 -*-
 #
-# clmdoc documentation build configuration file, created by
-# sphinx-quickstart on Thu Feb 23 17:14:30 2017.
-#
 # This file is execfile()d with the current directory set to its
 # containing dir.
 #
@@ -18,10 +15,15 @@
 #
 import os
 import sys
-# Note that we need a specific version of sphinx_rtd_theme. This can be obtained with:
-# pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes
 import sphinx_rtd_theme
-# sys.path.insert(0, os.path.abspath('.'))
+
+# Assumes you have substitutions.py on your path
+# pylint: disable=wrong-import-position
+dir2add = os.path.join(os.path.dirname(__file__))
+print(dir2add)
+sys.path.insert(0, dir2add)
+import substitutions as subs  # pylint: disable=import-error
+from version_list import VERSION_LIST
 
 
 # -- General configuration ------------------------------------------------
@@ -37,51 +39,43 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.imgmath',
-    'sphinx.ext.githubpages']
+    'sphinx.ext.githubpages',
+    'sphinx_mdinclude',
+    ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
 
 # The master toctree document.
-master_doc = 'index'
+source_start_file = 'index'
 
-# General information about the project.
-project = u'ctsm'
-copyright = u'2020, UCAR'
-author = u''
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = u'CLM5.0'
-# The full version, including alpha/beta/rc tags.
-release = u'release-clm5.0'
-# CTSM-specific: version label used at the top of some pages.
-version_label = 'CLM5.0 (CESM2.1)'
+# Save standard Sphinx substitution vars separately
+project = subs.project
+copyright = subs.copyright  # pylint: disable=redefined-builtin
+author = subs.author
+version = subs.version
+release = subs.release
 
 # version_label is not a standard sphinx variable, so we need some custom rst to allow
 # pages to use it. We need a separate replacement for the bolded version because it
 # doesn't work to have variable replacements within formatting.
 rst_epilog = """
 .. |version_label| replace:: {version_label}
 .. |version_label_bold| replace:: **{version_label}**
-""".format(version_label=version_label)
+""".format(version_label=subs.version_label)
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -94,8 +88,6 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-imgmath_image_format = 'svg'
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -106,15 +98,6 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
-# The 'versions' option needs to have at least two versions to work, but it doesn't need
-# to have all versions: others will be added dynamically. Note that this maps from version
-# names to html links. The current version can link to the current location (i.e., do
-# nothing). For the other version, we just add a place-holder; its name and value are
-# unimportant because these versions will get replaced dynamically.
-html_theme_options = {}
-html_theme_options['versions'] = {version: ''}
-html_theme_options['versions']['[placeholder]'] = ''
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -124,64 +107,70 @@
 
 # -- Options for HTMLHelp output ------------------------------------------
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'clmdocdoc'
+if getattr(subs, "htmlhelp", False):
+    htmlhelp_basename = subs.htmlhelp["basename"]
 
 
 # -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    'preamble': '\\usepackage{hyperref}',
-
-    'fncychap': '\\usepackage[Conny]{fncychap}',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [(master_doc, 'clmdoc.tex', u'CLM5 Documentation', '', 'manual'),]
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'clmdoc', u'clmdoc Documentation',
-     [author], 1)
-]
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, 'clmdoc', u'clmdoc Documentation',
-     author, 'clmdoc', 'One line description of project.',
-     'Miscellaneous'),
-]
-
-
-
+if getattr(subs, "latex", False):
+
+    latex_elements = {
+        # The paper size ('letterpaper' or 'a4paper').
+        #
+        # 'papersize': 'letterpaper',
+
+        # The font size ('10pt', '11pt' or '12pt').
+        #
+        # 'pointsize': '10pt',
+
+        # Additional stuff for the LaTeX preamble.
+        #
+        'preamble': '\\usepackage{hyperref}',
+
+        'fncychap': '\\usepackage[Conny]{fncychap}',
+
+        # Latex figure (float) alignment
+        #
+        # 'figure_align': 'htbp',
+    }
+
+    # Grouping the document tree into LaTeX files. List of tuples
+    # (source start file, target name, title,
+    #  author, documentclass [howto, manual, or own class]).
+    latex_documents = [(
+        source_start_file,
+        subs.latex["target_name"],
+        subs.latex["title"],
+        author,
+        subs.latex["category"],
+    )]
+
+
+# Options for manual page and Texinfo output
+if getattr(subs, "mantex", False):
+
+    # One entry per manual page. List of tuples
+    # (source start file, name, title, authors, manual section).
+    man_pages = [
+        (source_start_file, subs.mantex["name"], subs.mantex["title"], [author], 1),
+    ]
+
+    if getattr(subs, "tex", False):
+        # Grouping the document tree into Texinfo files. List of tuples
+        # (source start file, target name, title, author,
+        #  dir menu entry, description, category)
+        texinfo_documents = [(
+            source_start_file,
+            subs.mantex["name"],
+            subs.mantex["title"],
+            author,
+            subs.tex["dirmenu_entry"],
+            subs.tex["description"],
+            subs.tex["category"]),
+        ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/', None)}
 
 numfig = True
 numfig_format = {'figure': 'Figure %s',
@@ -192,4 +181,26 @@
 numfig_secnum_depth = 2
 
 def setup(app):
-    app.add_stylesheet('css/custom.css')
+    app.add_css_file('css/custom.css')
+
+try:
+    html_context
+except NameError:
+    html_context = dict()
+
+html_context["display_lower_left"] = True
+
+# Whether to show the version dropdown. If not set as environment variable, or environment variable
+# is Python-falsey, do not show it.
+version_dropdown = os.environ.get("version_dropdown")
+
+if version_dropdown:
+    html_context["current_version"] = os.environ["version_display_name"]
+
+    html_context["versions"] = []
+    pages_root = os.environ["pages_root"]
+    for this_version in VERSION_LIST:
+        html_context["versions"].append([
+            this_version.display_name,
+            os.path.join(pages_root, this_version.subdir()),
+        ])

doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst

@@ -47,9 +47,9 @@ and discharges the water to its downstream spatial unit or the ocean.
 
 .. _Figure MOSART conceptual diagram:
 
-.. figure:: mosart_diagram.png
-    :width: 800px
-    :height: 400px
+.. Figure:: mosart_diagram.png
+
+ MOSART conceptual diagram
 
 MOSART only routes positive runoff, although negative runoff can be generated
 occasionally by the land model (e.g., :math:`q_{gwl}`). Negative runoff in any

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

@@ -134,6 +134,3 @@ Example 6-1. Example of running PTCLMmkdata for US-UMB on cheyenne
 
 
 PTCLMmkdata includes a README file that gives some extra details and a simple example.
-
-.. include:: ../../../../tools/PTCLM/README
-   :literal:

doc/source/users_guide/testing/testing.rst

@@ -26,12 +26,6 @@ tests as well as lists of tests. The standard testname for CLM is "aux_clm" for
 well as the CGD machine hobart for intel, nag, and pgi compilers.  There's also a shorter test list called "clm_short". Also
 see the `CTSM Wiki on Testing <https://github.com/ESCOMP/ctsm/wiki/System-Testing-Guide>`_.
 
-CTSM Tools Testing
-==================
-
-.. include:: ../../../../test/tools/README
-   :literal:
-
 CTSM Fortran Unit Tests
 =======================
 
@@ -46,16 +40,3 @@ Run the following perl tester that
 ::
    > cd bld/unit_testers
    > ./build-namelist_test.pl
-
-
-Testing PTCLM
-=============
-
-.. include:: ../../../../tools/PTCLM/README
-   :literal:
-
-To run on cheyenne, you do the following:
-
-
-.. include:: ../../../../tools/PTCLM/test/README.run_cheyenne
-   :literal:

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

@@ -97,11 +97,6 @@ More details on each environment variable.
 
 .. 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.
 
-The *README.filecopies* (which can be found in ``$CTSMROOT/tools``) is repeated here.
-
-.. include:: ../../../../tools/README.filecopies
-   :literal:
-
 ================================================================
  Building the CLM tools that use the CIME configure/build system
 ================================================================