diff --git a/.github/ISSUE_TEMPLATE/03_documentation.md b/.github/ISSUE_TEMPLATE/03_documentation.md index 3d423ec463..782656e83c 100644 --- a/.github/ISSUE_TEMPLATE/03_documentation.md +++ b/.github/ISSUE_TEMPLATE/03_documentation.md @@ -12,8 +12,8 @@ about: Something should be added to or fixed in the documentation - [ ] Something is broken. ### What part(s) of the documentation does this concern? -- [ ] [Technical Note](https://escomp.github.io/ctsm-docs/versions/master/html/tech_note/index.html) (science and design of the model) -- [ ] [User's Guide](https://escomp.github.io/ctsm-docs/versions/master/html/users_guide/index.html) (using the model and related tools) +- [ ] [Technical Note](https://escomp.github.io/ctsm/tech_note/index.html) (science and design of the model) +- [ ] [User's Guide](https://escomp.github.io/ctsm/users_guide/index.html) (using the model and related tools) - [ ] Somewhere else (e.g., README file, tool help text, or code comment): _Please specify_ - [ ] I don't know diff --git a/.github/workflows/docs-build-and-deploy.yml b/.github/workflows/docs-build-and-deploy.yml new file mode 100644 index 0000000000..e293080a4a --- /dev/null +++ b/.github/workflows/docs-build-and-deploy.yml @@ -0,0 +1,64 @@ +name: Deploy static content to Pages + +on: + push: + # Run when a change to these files is pushed to master. + branches: ['master', 'release-clm5.0'] + paths: + - 'doc/**' + - '!doc/*ChangeLog*' + - '!doc/*ChangeSum*' + - '!doc/UpdateChangelog.pl' + # Include all include::ed files outside doc/ directory! + - 'src/README.unit_testing' + - 'tools/README' + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + + build-and-deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + # Get all history, ensuring all branches are available for checkout + fetch-depth: 0 + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Build docs using container + id: build-docs + run: | + bin/git-fleximod update -o + cd doc + ./build_docs_to_publish -d --site-root https://escomp.github.io/ctsm + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + # Upload publish dir + path: 'doc/_publish' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/docs-ctsm_pylib.yml b/.github/workflows/docs-ctsm_pylib.yml index 1e3412475f..850f58063f 100644 --- a/.github/workflows/docs-ctsm_pylib.yml +++ b/.github/workflows/docs-ctsm_pylib.yml @@ -6,11 +6,13 @@ on: branches: ['*'] paths: - 'python/conda_env_ctsm_py.txt' + - '.github/workflows/docs-common.yml' pull_request: # Run on pull requests that change the listed files paths: - 'python/conda_env_ctsm_py.txt' + - '.github/workflows/docs-common.yml' schedule: # 8 am every Monday UTC diff --git a/.github/workflows/docs-omnibus.yml b/.github/workflows/docs-omnibus.yml new file mode 100644 index 0000000000..655813c366 --- /dev/null +++ b/.github/workflows/docs-omnibus.yml @@ -0,0 +1,54 @@ +name: Run an omnibus test script for the docs + +on: + push: + # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed. + branches: ['*'] + paths: + - 'doc/**' + - '!doc/*ChangeLog*' + - '!doc/*ChangeSum*' + - '!doc/UpdateChangelog.pl' + # Include all include::ed files outside doc/ directory! + - 'src/README.unit_testing' + - 'tools/README' + + pull_request: + # Run on pull requests that change the listed files + paths: + - 'doc/**' + - '!doc/*ChangeLog*' + - '!doc/*ChangeSum*' + - '!doc/UpdateChangelog.pl' + # Include all include::ed files outside doc/ directory! + - 'src/README.unit_testing' + - 'tools/README' + + workflow_dispatch: + +jobs: + build-docs-omnibus-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + lfs: true + + - name: Checkout doc-builder external + run: | + bin/git-fleximod update doc-builder + + # Set up conda + - name: Set up conda environment + uses: conda-incubator/setup-miniconda@v3 + with: + activate-environment: ctsm_pylib + environment-file: python/conda_env_ctsm_py.yml + channels: conda-forge + auto-activate-base: false + + # TODO: Split testing.sh tests into their own steps in this job + - name: Text Sphinx builds with omnibus script + run: | + cd doc && conda run -n ctsm_pylib ./testing.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 068d75da8c..dd859acf80 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -10,6 +10,10 @@ on: - '!doc/*ChangeLog*' - '!doc/*ChangeSum*' - '!doc/UpdateChangelog.pl' + - '.github/workflows/docs-common.yml' + # Include all include::ed files outside doc/ directory! + - 'src/README.unit_testing' + - 'tools/README' pull_request: # Run on pull requests that change the listed files @@ -18,6 +22,10 @@ on: - '!doc/*ChangeLog*' - '!doc/*ChangeSum*' - '!doc/UpdateChangelog.pl' + - '.github/workflows/docs-common.yml' + # Include all include::ed files outside doc/ directory! + - 'src/README.unit_testing' + - 'tools/README' workflow_dispatch: diff --git a/.gitignore b/.gitignore index 41ab22b198..0d723b2e00 100644 --- a/.gitignore +++ b/.gitignore @@ -114,4 +114,4 @@ Depends # Docs build output _build*/ - +_publish*/ diff --git a/.gitmodules b/.gitmodules index 4de7814a55..0f6df73ea1 100644 --- a/.gitmodules +++ b/.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 = v2.0.0 +fxtag = v2.1.2 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 diff --git a/README.md b/README.md index 5e800a0b77..cca41e3473 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ http://www.cesm.ucar.edu/models/cesm2.0/land/ and -https://escomp.github.io/ctsm-docs/ +https://escomp.github.io/ctsm/ For help with how to work with CTSM in git, see diff --git a/doc/ChangeLog b/doc/ChangeLog index 2b89a435f0..03dec466b5 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,4 +1,68 @@ =============================================================== +Tag name: ctsm5.3.048 +Originator(s): samrabin (Sam Rabin, UCAR/TSS) +Date: Mon May 26 18:30:59 MDT 2025 +One-line Summary: Automatically publish docs to this repo + +Purpose and description of changes +---------------------------------- + +Enables automatic publication of documentation to this repo's GitHub Pages, making ctsm-docs repo obsolete. Also updates documentation documentation. + + +Significant changes to scientifically-supported configurations +-------------------------------------------------------------- + +Does this tag change answers significantly for any of the following physics configurations? +(Details of any changes will be given in the "Answer changes" section below.) + +[ ] clm6_0 + +[ ] clm5_0 + +[ ] ctsm5_0-nwp + +[ ] clm4_5 + + +Bugs fixed +---------- + +List of CTSM issues fixed (include CTSM Issue # and description): +- [Issue #2541: Some links in User's Guide sidebar are broken](https://github.com/ESCOMP/CTSM/issues/2541) +- [Issue #2839: Automatically publish updated docs](https://github.com/ESCOMP/CTSM/issues/2839) +- [Issue #3121: Fix capital letter in doc filenames](https://github.com/ESCOMP/CTSM/issues/3121) + +Notes of particular relevance for users +--------------------------------------- + +Changes to documentation: +- Canonical URL for User's Guide and Tech Note will be changing from https://escomp.github.io/ctsm-docs to https://escomp.github.io/ctsm. +- Updates to "Working with the CTSM documentation" section + + +Notes of particular relevance for developers: +--------------------------------------------- + +We're going to get rid of the ctsm-docs repo! + + +Testing summary: +---------------- + +None, as no code is changing aside from the documentation infrastructure, which is tested in GitHub Workflows. + +Other details +------------- + +List any git submodules updated (cime, rtm, mosart, cism, fates, etc.): +- doc-builder + +Pull Requests that document the changes (include PR ids): +- [Pull Request #3146: ctsm5.3.048: Automatically publish docs to this repo by samsrabin](https://github.com/ESCOMP/CTSM/pull/3146/files) + +=============================================================== +=============================================================== Tag name: ctsm5.3.047 Originator(s): samrabin (Sam Rabin, UCAR/TSS) Date: Mon May 26 16:30:10 MDT 2025 diff --git a/doc/ChangeSum b/doc/ChangeSum index c691363c34..c48dd71c1d 100644 --- a/doc/ChangeSum +++ b/doc/ChangeSum @@ -1,5 +1,6 @@ Tag Who Date Summary ============================================================================================================================ + ctsm5.3.048 samrabin 05/26/2025 Automatically publish docs to this repo ctsm5.3.047 samrabin 05/26/2025 Merge b4b-dev to master ctsm5.3.046 rgknox 05/26/2025 For FATES set itype to ispval and a few unused variables to nan to help prevent future problems ctsm5.3.045 glemieux 05/20/2025 FATES default parameter update for API 40 diff --git a/doc/Makefile b/doc/Makefile index 7e74b6e545..d24e5e31aa 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -6,11 +6,12 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build SPHINXPROJ = clmdoc SOURCEDIR = source +DIRWITHCONFPY = doc-builder BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" $(SPHINXOPTS) $(O) # '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 @@ -33,9 +34,9 @@ fetch-images: # # The use of $(0) is as in the catch-all target. latexpdf: - $(SPHINXBUILD) -M $@ "$(SOURCEDIR)/tech_note" "$(BUILDDIR)" -c "$(SOURCEDIR)" -D numfig_secnum_depth=1 $(SPHINXOPTS) $(O) + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)/tech_note" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" -D numfig_secnum_depth=1 $(SPHINXOPTS) $(O) # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" $(SPHINXOPTS) $(O) diff --git a/doc/__init__.py b/doc/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/build_docs_to_publish b/doc/build_docs_to_publish new file mode 100755 index 0000000000..6804311c64 --- /dev/null +++ b/doc/build_docs_to_publish @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +set -e + +script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" +if [ ! -f doc-builder/build_docs_to_publish ]; then + "${script_dir}"/../bin/git-fleximod update doc-builder +fi + +cd "${script_dir}" + +echo "Running: make fetch-images" +make fetch-images + +echo "Running: ./doc-builder/build_docs_to_publish $@" +pwd +./doc-builder/build_docs_to_publish "$@" + +exit 0 \ No newline at end of file diff --git a/doc/doc-builder b/doc/doc-builder index 9a25c4a20d..a8ddea246b 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 9a25c4a20db152f57f334c2eb86ea5246b406674 +Subproject commit a8ddea246bcffc65b053ecd9bd94c57542211982 diff --git a/doc/source/__init__.py b/doc/source/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/source/_static/css/custom.css b/doc/source/_static/css/custom.css deleted file mode 100644 index 10abb45722..0000000000 --- a/doc/source/_static/css/custom.css +++ /dev/null @@ -1,17 +0,0 @@ -/* Make equation numbers float to the right */ -.eqno { - margin-left: 5px; - float: right; -} -/* Hide the link... */ -.math .headerlink { - display: none; - visibility: hidden; -} -/* ...unless the equation is hovered */ -.math:hover .headerlink { - display: inline-block; - visibility: visible; - /* Place link in margin and keep equation number aligned with boundary */ - margin-right: -0.7em; -} diff --git a/doc/source/_templates/footer.html b/doc/source/_templates/footer.html deleted file mode 100644 index a7c22a302a..0000000000 --- a/doc/source/_templates/footer.html +++ /dev/null @@ -1,5 +0,0 @@ -{% extends "!footer.html" %} -{% block extrafooter %} - {{ super() }} - -{% endblock %} diff --git a/doc/source/conf.py b/doc/source/conf.py deleted file mode 100644 index 9678849187..0000000000 --- a/doc/source/conf.py +++ /dev/null @@ -1,201 +0,0 @@ -# -*- 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. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys -import sphinx_rtd_theme - - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.intersphinx', - 'sphinx.ext.autodoc', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - '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' - -# The master toctree document. -master_doc = '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'CTSM1' -# The full version, including alpha/beta/rc tags. -release = u'CTSM master' -# CTSM-specific: version label used at the top of some pages. -version_label = 'the latest development code' - -# List of versions to populate version picker dropdown menu -version_list = ["master", "release-clm5.0"] - -# 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) - -# 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 = "en" - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# 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. - -# 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, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'clmdocdoc' - - -# -- 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'), -] - - - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'python': ('https://docs.python.org/', None)} - -numfig = True -numfig_format = {'figure': 'Figure %s', - 'table': 'Table %s', - 'code-block': 'Code %s', - 'section': '%s', - } -numfig_secnum_depth = 2 - -def setup(app): - app.add_css_file('css/custom.css') - -try: - html_context -except NameError: - html_context = dict() - -html_context["display_lower_left"] = True - -html_context["current_language"] = language - -html_context["current_version"] = os.environ.get("current_version") - -html_context["versions"] = [] -for this_version in version_list: - # Note: with 4 pardir operators, link in version selector will be broken locally but work on the Web 🤷 - html_context["versions"].append([this_version, f"../../../../versions/{this_version}/html"]) diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index f8fe858c00..3a2520c62d 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -33,7 +33,7 @@ Developers that are making changes to CLM either for their own development or fo What is New with |version| ============================ -`What's new with |version| science `_ gives a synopsis of the changes to CLM since the CLM4.5 release. More details are given in the CLM ChangeLog files: +`What's new with |version| science `_ gives a synopsis of the changes to CLM since the CLM4.5 release. More details are given in the CLM ChangeLog files: - `CLM 3.0 ChangeLog file `_ - `CLM 4.0 ChangeLog file `_ diff --git a/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.md b/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.md deleted file mode 100644 index 738af6b8ba..0000000000 --- a/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.md +++ /dev/null @@ -1,18 +0,0 @@ -.. _building-docs-multiple-versions: - -# Building multiple versions of the documentation - -There is a menu in the lower left of the webpage that lets readers switch between different versions of the documentation. Populating this menu involves a few steps. - -First, look at the `version_list` line in `docs/conf.py`. Edit that list as needed so it contains the name of each version you want. - -Next, you will need to build the documentation once for each version. To build a version called `latest`, you would first check out the corresponding version of the docs, then do: - -```shell -cd doc -./build_docs -r $HOME/path/to/build-dir -d -v latest -``` - -This will build the documentation in `$HOME/path/to/build-dir/versions/latest`. Open `$HOME/path/to/build-dir/versions/latest/html/index.html` to see the result. - -You can also leave off the `-v latest`, in which case the current Git branch name will be used as the version name. Note, though, that in this case you will need to manually create the `$HOME/path/to/build-dir/versions/branch-name/` directory if it doesn't already exist. diff --git a/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.rst b/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.rst new file mode 100644 index 0000000000..20e9481e0a --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.rst @@ -0,0 +1,27 @@ +.. _building-docs-multiple-versions: + +Building multiple versions of the documentation +=============================================== + +There is a menu in the lower left of the webpage that lets readers switch between different versions of the documentation. To build a website with this menu properly set up—so that all our versions appear and all the links work—you need to use ``docs/build_docs_to_publish`` instead of ``docs/build_docs``. + +If you'd like to try, this will generate a local site for you in ``_publish/`` and then open it: + +.. literalinclude:: ../../../testing.sh + :start-at: ./build_docs_to_publish + :end-before: VERSION LINKS WILL NOT RESOLVE + :append: open _publish/index.html + + +How this works +-------------- + +``build_docs_to_publish`` loops through the ``VERSION_LIST`` variable in ``doc/version_list.py``: + +.. literalinclude:: ../../../version_list.py + :start-at: version of certain files we want to preserve + :end-before: End version definitions + +For each member of `VERSION_LIST`, ``build_docs_to_publish`` checks out its `ref`, then builds the documentation in a build directory. (`LATEST_REF` is set because some files, folders, and submodules are important for how the build works and need to stay the same for each build.) Once the build is complete, ``build_docs_to_publish`` should reset your local repo copy (CTSM clone) to how it was before you called ``build_docs_to_publish``. + +Next, ``build_docs_to_publish`` moves the HTML files from the build directory to the publish directory. The publish directory has a structure that matches the paths in the version dropdown menu's links. If a member of ``VERSION_LIST`` has ``landing_version=True``, its HTML will be at the top level. That makes it simple for people to find the default version of the docs at https://escomp.github.io/ctsm, rather than having to drill down further into something like ``https://escomp.github.io/ctsm/versions/latest``. diff --git a/doc/source/users_guide/working-with-documentation/building-docs-original-wiki.md b/doc/source/users_guide/working-with-documentation/building-docs-original-wiki.md index 20a739847f..251622b6f0 100644 --- a/doc/source/users_guide/working-with-documentation/building-docs-original-wiki.md +++ b/doc/source/users_guide/working-with-documentation/building-docs-original-wiki.md @@ -5,515 +5,6 @@ .. todo:: ⚠️⚠️⚠️WARNING⚠️⚠️⚠️ - This page contains documentation that (a) is more complicated than you probably require and (b) has not been fully checked for accuracy with the latest documentation setup. Unless you have a very good reason, you should probably go to :ref:`docs-intro-and-recommended`. + The linked page contains documentation that (a) is more complicated than you probably require and (b) has not been fully checked for accuracy with the latest documentation setup. Unless you have a very good reason, you should probably go to :ref:`docs-intro-and-recommended`. - -## Table of contents - -* [Intro to the CTSM documentation](#intro-to-the-ctsm-documentation) -* [What do I, as a contributor, need to do to update the tech note for my new feature?](#what-do-i-as-a-contributor-need-to-do-to-update-the-tech-note-for-my-new-feature) -* [Quick start to building the documentation](#quick-start-to-building-the-documentation) -* [Overview of the recommended build method and alternative methods](#overview-of-the-recommended-build-method-and-alternative-methods) -* [One-time setup needed for a given machine](#one-time-setup-needed-for-a-given-machine) - * [Prerequisites](#prerequisites) - * [Install Docker and download the required container](#install-docker-and-download-the-required-container) - * [Install git-lfs](#install-git-lfs) -* [Management of image files](#management-of-image-files) - * [Obtaining the image files](#obtaining-the-image-files) - * [Seeing what files are tracked by git-lfs](#seeing-what-files-are-tracked-by-git-lfs) - * [Adding a new image file type](#adding-a-new-image-file-type) -* [Procedure for building the html documentation](#procedure-for-building-the-html-documentation) - * [Recommended directory structure for these directions](#recommended-directory-structure-for-these-directions) - * [Initial steps for building the documentation](#initial-steps-for-building-the-documentation) - * [Building a test version of the documentation for your own review](#building-a-test-version-of-the-documentation-for-your-own-review) - * [Previewing the built documentation](#previewing-the-built-documentation) - * [Updating the official html documentation](#updating-the-official-html-documentation) - * [Dealing with errors](#dealing-with-errors) - * [Input/output error](#inputoutput-error) - * [Adding a new version](#adding-a-new-version) -* [Building a pdf of the tech note](#building-a-pdf-of-the-tech-note) -* [Resources for learning markup with reStructuredText and using Sphinx.](#resources-for-learning-markup-with-restructuredtext-and-using-sphinx) -* [Appendix: Other build methods](#appendix-other-build-methods) - * [Running build_docs from all of these methods](#running-build_docs-from-all-of-these-methods) - * [Relying more heavily on the Docker container](#relying-more-heavily-on-the-docker-container) - * [Launching the Docker image](#launching-the-docker-image) - * [Building the documentation](#building-the-documentation) - * [Viewing the built documentation](#viewing-the-built-documentation) - * [Committing to git repositories](#committing-to-git-repositories) - * [Installing required software on your desktop/laptop (instructions for Mac)](#installing-required-software-on-your-desktoplaptop-instructions-for-mac) - * [Prerequisites / assumptions](#prerequisites--assumptions) - * [Installing Sphinx and the necessary Sphinx theme](#installing-sphinx-and-the-necessary-sphinx-theme) - * [Installing latexmk](#installing-latexmk) - * [Optionally installing components needed to build the PDF](#optionally-installing-components-needed-to-build-the-pdf) - * [Building the documentation on cheyenne](#building-the-documentation-on-cheyenne) -* [Appendix: Editing tips](#appendix-editing-tips) - -.. _intro-to-the-ctsm-documentation: - -## Intro to the CTSM documentation - -The CTSM documentation is written using [reStructuredText markup language](http://www.sphinx-doc.org/en/stable/rest.html). ReStructuredText is a markup language, like HTML, markdown or latex. (See below for more resources on learning reStructuredText.) - -[Sphinx](http://www.sphinx-doc.org/en/stable/index.html) is a python tool for publishing reStructuredText documents in other formats such as HTML and PDF. - -The CTSM documentation source is stored in the `doc/source` directory of the main CTSM repository. The built documentation is stored in the gh-pages branch of the [ESCOMP/ctsm-docs repository](https://github.com/escomp/ctsm-docs). The Sphinx-generated HTML pages are accessible from URL [https://escomp.github.io/ctsm-docs/](https://escomp.github.io/ctsm-docs/) - -.. _what-do-i-as-a-contributor-need-to-do-to-update-the-tech-note-for-my-new-feature: - -## What do I, as a contributor, need to do to update the tech note for my new feature? - -As a contributor to CTSM, you don't necessarily need to know all of the information laid out below. If you need to update the tech note for some changes you have made, you should add or edit the necessary rst files in `doc/source/tech_note` on your CTSM branch. Then simply commit your changes to these rst files just as you would do for changes to Fortran source files, and include these rst changes in your Pull Request. Ideally these documentation changes will be on the same branch and the same Pull Request as the related source file changes, but they can also be made later, on a separate branch, and submitted to us via a separate Pull Request. In either case, the CTSM maintainers will review the documentation changes in the Pull Request and merge these changes to CTSM's master branch when ready. - -You do *not* need to open a Pull Request for the built documentation: one of the CTSM maintainers will rebuild the documentation later. However, if you have made more than minor edits to the documentation, we prefer if you have tested the documentation build to make sure there are no errors in the edited rst files and that the html documentation appears how you intended. But you do *not* need to send us or point us to your rebuilt documentation: One of the CTSM maintainers will build the documentation themselves to review the build. - -If you need to build the documentation, and/or if you need to change or add any images, you will need to keep reading for instructions on installing and using `git lfs`. - -.. _quick-start-to-building-the-documentation: - -## Quick start to building the documentation - -This documentation gives detailed explanations of a number of workflows that can be used in building the documentation. This section briefly summarizes a single, recommended workflow, so that you can get started quickly. - -First, as one-time setup, you will need to install: -- A recent version of git -- A recent version of python (python3.5 or later), available as `python3` -- [Docker](https://www.docker.com/products/docker-desktop) -- [Git LFS](https://git-lfs.github.com/), including running `git lfs install` (required if you will be adding or editing any image files, otherwise you can skip Git LFS for now) You should then launch Docker's desktop application, and run `docker pull escomp/base`. - -Then (if you haven't already done so), clone the CTSM repository (this example assumes that it appears in a path like this: `~/ctsm-repos/ctsm`). Check out the branch from which you want to build the documentation, then run `./bin/git-fleximod update --optional`. - -Then build the documentation like this: - -```shell -mkdir ~/ctsm-repos/ctsm-docs -cd ~/ctsm-repos/ctsm/doc -./build_docs -b ~/ctsm-repos/ctsm-docs -d -``` - -and view it by opening the file `~/ctsm-repos/ctsm-docs/html/index.html`. - -.. _overview-of-the-recommended-build-method-and-alternative-methods: - -## Overview of the recommended build method and alternative methods - -The directions here assume use of a documentation build method where you are working on your local desktop / laptop, and have some basic software installed there, but use a Docker container-based method for doing the actual documentation build. Other methods are documented in an [Appendix below](#appendix-other-build-methods). We prefer the Docker-based method because it avoids the complexity of installing multiple packages on your local machine, and ensures that all people building the documentation are using the same versions of Sphinx and other utilities. The main method described here leverages this Docker container while still allowing you to remain in the comfort of your own local environment. However, some people may prefer [the more Docker-centric method described in the Appendix](#relying-more-heavily-on-the-docker-container), because it has even fewer initial installation requirements. **That solution may also work more smoothly on a Windows system, though we have run the primary method successfully on Windows after ensuring that we have an executable named python3 installed.** - -.. _one-time-setup-needed-for-a-given-machine: - -## One-time setup needed for a given machine - -.. _prerequisites: - -### Prerequisites - -These instructions assume that you have the following available on your machine: - -- A recent version of git, ideally configured according to the recommendations in . - -- A recent version of python (python3.5 or later) - - Note that this must be available as `python3` (not just `python`). If your python installation did not create a `python3` command, you will need to create an alias or symbolic link so that python can be invoked via `python3`. On Windows, one developer reports success after copying `C:\Users\USERNAME\AppData\Local\Programs\Python\Python39\python.exe` to `python3.exe` (in the same location). - -.. _install-docker-and-download-the-required-container: - -### Install Docker and download the required container - -Download Docker to your personal desktop or laptop from [Docker](https://www.docker.com/products/docker-desktop) and follow the instructions. Then launch the Docker application. - -You can then obtain the necessary Docker container by running: - -```shell -docker pull escomp/base -``` - -Note: For some versions of Docker on a Mac, Docker's CPU usage can remain at 100% even after the documentation build process exits. This seems to be connected with the issue reported in . The issue probably arises because the `build_docs` script mounts your entire home directory in the docker container. You can work around this issue by quitting Docker when you are done building the docs, or by unchecking the option, "Use gRPC FUSE for file sharing" in Docker's preferences. However, note that unchecking that option might have some negative consequences, so you may want to re-enable it when you are done building the documentation if you use Docker for other purposes as well. - -.. _install-git-lfs: - -### Install git-lfs - -Git-LFS (Large File Support) is needed if you will be adding or editing any image files. **If there is even a chance that you will be doing so, it is best to go ahead and install this now, while you are thinking about it. This will prevent you from accidentally committing an image file directly to the repository, which is something we try very hard to avoid.** This is also needed for building the documentation if *not* using the Docker-based method. - -Follow the instructions on the [Git LFS page](https://git-lfs.github.com/) for installing git-lfs on your platform. (On a Mac using homebrew, this can be done with `brew install git-lfs`.) - -**Although the actual installation only needs to be done once per machine, each user who wants to use it must then run the following command to set up git-lfs for your user account on this machine:** - -```shell -git lfs install -``` - -.. _management-of-image-files: - -## Management of image files - -**If you are adding or changing any image files, be sure you have installed git-lfs according to the [above instructions](#Install-git-lfs), including running** `git lfs install`. If you are not sure whether you have already run `git lfs install`, it is safe to rerun that command to be sure. - -Image files are tracked using Git LFS (Large File Support). The images are stored somewhere on GitHub, but aren't actually part of the main repository. Instead, the repository contains small text files that direct git-lfs to the appropriate storage location on GitHub. - -For the most part, you can remain blissfully unaware of the details of how this works. For example, if you want to add a new image file to the repository, the process is just like adding any other file to the repository, as long as you have installed git-lfs. In addition, building the documentation does not require any additional steps - again, as long as you have installed git-lfs. But here are some notes that may help you: - -.. _obtaining-the-image-files: - -### Obtaining the image files - -We have configured git-lfs for CTSM so that it does *not* pull down any images by default, since these images are only rarely needed. If you have cloned CTSM or updated an existing clone and want to get the latest version of the image files, you can run: - -```shell -git lfs pull --exclude="" --include="" -``` - -Note that this is done automatically when building the documentation via the `build_docs` command, as described below. - -.. _seeing-what-files-are-tracked-by-git-lfs: - -### Seeing what files are tracked by git-lfs - -To see what file types (extensions) are tracked by git-lfs, run the following from within your CTSM clone: - -```shell -git lfs track -``` - -To see every file currently being managed by git-lfs, run the following from within your CTSM clone: - -```shell -git lfs ls-files --exclude="" --include="" -``` - -.. _adding-a-new-image-file-type: - -### Adding a new image file type - -If you want to add a new image file type, with an extension not currently being managed by git-lfs, use this process **before** adding the file to the git repository. Note that this assumes that you are in the top-level directory of your CTSM clone: - -```shell -git lfs track "*.extension" -git add .gitattributes -git commit -m "Use git-lfs for *.extension files" -``` - -Then you can check that it worked by running `git lfs track`. Finally, you can add your new file with standard `git add` and `git commit` commands. - -.. _procedure-for-building-the-html-documentation: - -## Procedure for building the html documentation - -.. _recommended-directory-structure-for-these-directions: - -### Recommended directory structure for these directions - -In order to give concrete examples, we assume a particular directory structure for these directions: We assume you have a directory in your home directory named `ctsm-repos`, and that you clone the main CTSM repository and the ctsm-docs repository inside that directory. So you will have something like: - -``` -~/ctsm-repos/ctsm -~/ctsm-repos/ctsm-docs -``` - -It's fine for your `ctsm` directory to be named something more specific, for example, including the branch name as is recommended [on the CTSM GitHub wiki](https://github.com/ESCOMP/CTSM/wiki/Quick-start-to-CTSM-development-with-git). It is also fine to use a different directory organization, but **if you are using the preferred, Docker container-based method, then both your main CTSM clone and the ctsm-docs clone must reside somewhere under your home directory.** - -.. _initial-steps-for-building-the-documentation: - -### Initial steps for building the documentation - -The following procedure assumes you have a clone of CTSM that is checked out at the branch from which you want to build documentation. - -Before building the documentation, you need to do the following: - -First, run `./bin/git-fleximod update --optional` to update your submodules; this is needed both to get `PTCLM` (which has some files referenced by the documentation build) and to get the `doc-builder` submodule that is used to do the build. **Note the use of the** `--optional` **flag here; this is needed because** `doc-builder` **is an optional submodule.** - -Next, if it's not already running, launch the Docker desktop application. - -Finally, if you haven't updated the `escomp/base` image in a while, you may want to update to the latest version with: - -```shell -docker pull escomp/base -``` - -.. _building-a-test-version-of-the-documentation-for-your-own-review: - -### Building a test version of the documentation for your own review - -If you are just building a test version of the documentation for your own review, then you don't need to do anything with the `ctsm-docs` GitHub repository. Instead, you can create a directory according to the [above recommendations for directory structure](#Recommended-directory-structure-for-these-directions). - -(However, you may want to follow a procedure similar to the one [documented below for updating the official html documentation](#Updating-the-official-html-documentation): That allows you to do an incremental build rather than building the whole documentation from scratch, which can take about 1/2 hour. You can just avoid committing and pushing when following that procedure, if all you want is to preview the documentation for your own review.) - -If you are using the [above recommendations for directory structure](#Recommended-directory-structure-for-these-directions), do the following from the `doc` directory of your ctsm clone: - -```shell -mkdir ~/ctsm-repos/ctsm-docs -./build_docs -b ~/ctsm-repos/ctsm-docs -d -``` - -(where the `-d` flag instructs `build_docs` to use the `escomp/base` Docker container to do the build). - -.. _previewing-the-built-documentation: - -### Previewing the built documentation - -You can then view your changes in a local browser window using a command like one of these: - -```shell -open ~/ctsm-repos/ctsm-docs/html/index.html -firefox ~/ctsm-repos/ctsm-docs/html/index.html -konqueror ~/ctsm-repos/ctsm-docs/html/index.html -``` - -**Note that the version dropdown menu will not work in these local previews.** - -.. _updating-the-official-html-documentation: - -### Updating the official html documentation - -If you want to update the official html documentation, follow the below procedure. (You can also use this procedure if you only intend to build a test version for your own review. This can be helpful because this procedure allows for an incremental build rather than building the entire documentation from scratch.) First clone the ctsm-docs repository to somewhere outside of your main CTSM repository. Here we'll assume that you are using the [above recommendations for directory structure](#Recommended-directory-structure-for-these-directions). - -```shell -cd ~/ctsm-repos -git clone https://github.com/ESCOMP/ctsm-docs.git -``` - -Or, if you already have a copy of ctsm-docs, make sure it is up-to-date as follows: - -```shell -cd ~/ctsm-repos/ctsm-docs -git checkout -- . -git pull -``` - -Next, `cd` to the `doc` directory of your main CTSM clone: - -```shell -cd ~/ctsm-repos/ctsm/doc -``` - -Then, to perform an incremental build (only updating files that need to be updated), run the following. **Note that the following assumes you are building the documentation for the master branch; if you are building the documentation for one of the release branches, replace** `master` **with the appropriate version.** - -```shell -./build_docs -b ~/ctsm-repos/ctsm-docs/versions/master -d -``` - -(where the `-d` flag instructs `build_docs` to use the `escomp/base` Docker container to do the build). - -However, if there have been significant changes to the documentation since the last documentation build, and you are intending to push the new build back to GitHub, it's probably best to first clean out the old build in order to remove any no-longer-relevant files. The downside of doing this is that the full documentation rebuild will take about 1/2 hour: - -```shell -./build_docs -b ~/ctsm-repos/ctsm-docs/versions/master -d -c -``` - -(where the `-c` flag instructs `build_docs` to first run `make clean` in the specified directory). - -You can preview the documentation as noted [above](#Previewing-the-built-documentation), but now the `index.html` file will be in `~/ctsm-repos/ctsm-docs/versions/master/html/index.html`. **Note that the version dropdown menu appear when you preview the documentation locally, but if you haven't built all the versions, some version links will lead to nonexistent files.** - -Then commit and push the rebuilt documentation as follows: - -```shell -cd ~/ctsm-repos/ctsm-docs -git add . -git commit -m "YOUR MESSAGE" -git push origin gh-pages -``` - -**Note if you're using a Windows machine: You may see a lot of warnings like** `warning: LF will be replaced by CRLF in path/to/some/file`. **These seem safe to ignore in this case.** - -Within a few minutes, the official documentation at [https://escomp.github.io/ctsm-docs/](https://escomp.github.io/ctsm-docs/) will be updated automatically. Note that you can also fork the ctsm-docs repository and push the gh-pages branch to your fork to allow others to preview the documentation before you overwrite the official documentation. - -.. _dealing-with-errors: - -### Dealing with errors - -.. _inputoutput-error: - -#### Input/output error - -Some people have reported an error like this: - -```shell -Exception occurred: - File "/usr/lib64/python3.6/shutil.py", line 205, in copystat - follow_symlinks=follow) -OSError: [Errno 5] Input/output error -The full traceback has been saved in /tmp/sphinx-err-hhpnw_mt.log, if you want to report the issue to the developers. -``` - -Rerunning the build command will restart it where it left off, and our experience is that that will let you complete the build - though you may need to rerun the build command a few times before it finally finishes successfully. - -.. _adding-a-new-version: - -### Adding a new version - -If you want to add a new version of the built documentation, so that it appears in the dropdown menu, follow this process: - -- In the ctsm-docs repository, create a new directory under `versions` with the name of the new version. Our convention is that this name should be the same as the name of the branch in the main CTSM repository that contains this version of the documentation source. -- In the ctsm-docs repository, add a line in the file `versions/versions.json`. Note that each line is a colon-delimited mapping; the name before the colon is the directory name (i.e., the name of the directory you just created, which is the same as the branch name in the CTSM repository), and the name after the colon is the version name that you want to appear in the dropdown menu. Make sure there is a comma at the end of every line except for the last in this file. -- In the main CTSM repository, check out the branch from which you want to build the documentation. -- In the main CTSM repository, edit the file `doc/source/conf.py`: edit the `version` and `release` variables (these should probably be the same as the version name that will appear in the dropdown menu) and anything else that needs to be changed for this release (`copyright`, etc.) -- Build the documentation as described above, being sure to specify your new directory for `BUILDDIR`. - -.. _building-a-pdf-of-the-tech-note: - -## Building a pdf of the tech note - -To build a pdf of the tech note (note that we currently do not support building a pdf of the user's guide), do the following from the `doc` directory of your CTSM clone: - -```shell -mkdir ~/ctsm-repos/ctsm-docs-pdf -./build_docs -b ~/ctsm-repos/ctsm-docs-pdf -d -t latexpdf -``` - -The pdf will appear at `~/ctsm-repos/ctsm-docs-pdf/latex/clmdoc.pdf`. - -.. _resources-for-learning-markup-with-restructuredtext-and-using-sphinx: - -## Resources for learning markup with reStructuredText and using Sphinx. - -* [reStructuredText Primer](http://www.sphinx-doc.org/en/stable/rest.html) -* [ReST Syntax](https://wiki.typo3.org/ReST_Syntax) -* [Sphinx (including how to get Sphinx)](http://www.sphinx-doc.org/en/stable/) -* [reStructured syntax](http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#tables) - -.. _appendix-other-build-methods: - -## Appendix: Other build methods - -.. _running-build_docs-from-all-of-these-methods: - -### Running build_docs from all of these methods - -With all of these alternative methods, you can still use `build_docs` commands similar to those given elsewhere in these instructions, **but without the** `-d` **argument**. - -.. _relying-more-heavily-on-the-docker-container: - -### Relying more heavily on the Docker container - -The above instructions still require you to have recent versions of python, git and git-lfs. Alternatively, you can use a method that relies more heavily on the Docker container, avoiding the need for other software to be installed. **This is a very reasonable alternative method, which some people may prefer - especially if you are already comfortable using Docker containers.** - -To start, [follow the instructions for installing Docker and downloading the required container](#Install-Docker-and-download-the-required-container). Then use the instructions below. - -.. _launching-the-docker-image: - -#### Launching the Docker image - -Assuming that both your main CTSM repository and ctsm-docs repository are cloned somewhere within your home directory, you can launch the Docker image like this: - -```shell -docker run -i -t --rm -v ${HOME}:/home/user/mounted_home escomp/base -``` - -This tells docker to *run* the container (`docker run`), interactively (`-i`) with a terminal (`-t`), to clean up the container after running (`--rm`), and most importantly, to map your local `${HOME}` directory into the `/home/user/mounted_home` directory inside the container (`-v ${HOME}:/home/user/mounted_home`). - -After running this command, you will see a command prompt, but now you will be in the Docker environment. This means: -- You will be able to see directories and files contained in your local `${HOME}` directory, but nothing else. `${HOME}/mounted_home` in the Docker environment refers to `${HOME}` in your native system environment. Changed or added files here will be visible in your native system, in the appropriate subdirectory of your `${HOME}` directory. This will become important later in these directions, since you will view the generated documentation from your native environment. -- Any commands you run from this environment will use the commands bundled with the Docker image, *not* the commands in your native system environment. - -When you are done using this Docker image, simply type `exit` from the command prompt. - -For far more information on running Docker containers, you can look at [Docker's documentation](https://docs.docker.com/engine/reference/run/). - -.. _building-the-documentation: - -#### Building the documentation - -You can use `build_docs` commands like those given elsewhere in these instructions, **but without the** `-d` **argument** (the `-d` argument launches a new Docker image, but in this case, you are already inside a Docker image, so this is unnecessary). Keep in mind that you will need to specify the path to the documentation build directory according to the Docker file system, not your native file system. - -.. _viewing-the-built-documentation: - -#### Viewing the built documentation - -You can view the built documentation [as described above](#Previewing-the-built-documentation). However, in order to find the `index.html` file, keep in mind the mapping between directories in Docker's environment and those in your native environment. - -.. _committing-to-git-repositories: - -#### Committing to git repositories - -Any local git configuration information is *not* picked up by the Docker image. Therefore, if you want to make any git commits from the Docker terminal session, you will need to do one of the following: -- After doing the `docker run` command as above, copy `/home/user/mounted_home/.gitconfig` to `/home/user/.gitconfig`. -- Or run the `git config` command to set your name and email, as described [here](https://github.com/ESCOMP/CTSM/wiki/Recommended-git-setup#required-settings) - -.. _installing-required-software-on-your-desktoplaptop-instructions-for-mac: - -### Installing required software on your desktop/laptop (instructions for Mac) - -If you choose not to use the Docker-based method described above, you can instead install Sphinx and some related packages locally. **We do not recommend this method, because it can be more challenging to set up and maintain than the method described above. In addition, the instructions here are not regularly tested, so may no longer work. Finally, the use of this method can mean that your Sphinx version differs from the one used to generate the official documentation, which can potentially cause problems.** However, if you cannot use the Docker method for some reason, then you can try this alternative. - -.. _prerequisites--assumptions: - -#### Prerequisites / assumptions - -The following documentation assumes that you have the following available on your machine: - -- A recent version of git, ideally configured according to the recommendations in . - -- A recent version of python (python3.5 or later) - -- If using a Mac, the [Homebrew package manager](https://brew.sh/) - -.. _installing-sphinx-and-the-necessary-sphinx-theme: - -#### Installing Sphinx and the necessary Sphinx theme - -Sphinx and the necessary Sphinx theme are python packages that can be installed with `pip install`: - -```shell -pip install sphinx -pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes -``` - -For more details on installing Sphinx, see the [Sphinx installation docs](http://www.sphinx-doc.org/en/stable/install.html). - -*You may then need to update your PATH environment variable to include the path to the* `sphinx-build` *script.* - -.. _installing-latexmk: - -#### Installing latexmk - -`latexmk` is needed both for building the PDF and for creating the equations in the html documentation. On a Mac using homebrew, this can be installed with: - -```shell -brew cask install mactex -``` - -Note that you will need to open a new terminal window for the latexmk tool to be added to your path (it is in `/Library/TeX/texbin/latexmk`, which should have been added to your path by the above `brew` command). - -.. _optionally-installing-components-needed-to-build-the-pdf: - -#### Optionally installing components needed to build the PDF - -If you want to build the PDF (not just the html web pages), you *may* also need rst2pdf. This can be installed with: - -```shell -pip install rst2pdf -``` - -.. _building-the-documentation-on-cheyenne: - -### Building the documentation on cheyenne - -Finally, although we haven't figured out a way to view the built documentation on cheyenne, you can test the build there, and then transfer the files to your local machine for viewing. - -To do so, first ensure that you are using the `git` and `python` modules on cheyenne rather than the default system versions, by doing `module load git` and `module load python`. (Note that the default git module has `git lfs` bundled with it.) - -Then, the first time you build the documentation, do this one-time setup: - -```shell -pip install --user sphinx -pip install --user sphinxcontrib-programoutput -pip install --user git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes -``` - -and add the following to your `.bashrc` or similar file if using bash: - -```bash -export PATH=/glade/u/home/$USER/.local/bin:$PATH -``` - -or, if you're using tcsh, add to your `.tcshrc`: - -```tcsh -setenv PATH /glade/u/home/$USER/.local/bin:$PATH -``` - -.. _appendix-editing-tips: - -## Appendix: Editing tips -- Please don't add manual line breaks when writing text, as this harms searchability. (Note that it's fine to do this in multi-line `:math:` blocks.) For more information, see [text-linebreaks](https://github.com/ESCOMP/CTSM/issues/2135#issuecomment-1764999337). -- You can write the degree symbol ° with Opt-Shift-8 on Mac or Alt+0176 on Windows. Note that this is different from the [masculine ordinal indicator](https://en.wikipedia.org/wiki/Ordinal_indicator) º (typed with Opt-0 on Mac). This is much cleaner and more searchable than using RestructuredText syntax to write a superscript-o! -- Whenever possible, please give equations meaningful labels. E.g., for [eq. 2.26.2](https://escomp.github.io/ctsm-docs/versions/release-clm5.0/html/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.html#equation-25-2), `:label: gdds_for_cfts`) instead of numbers (`:label: 25.2`). Numeric labels become obsolete—as you can see in that example!—whenever new equations and/or sections are added. (Note that the equation numbering in the rendered HTML is automatic.) -- Tables defined with the [`:table:` directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#table) can be annoying because they're very sensitive to the cells inside them being precisely the right widths, as defined by the first `====` strings. If you don't get the widths right, you'll see "Text in column margin" errors. Instead, define your tables using the [`:list-table:`](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) directive. \ No newline at end of file +If you're really sure you want to look at the old documentation instructions, they are preserved [here](https://github.com/ESCOMP/CTSM/wiki/Directions-for-editing-CLM-documentation-on-github-and-sphinx/af29e2b37c07581a8ebacaa49e7a9b0ecf6bb7f3). diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-mac.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-mac.md new file mode 100644 index 0000000000..45a1f2bb96 --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-mac.md @@ -0,0 +1,103 @@ +.. _building-docs-prereqs-docker-mac: + +# Initial setup: Mac + +Note that you may need administrator privileges on your Mac for the installation steps detailed here. + +.. _building-docs-git-tools: + +## Python +To test whether you already have the required Python version, open a Terminal window and try the following: +```shell +python3 --version +``` + +If python3 is already set up, you'll see a version number. If that version is 3.7 or later, you should be ready as far as Python goes; continue to :ref:`docs-git-tools`. + +If not, recent versions of macOS should print a messsage saying, "xcode-select: No developer tools were found, requesting install." A dialog box will then pop up that says, "The 'python3' command requires the command line developer tools. Would you like to install the tools now?" Press Install and go through the installation process. This will take a while; once it's done, test by doing ``python3 --version`` again. (You may need to open a new Terminal window.) If the printed version number looks good, continue to :ref:`docs-git-tools`. + +.. + The paragraph above was tested 2025-04-25 on a fresh-ish installation of macOS 15.3.2. + +If instead `python3` gives "command not found," or the version is less than 3.7, you might need to install Python; continue to :ref:`aliasing-python3-to-python`. + +.. _aliasing-python3-to-python: + +### Aliasing `python3` to `python` +Try the same command as above, but instead of `python3` just do `python` (no number). If that version is 3.7 or later, you can tell your Mac that when you say `python3` you want it to use `python`: +```bash +echo alias python3="$(which python)" >> ~/.bashrc +echo alias python3="$(which python)" >> ~/.zshrc +``` + +This will make it so that bash scripts, like what we use to build our docs, know what to do for `python3`. `python3` will also be available in new Terminal sessions if your shell is `zsh` (the default since macOS 10.15) or `bash`. + +If you were able to do this, you can continue to :ref:`docs-git-tools`. + +### Conda +If your `python` doesn't exist or is too old, we suggest using Python via Conda. First, check whether you already have Conda installed: +```shell +conda env list +``` + +If that shows you something like +``` +# conda environments: +# +base /Users/you/... +another_env /Users/you/.../... +... +``` + +instead of the "command not found" error, then you do have conda installed! (Note that the second column doesn't really matter.) Try this to check the Python version in the `base` Conda environment: +```shell +conda run -n base python3 --version +``` + +Repeat with all your Conda environments as needed until you find one that's Python 3.7 or later. Let's say your `ENVNAME` environment works. In that case, just make sure to do `conda activate ENVNAME` before running the commands in the documentation-building instructions. + +If you don't have Conda yet, go on to the next section. Otherwise, continue to :ref:`docs-git-tools`. + +.. _installing-conda-for-docs: + +### Installing Conda +We suggest installing Conda, if needed, via Miniforge: + +1. [Download Miniforge](https://conda-forge.org/download/) and install it. (:ref:`what-kind-of-mac-chip`) You can also [install Miniforge via Homebrew](https://formulae.brew.sh/cask/miniforge#default), if you already have that installed. +2. Activate Conda permanently in your shell by opening a new Terminal window and doing `conda init "$(basename $SHELL)"`. + +You should now have `conda` and an up-to-date version of `python3` available, although will need to open another new Terminal window for it to work. + +## Additional requirements +The remaining software you need to install depends on which documentation-building method(s) you plan to use. + +### Docker (recommended) +Install Docker Desktop through the [download page on Docker's website](https://docs.docker.com/desktop/setup/install/mac-install/). (:ref:`what-kind-of-mac-chip`) + +### Non-Docker method + +Install Conda, if needed (see :ref:`installing-conda-for-docs`). Then follow the instructions for setting up the `ctsm_pylib` Conda environment in Sect. :numref:`using-ctsm-pylib`. + +.. _docs-git-tools: + +## Git tools +Note: Do this section after handling Python, because the Python installation process might bring the Git tools with it. + +To test whether you have the required Git tools already, open a Terminal window and try the following: +```shell +git --version +git-lfs --version +``` + +If either of those fail with "command not found," you'll need to install them. The recommended way is with [Homebrew](https://brew.sh/). + +1. [Install Homebrew](https://brew.sh/), if needed. (Check using `brew --version`.) Make sure to follow the instructions for adding Homebrew to your path. (:ref:`what-kind-of-mac-chip`) +2. Use Homebrew to [install Git](https://formulae.brew.sh/formula/git#default), if needed. +3. Use Homebrew to [install Git LFS](https://formulae.brew.sh/formula/git-lfs#default), if needed. + +## Frequently-asked questions + +.. _what-kind-of-mac-chip: + +### What kind of chip does my Mac have? +For certain steps in this installation process, you may need to know whether your Mac has an Intel (`x86_64`) or an Apple Silicon (`arm64`) chip. If you don't know, visit Apple's [Mac computers with Apple silicon](https://support.apple.com/en-us/116943) page for instructions. \ No newline at end of file diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-windows.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-windows.md new file mode 100644 index 0000000000..10e62c1220 --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-windows.md @@ -0,0 +1,22 @@ +.. _building-docs-prereqs-docker-windows: + +# Initial setup: Windows + +Note that you may need administrator privileges on your PC (or approval from your IT department) for various steps here. + +## Linux subsystem + +We don't support building our documentation in the native Windows command-line environment. Thus, you will need to install a little version of Linux to use instead. + +The first step is to install Windows Subsystem for Linux (WSL), if you haven't already: + +1. Download and install it from the Microsoft Store. +1. Restart your computer. + +Next, download and install Ubuntu (a version of Linux) via the Microsoft Store. + +Finally, try opening Ubuntu. If you run into an error, you may need to manually enable WSL. To do so: Open Control Panel, go to "Programs and Features," and then "Turn Windows features on or off." Check the box next to "Windows Subsystem for Linux" and click OK. + +## Docker Desktop +1. Install Docker Desktop through the Microsoft Store or the [download page on Docker's website](https://docs.docker.com/desktop/setup/install/windows-install/). +1. Open Docker Desktop. In Settings > Resources > WSL, Enable Docker to work under Ubuntu. diff --git a/doc/source/users_guide/working-with-documentation/caveats-for-working-with-markdown.md b/doc/source/users_guide/working-with-documentation/caveats-for-working-with-markdown.md deleted file mode 100644 index 843e0630f4..0000000000 --- a/doc/source/users_guide/working-with-documentation/caveats-for-working-with-markdown.md +++ /dev/null @@ -1,26 +0,0 @@ -.. _caveats-for-working-with-markdown: - -# Caveats for working with Markdown - -.. _cross-references: - -## Cross-references -You can [link to section headings](#cross-references) with the `[link to section headings](#cross-references)` format, but the Sphinx compiler will complain. To fix that, you will need to also add a reStructuredText label like `.. _cross-references:` above the heading, with blank lines before and after it. This rST label will appear if you render the .md file as pure Markdown (e.g., in VSCode's Markdown preview pane), but it will be invisible on the final generated webpage. - -If you forget to surround the label with blank lines, you will get errors like "Explicit markup ends without a blank line; unexpected unindent [docutils]" that often point to lines far away from the actual problem. - -## Inline math -(Note that parts of this section will be rendered incorrectly by Markdown parsers!) - -Inline math can't be achieved with the typical Markdown syntax of just surrounding your expression with dollar signs. Instead, you need to surround THAT with backticks. So to render `$y = mx + b$`, we can't do -``` -So to render $y = mx + b$, ... -``` -because we'd just see $y = mx + b$ on the generated webpage. Instead, we do -``` -So to render `$y = mx + b$`, ... -``` -We could also use rST's syntax like so: -``` -So to render :math:`y = mx + b`, ... -``` \ No newline at end of file diff --git a/doc/source/users_guide/working-with-documentation/docs-intro-and-recommended.md b/doc/source/users_guide/working-with-documentation/docs-intro-and-recommended.md index 04fac2b164..e74290f8e3 100644 --- a/doc/source/users_guide/working-with-documentation/docs-intro-and-recommended.md +++ b/doc/source/users_guide/working-with-documentation/docs-intro-and-recommended.md @@ -1,13 +1,16 @@ .. _docs-intro-and-recommended: -# Introduction to working with the CTSM documentation - -## Documentation source files -The CTSM documentation is built from files in the `doc/source/tech_note/` and `doc/source/users_guide/` directories. These files are written in a mixture of what are called "markup languages." You may already be familiar—for better or for worse—with the LaTeX markup language. Fortunately, our documentation is simpler than that. It was originally written entirely in [reStructuredText](http://www.sphinx-doc.org/en/stable/rest.html), and it still mostly is, as you can tell by the predominance of .rst files. However, it's also possible to write Markdown documents (.md), which is nice because it's a much simpler and more widespread format (although see :ref:`caveats-for-working-with-markdown`). If you've formatted text on GitHub, for instance, you've used Markdown. - +# Working with the CTSM documentation .. _editing-the-documentation: +## One-time setup +In addition to a CTSM checkout in which to work, you will need to have some software installed in order to build the documentation: +- :ref:`building-docs-prereqs-docker-mac` +- :ref:`building-docs-prereqs-docker-windows` + ## Editing the documentation +The CTSM documentation is built from files in the `doc/source/tech_note/` and `doc/source/users_guide/` directories. These files are written in a mixture of what are called "markup languages." You may already be familiar—for better or for worse—with the LaTeX markup language. Fortunately, our documentation is simpler than that. It was originally written entirely in [reStructuredText](http://www.sphinx-doc.org/en/stable/rest.html), and it still mostly is, as you can tell by the predominance of .rst files. However, it's also possible to write Markdown documents (.md), which is nice because it's a much simpler and more widespread format (although see :ref:`tips-for-working-with-markdown`). If you've formatted text on GitHub, for instance, you've used Markdown. + Editing the documentation is as simple as opening the source file for the page you want to edit, then changing text. Make sure to use either reStructuredText or Markdown syntax, depending on the file's extension (.rst or .md, respectively). If you're confident in your changes, or you're _not_ confident in your ability to preview and test the documentation (see [Building the documentation (recommended method)](#building-the-documentation-recommended-method) below), all you need to do is commit your changes and submit a pull request to the [CTSM GitHub repo](https://github.com/ESCOMP/CTSM). Automated testing will check the updated documentation for any errors, and a CTSM software engineer will review your PR. If everything looks good, they will merge it into the codebase and update the website. @@ -17,19 +20,16 @@ If you're confident in your changes, or you're _not_ confident in your ability t ## Building the documentation (recommended method) We strongly suggest building the documentation on your personal computer before submitting a pull request, so that you can preview what your changes will look like. The recommended way to do this is using the `doc-builder` tool in conjunction with a "containerized" version of some required software. -### Required software -You will need [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), [Git LFS](https://git-lfs.com/), and [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed on your machine. In addition, you will need a decently modern installation of Python available from the command line as `python3`. We test the most with Python 3.13.2 (available in the `ctsm_pylib` conda environment; see :ref:`using-ctsm-pylib`), but any version 3.7 or later should work (and maybe earlier). You can do `python3 --version` on the command line to check your version. - ### Directories -You will need a place to build the documentation. It's fine if that doesn't exist; the build tool will make it for you. Alternatively, you can clone the [ctsm-docs](https://github.com/ESCOMP/ctsm-docs) repository and build there. The only restriction is that, at least for the recommended method described here, **your build directory must be somewhere in your user home directory**, which we represent as `$HOME`. The instructions here assume you want to do your build in `$HOME/path/to/build-dir/`. +You will need a place to build the documentation. It's fine if that doesn't exist; the build tool will make it for you. The only restriction is that, at least for the recommended method described here, **your build directory must be somewhere in your user home directory**, which we represent as `$HOME`. The instructions here assume you want to do your build in `$HOME/path/to/build-dir/`. Your CTSM clone, from which you're building the documentation, also needs to be somewhere in your user home directory. ### Building a preview -Ensure that Docker Desktop is running. Then all you need to do is +Ensure that Docker Desktop is running. (You do not actually need to do anything in Docker Desktop; it just needs to be running. It's fine for it to be minimized or hidden.) Then all you need to do is ```shell cd doc -./build_docs -b $HOME/path/to/build-dir -d +./build_docs -b $HOME/path/to/build-dir -c -d ``` (Do `./build_docs --help` for more information and options.) @@ -37,6 +37,3 @@ cd doc You can then open the documentation in a web browser by browsing to `$HOME/path/to/build-dir/html/` and opening `index.html`. Note that there is a menu in the lower left of the webpage that lets readers switch between different versions of the documentation. The links to versions in this menu will not work when using the build command given above. If you wish to preview this version switching functionality, or you're building the docs in the process of actually updating the website, see :ref:`building-docs-multiple-versions`. - -## Further reading -More complicated instructions and alternative methods for building the documentation can be found in :ref:`overview-of-the-recommended-build-method-and-alternative-methods`. diff --git a/doc/source/users_guide/working-with-documentation/index.rst b/doc/source/users_guide/working-with-documentation/index.rst index 383fa52e80..fec10dc4c9 100644 --- a/doc/source/users_guide/working-with-documentation/index.rst +++ b/doc/source/users_guide/working-with-documentation/index.rst @@ -7,10 +7,13 @@ Working with CTSM Documentation ####################################### .. toctree:: - :maxdepth: 2 + :maxdepth: 1 docs-intro-and-recommended.md - building-docs-multiple-versions.md - caveats-for-working-with-markdown.md + building-docs-prereqs-docker-mac.md + building-docs-prereqs-docker-windows.md + building-docs-multiple-versions.rst + tips-for-working-with-markdown.md + tips-for-working-with-rst.md building-docs-original-wiki.md diff --git a/doc/source/users_guide/working-with-documentation/tips-for-working-with-markdown.md b/doc/source/users_guide/working-with-documentation/tips-for-working-with-markdown.md new file mode 100644 index 0000000000..9575092459 --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/tips-for-working-with-markdown.md @@ -0,0 +1,45 @@ +.. _tips-for-working-with-markdown: + +# Tips for working with Markdown + +Markdown is great for very simple documentation files—it's much easier to write and read Markdown source than reStructuredText source. However, there are some compromises that you should be aware of, and you may find yourself needing to mix in some reStructuredText. + +.. _md-cross-references: + +## Markdown: Cross-references +You can [link to section headings](#md-cross-references) with the `[link to section headings](#md-cross-references)` format, but the Sphinx compiler will complain. Instead, use the :ref:`reStructuredText cross-reference and label` syntax. + +## Markdown: Math +(Note that parts of this section will be rendered incorrectly by Markdown parsers!) + +Inline math can't be achieved with the typical Markdown syntax of just surrounding your expression with dollar signs. Instead, you need to surround THAT with backticks. So to render `$y = mx + b$`, we can't do +``` +So to render $y = mx + b$, ... +``` +because we'd just see $y = mx + b$ on the generated webpage. Instead, we do +``` +So to render `$y = mx + b$`, ... +``` +We could also use :ref:`rST's syntax` like so: +``` +So to render :math:`y = mx + b`, ... +``` + +You can also use Markdown's math block syntax for big equations on their own lines: +``` +$$ +y = mx + b +$$ +``` +$$ +y = mx + b +$$ + +However, you won't get the equation numbering or labeling that you would with the :ref:`reStructuredText math format`. + +## Markdown: Comments +If you want to add some text that's only visible in the documentation source file, there's not really a way to do that in Markdown. However, you can use the :ref:`reStructuredText comment syntax` in a Markdown document. + +## Markdown: Tables + +Markdown tables are supported. See [GitHub's "Organizing information with tables"](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables) for more info. \ No newline at end of file diff --git a/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.md b/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.md new file mode 100644 index 0000000000..2dcc7f455e --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.md @@ -0,0 +1,82 @@ +.. _tips-for-working-with-rst: + +# Tips for working with reStructuredText + +.. _rst-math: + +## reStructuredText: Math +You can write inline math like ``:math:`y = mx + b``` → :math:`y = mx + b`. You can also write bigger equations on their own line that will automatically be numbered: + +```reStructuredText +.. math:: + :label: equation for a line + + y = mx + b +``` +.. math:: + :label: equation for a line + + y = mx + b + +Note (a) the leading spaces for each line after `.. math::` and (b) the empty line after the label. If you don't include the `:label:` line, the equation will not be numbered. + +reStructuredText math largely follows LaTeX syntax. + +Common errors: +- 'ERROR: Error in "math" directive: invalid option block': You might have forgotten the empty line after your equation label. +- "WARNING: Explicit markup ends without a blank line; unexpected unindent": You might have forgotten the leading spaces for every line after `.. math::`. You need at least one leading space on each line. + +.. _rst-cross-references: + +## reStructuredText: Cross-references +reStructuredText lets you define labels that can be cross-referenced as links elsewhere in the documentation. A label looks like ``.. _this-is-my-label:`` or ``.. _This is my label with CAPS and spaces:``, on its own line surrounded by blank lines. The leading ``.. _`` and trailing ``:`` are what tell rST "this line is a label." E.g.: + +``` +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + +.. _this-is-my-label: + +My cool information +^^^^^^^^^^^^^^^^^^^ +Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +``` + +You could then refer to that section with ``:XYZ:`this-is-my-label``` (leaving off the leading `.. _`), where `XYZ` can be `ref`, `numref`, or `eq` (see examples below). This will create a link that, when clicked, takes the reader to the "My cool information" section. + +Here are some examples. Note that the displayed link text will update automatically as needed (e.g., a section number or figure caption gets changed). +- Section headings, text: ``:ref:`rst-cross-references``` → :ref:`rst-cross-references` +- Section headings, number: ``:numref:`rst-cross-references``` → :numref:`rst-cross-references`. Note that, unlike `numref` for other things mentioned here, "Section" is not automatically prepended to the section number in the link text. +- Table, text: ``:ref:`Table Crop plant functional types``` → :ref:`Table Crop plant functional types` +- Table, number: ``:numref:`Table Crop plant functional types``` → :numref:`Table Crop plant functional types` +- Figure, text (uses entire caption): ``:ref:`Figure CLM subgrid hierarchy``` → :ref:`Figure CLM subgrid hierarchy` +- Figure, number: ``:numref:`Figure CLM subgrid hierarchy``` → :numref:`Figure CLM subgrid hierarchy` +- Equation, number: ``:eq:`equation for a line``` → :eq:`equation for a line`. The parentheses in the link text seem unavoidable, and there seems to be no way to refer to have the link show the label text or anything else aside from the number. + +You can have any link (except for equations) show custom text by putting the referenced label at the end in ``. E.g., ``:ref:`Diagram of CLM subgrid hierarchy
``` → :ref:`Diagram of CLM subgrid hierarchy
`. + +Note that this is necessary for labels that aren't immediately followed by a section heading, a table with a caption, or a figure with a caption. For instance, to refer to labels in our bibliography, you could do ``:ref:`(Bonan, 1996)``` → :ref:`(Bonan, 1996)`. + +Common errors: +- "WARNING: Failed to create a cross reference. A title or caption not found": This probably means you tried to `:ref:` a label that's not immediately followed by (a) a table/figure with a caption or section or (b) a section (see above). +- "WARNING: undefined label": If you're sure the label you referenced actually exists, this probably means you tried to ``:numref:`` a label that's not immediately followed by a table, figure, or section (see above). Alternatively, you might have tried to ``:ref:`` an :ref:`equation`; in that case, use ``:eq:`` instead. +- "WARNING: malformed hyperlink target": You may have forgotten the trailing `:` on a label line. +- If you forget to surround a label with blank lines, you will get errors like "Explicit markup ends without a blank line; unexpected unindent [docutils]" that often point to lines far away from the actual problem. + +.. _rst-comments: + +## reStructuredText: Comments +If you want to add some text that's only visible in the documentation source file, you can use the reStructuredText comment syntax: + +``` +.. + This will not appear on the webpage or even anywhere in the generated HTML. + +``` + +Make sure to include at least one empty line after the comment text. + + +## reStructuredText: Tables +Tables defined with the [:table: directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#table) can be annoying because they're very sensitive to the cells inside them being precisely the right widths, as defined by the first `====` strings. If you don't get the widths right, you'll see "Text in column margin" errors. Instead, define your tables using the [list-table](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) directive. + +If you already have a table in some other format, like comma-separated values (CSV), you may want to check out the R package [knitr](https://cran.r-project.org/web/packages/knitr/index.html). Its [kable](https://bookdown.org/yihui/rmarkdown-cookbook/kable.html) command allows automatic conversion of R dataframes to tables in reStructuredText and other formats. diff --git a/doc/substitutions.py b/doc/substitutions.py new file mode 100644 index 0000000000..29b6fb54de --- /dev/null +++ b/doc/substitutions.py @@ -0,0 +1,63 @@ +""" +Substitutions for Sphinx +""" + +# 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. + +# pylint: disable=invalid-name + +################################# +### Standard Sphinx variables ### +################################# + +# General information about the project. +project = "ctsm" +copyright = "2020, UCAR" # pylint: disable=redefined-builtin +author = "" + +# The short X.Y version. +version = "CTSM1" + +# The full version, including alpha/beta/rc tags. +release = "CTSM master" + +##################################################### +### Custom variables needed for doc-builder setup ### +##################################################### + +# Version label used at the top of some pages. +version_label = "the latest development code" + +####################################################### +### Custom variables optional for doc-builder setup ### +####################################################### + +tex_category = "Miscellaneous" + +# Used by HTML help builder +htmlhelp = { + "basename": "clmdocdoc", # Output file base name +} + +# Used for LaTeX output +latex = { + "target_name": "clmdoc.tex", + "title": "CLM Documentation", + "documentclass": "manual", # howto, manual, or own class + "category": tex_category, +} + +# Used for man_pages and texinfo_documents +mantex = { + "name": "clmdoc", + "title": "clmdoc Documentation", +} + +# Used for texinfo_documents +tex = { + "dirmenu_entry": "clmdoc", + "description": "One line description of project.", + "category": tex_category, +} \ No newline at end of file diff --git a/doc/testing.sh b/doc/testing.sh new file mode 100755 index 0000000000..9d39955fe4 --- /dev/null +++ b/doc/testing.sh @@ -0,0 +1,52 @@ +#!/bin/bash +set -e +set -x + +rm -rf _publish* + +# Build all docs using container +echo "~~~~~ Build all docs using container" +# Also do a custom --conf-py-path +rm -rf _build _publish +d1="$PWD/_publish_container" +./build_docs_to_publish -r _build -d --site-root "$PWD/_publish" +# VERSION LINKS WILL NOT RESOLVE IN _publish_container +cp -a _publish "${d1}" + +# Build all docs using ctsm_pylib +echo "~~~~~ Build all docs using ctsm_pylib" +rm -rf _build _publish +d2="$PWD/_publish_nocontainer" +conda run -n ctsm_pylib ./build_docs_to_publish -r _build --site-root "$PWD/_publish" --conf-py-path doc-builder/test/conf.py --static-path ../_static --templates-path ../_templates +# VERSION LINKS WILL NOT RESOLVE IN _publish_nocontainer +cp -a _publish "${d2}" + +# Make sure container version is identical to no-container version +echo "~~~~~ Make sure container version is identical to no-container version" +diff -qr "${d1}" "${d2}" + +# Check that -r -v works +echo "~~~~~ Check that -r -v works" +# Also do a custom --conf-py-path +rm -rf _build_docker +./build_docs -r _build_docker -v latest -d -c --conf-py-path doc-builder/test/conf.py --static-path ../_static --templates-path ../_templates + +# Check that Makefile method works +echo "~~~~~ Check that Makefile method works" +rm -rf _build +make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build html + +# Check that -b works +echo "~~~~~ Check that -b works" +rm -rf _build_docker +./build_docs -b _build_docker -d -c + +# Check that doc-builder tests pass +# Don't run if on a GitHub runner; failing 🤷. Trust that doc-builder does this test. +if [[ "${GITHUB_ACTION}" == "" ]]; then + echo "~~~~~ Check that doc-builder tests pass" + cd doc-builder/test + conda run -n ctsm_pylib make test +fi + +exit 0 \ No newline at end of file diff --git a/doc/version_list.py b/doc/version_list.py new file mode 100644 index 0000000000..56610c3018 --- /dev/null +++ b/doc/version_list.py @@ -0,0 +1,31 @@ +""" +Define the versions we want to build +""" +import sys +import os +dir2add = os.path.join(os.path.dirname(__file__), "doc-builder") +if not os.path.exists(dir2add): + raise FileNotFoundError(dir2add) +sys.path.insert(0, dir2add) +# pylint: disable=wrong-import-position +from doc_builder.docs_version import DocsVersion # pylint: disable=import-error,no-name-in-module +from doc_builder.sys_utils import get_git_head_or_branch # pylint: disable=import-error,no-name-in-module + +# Branch name, tag, or commit SHA whose version of certain files we want to preserve +LATEST_REF = get_git_head_or_branch() + +# List of version definitions +VERSION_LIST = [ + DocsVersion( + short_name="latest", + display_name="Latest development code", + landing_version=True, + ref=LATEST_REF, + ), + DocsVersion( + short_name="release-clm5.0", + display_name="CLM5.0", + ref="release-clm5.0", + ), +] +# End version definitions (keep this comment; Sphinx is looking for it)