From 16c688f5d8c1d66d91641d6f329f7454a9f7018c Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 2 Apr 2026 13:30:11 -0600 Subject: [PATCH 01/17] Docs docs: Move "One-time setup" section. --- doc/doc-builder | 2 +- .../docs-intro-and-recommended.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/doc-builder b/doc/doc-builder index 3ab6d06971..6c7f2b1d1f 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 3ab6d06971e508f2886f0079db37156ab93c2b07 +Subproject commit 6c7f2b1d1fbf1766c32fe1f6221098194ea62c8a 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 bfc537f223..3c01a98eea 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 @@ -3,11 +3,6 @@ # Working with the CTSM documentation .. _editing-the-documentation: -## One-time setup -You will need to have some software installed on your computer in order to build and the documentation and view the results: -- :ref:`building-docs-prereqs-mac` -- :ref:`building-docs-prereqs-windows` - ## Editing the documentation First, you will need a clone of CTSM to get all the documentation files and infrastructure. (If you're on Windows, you will make this clone in your :ref:`Ubuntu VM `.) Note that you will clone this to your own computer, not Derecho or any cluster or anything. @@ -25,6 +20,11 @@ We strongly suggest building the documentation on your personal computer before ### 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. The only restriction is that, at least for the recommended method described here, **your build directory must be somewhere in your CTSM clone**. (We recommend starting the name of your build directory with `_build` because CTSM knows to ignore such directories when it comes to `git`.) The instructions here assume you want to do your build in `doc/_build/`. +### One-time setup +You will need to have some software installed on your computer in order to build and the documentation and view the results: +- :ref:`building-docs-prereqs-mac` +- :ref:`building-docs-prereqs-windows` + ### Building the docs All you need to do to build the docs with our recommended method is ```shell From b226df93ff956be00834450e2901ac283ce4296a Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 2 Apr 2026 14:31:36 -0600 Subject: [PATCH 02/17] Update doc-builder: Add fallback for container build on Casper. --- .gitmodules | 2 +- doc/doc-builder | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitmodules b/.gitmodules index 434c985738..bba741bac2 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.2.6 +fxtag = v2.2.7 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/doc/doc-builder b/doc/doc-builder index 6c7f2b1d1f..e03ff5e22e 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 6c7f2b1d1fbf1766c32fe1f6221098194ea62c8a +Subproject commit e03ff5e22eba68fe6682b3b9de30bd6ee633ebd5 From 3bf635bebccc96721900fd490e788ec119f07124 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 2 Apr 2026 16:43:01 -0600 Subject: [PATCH 03/17] docs-intro-and-recommended.md: Add Casper instructions (preferred). --- .../docs-intro-and-recommended.md | 39 ++++++++++++++++--- 1 file changed, 33 insertions(+), 6 deletions(-) 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 3c01a98eea..2bcf2957c1 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 @@ -15,19 +15,21 @@ If you're confident in your changes, or you're _not_ confident in your ability t .. _building-the-documentation: ## Building the documentation -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. +We strongly suggest building and previewing the documentation before submitting a pull request, so that you can check 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. ### 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. The only restriction is that, at least for the recommended method described here, **your build directory must be somewhere in your CTSM clone**. (We recommend starting the name of your build directory with `_build` because CTSM knows to ignore such directories when it comes to `git`.) The instructions here assume you want to do your build in `doc/_build/`. -### One-time setup -You will need to have some software installed on your computer in order to build and the documentation and view the results: +### One-time setup for local builds +**The simplest way to build the CTSM documentation is on Casper.** If you prefer to work locally on your own computer, you will need to have some software installed in order to build the documentation and view the results: - :ref:`building-docs-prereqs-mac` - :ref:`building-docs-prereqs-windows` ### Building the docs All you need to do to build the docs with our recommended method is ```shell +module load podman # (Only if on Casper) + cd doc ./build_docs -b _build -c -d ``` @@ -44,16 +46,41 @@ The `-d` means "run using the container." If you're not using the container and 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, see :ref:`building-docs-multiple-versions`. -The process for viewing your build in a web browser differs depending on what kind of computer you have. +The process for viewing your build in a web browser differs depending on where you built the docs. + +### Remote build (e.g., Casper) +Open a terminal on your local machine and do this: +```shell +# user@server e.g. samrabin@casper.hpc.ucar.edu +ssh user@server echo $((10000 + $(id -u) % 50000)) +``` + +This will print an integer that we will call `YOUR_PORT`. + +Then open a new SSH connection to the server like so, replacing `YOUR_PORT` with the integer you got above: +```shell +ssh -L YOUR_PORT:localhost:YOUR_PORT user@server # e.g., samrabin@casper.hpc.ucar.edu +``` + +Once that's connected, we're going to spin up a web server. It's best to do this on a compute node rather than a login node. For Casper, use the `qinteractive` command to open an interactive session on a compute node. (Find more info about `qinteractive` [here](https://ncar-hpc-docs.readthedocs.io/en/latest/pbs/#qinteractive).) + +Once your interactive compute session is open, start the web server in it like so (again replacing `YOUR_PORT`): +```shell +cd /path/to/your/ctsm/repo +cd doc/_build/html +python3 -m http.server YOUR_PORT +``` + +Now you're ready to view your documentation! Just open a web browser on your computer and navigate to `http://localhost:YOUR_PORT`. You should see a rendered version of the documentation that you can browse as usual. -### Mac +### Local build: Mac You can open your build of the documentation in your default browser with ```shell open _build/html/index.html ``` -### Windows (Ubuntu VM) +### Local build: Windows (Ubuntu VM) Assuming you installed the WSL Utilities in the :ref:`windows-docs-ubuntu-utilities` setup step, you can open your build of the documentation like so: ```shell From 440951123b0fca2e09976d8f68483cb98f4c0322 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 2 Apr 2026 16:57:47 -0600 Subject: [PATCH 04/17] Reorder working-with-documentation index page. --- doc/source/users_guide/working-with-documentation/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/users_guide/working-with-documentation/index.rst b/doc/source/users_guide/working-with-documentation/index.rst index 198da612d4..8afc3b3ded 100644 --- a/doc/source/users_guide/working-with-documentation/index.rst +++ b/doc/source/users_guide/working-with-documentation/index.rst @@ -10,10 +10,10 @@ Working with CTSM Documentation :maxdepth: 1 docs-intro-and-recommended.md + tips-for-working-with-markdown.md + tips-for-working-with-rst.md building-docs-prereqs-mac.md building-docs-prereqs-windows.md building-docs-multiple-versions.rst - tips-for-working-with-markdown.md - tips-for-working-with-rst.md building-docs-original-wiki.md From bd7801d6489adccc1bca0d90fed997ab33ea8990 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 2 Apr 2026 16:58:00 -0600 Subject: [PATCH 05/17] Testing whether ESMCI/doc-builder#27 is resolved by commenting out code. --- doc/doc-builder | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/doc-builder b/doc/doc-builder index e03ff5e22e..a1bc2f9a34 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit e03ff5e22eba68fe6682b3b9de30bd6ee633ebd5 +Subproject commit a1bc2f9a346a6248e25282ccdf8198aa33970ef4 From db8c10ea1e5f6f438a31c78916c1b463a0af28fa Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 2 Apr 2026 17:11:54 -0600 Subject: [PATCH 06/17] Update doc-builder to v2.2.8: Podman multi-version build on Casper works, so now allowing that. --- .gitmodules | 2 +- doc/doc-builder | 2 +- .../building-docs-multiple-versions.rst | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.gitmodules b/.gitmodules index bba741bac2..d8ee1b86a8 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.2.7 +fxtag = v2.2.8 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/doc/doc-builder b/doc/doc-builder index a1bc2f9a34..b65672695e 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit a1bc2f9a346a6248e25282ccdf8198aa33970ef4 +Subproject commit b65672695e73d00dee1cadb1b0b8ccb7001a5c67 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 index 895dbf2a65..bc28dfd891 100644 --- 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 @@ -5,14 +5,14 @@ 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``. -Note that this is not necessary in order for you to contribute an update to the documentation. GitHub will test this automatically when you open a PR. But if you'd like to try, this will generate a local site for you in ``_publish/`` and then open it: +**Note that this is not necessary in order for you to contribute an update to the documentation.** GitHub will test this automatically when you open a PR. But if you'd like to try, this will generate a local site for you in ``_publish/`` and then open it: .. literalinclude:: ../../../test/test_container_eq_ctsm_pylib.sh :start-at: ./build_docs_to_publish :end-before: VERSION LINKS WILL NOT RESOLVE :append: CMD _publish/index.html # where CMD is open for Mac or wslview for Windows (Ubuntu VM) -**Note:** This is not yet supported with Podman on Linux (including Ubuntu VM on Windows). See `doc-builder Issue #27: build_docs_to_publish fails on Linux (maybe just Ubuntu?) with Podman `_. It does work with Docker on Linux, though. +**Note:** This may run into trouble with Podman on Linux (including Ubuntu VM on Windows, but **not** including Casper builds). See `doc-builder Issue #27: build_docs_to_publish fails on Linux (maybe just Ubuntu?) with Podman `_. It should definitely work with Docker on Linux, though. How this works From 23a62b46758bd8f14bbaef5c4a4aeaf7e62ce8b3 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 2 Apr 2026 17:21:16 -0600 Subject: [PATCH 07/17] Fallback instructions: Download html/ dir and open locally. --- .../working-with-documentation/docs-intro-and-recommended.md | 2 ++ 1 file changed, 2 insertions(+) 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 2bcf2957c1..bd16e1ed18 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 @@ -73,6 +73,8 @@ python3 -m http.server YOUR_PORT Now you're ready to view your documentation! Just open a web browser on your computer and navigate to `http://localhost:YOUR_PORT`. You should see a rendered version of the documentation that you can browse as usual. +If that doesn't work, you can download the `doc/_build/html` directory to your computer (e.g., with `scp` or `rsync`) and open `html/index.html` in a web browser. + ### Local build: Mac You can open your build of the documentation in your default browser with From 84da9d16b35f2c6dcb5fe1ddd1e99be2448c8f75 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 3 Apr 2026 12:52:36 -0600 Subject: [PATCH 08/17] Reorganize docs docs. --- .../bld-prev-docs-casper.md | 48 ++++++++++ ...cs-prereqs-mac.md => bld-prev-docs-mac.md} | 54 +++++++---- ...qs-windows.md => bld-prev-docs-windows.md} | 72 +++++++++----- .../building-docs-original-wiki.md | 2 +- .../common-docs-errors.md | 83 ++++++++++++++++ .../docs-intro-and-recommended.md | 95 ------------------- .../working-with-documentation/docs-intro.md | 31 ++++++ .../embed-build-cmd.md | 12 +++ .../embed-preview-menu.md | 1 + .../working-with-documentation/index.rst | 8 +- .../tips-for-working-with-rst.md | 74 +-------------- 11 files changed, 269 insertions(+), 211 deletions(-) create mode 100644 doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md rename doc/source/users_guide/working-with-documentation/{building-docs-prereqs-mac.md => bld-prev-docs-mac.md} (87%) rename doc/source/users_guide/working-with-documentation/{building-docs-prereqs-windows.md => bld-prev-docs-windows.md} (75%) create mode 100644 doc/source/users_guide/working-with-documentation/common-docs-errors.md delete mode 100644 doc/source/users_guide/working-with-documentation/docs-intro-and-recommended.md create mode 100644 doc/source/users_guide/working-with-documentation/docs-intro.md create mode 100644 doc/source/users_guide/working-with-documentation/embed-build-cmd.md create mode 100644 doc/source/users_guide/working-with-documentation/embed-preview-menu.md diff --git a/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md b/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md new file mode 100644 index 0000000000..5820316917 --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md @@ -0,0 +1,48 @@ +.. _bld-prev-docs-casper: + +# Building and previewing the documentation on Casper (RECOMMENDED) + +.. contents:: + :depth: 1 + :local: + +## Initial Casper setup + +None! This is why Casper is the recommended method for building and previewing the docs. + +## Building docs on Casper +Casper uses the Podman software for running containers like the one we recommend for building the CTSM documentation. Make sure it's enabled before building: `module load podman`. Then do: + +.. mdinclude:: embed-build-cmd.md + +See the "Container software or Conda environment" sections for :ref:`Mac ` or :ref:`Windows ` for more information on these two methods. + +## Previewing docs on Casper + +Open a terminal on your local machine and do this: +```shell +# user@server e.g. samrabin@casper.hpc.ucar.edu +ssh user@server echo $((10000 + $(id -u) % 50000)) +``` + +This will print an integer that we will call `YOUR_PORT`. + +Then open a new SSH connection to the server like so, replacing `YOUR_PORT` with the integer you got above: +```shell +ssh -L YOUR_PORT:localhost:YOUR_PORT user@server # e.g., samrabin@casper.hpc.ucar.edu +``` + +Once that's connected, we're going to spin up a web server. It's best to do this on a compute node rather than a login node. For Casper, use the `qinteractive` command to open an interactive session on a compute node. (Find more info about `qinteractive` [here](https://ncar-hpc-docs.readthedocs.io/en/latest/pbs/#qinteractive).) + +Once your interactive compute session is open, start the web server in it like so (again replacing `YOUR_PORT`): +```shell +cd /path/to/your/ctsm/repo +cd doc/_build/html +python3 -m http.server YOUR_PORT +``` + +Now you're ready to view your documentation! Just open a web browser on your computer and navigate to `http://localhost:YOUR_PORT`. You should see a rendered version of the documentation that you can browse as usual. + +If that doesn't work, you can download the `doc/_build/html` directory to your computer (e.g., with `scp` or `rsync`) and open `html/index.html` in a web browser. + +.. mdinclude:: embed-preview-menu.md diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md b/doc/source/users_guide/working-with-documentation/bld-prev-docs-mac.md similarity index 87% rename from doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md rename to doc/source/users_guide/working-with-documentation/bld-prev-docs-mac.md index c5629ba0ea..b2b2adf437 100644 --- a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md +++ b/doc/source/users_guide/working-with-documentation/bld-prev-docs-mac.md @@ -1,12 +1,18 @@ -.. _building-docs-prereqs-mac: +.. _bld-prev-docs-mac: -# Initial setup: Mac +# Building and previewing the documentation on Mac + +.. contents:: + :depth: 1 + :local: + +## Initial Mac setup Note that you may need administrator privileges on your Mac for the installation steps detailed here. .. _building-docs-git-tools: -## Python +### Python To test whether you already have the required Python version, open a Terminal window and try the following: ```shell python3 --version @@ -23,7 +29,7 @@ If instead `python3` gives "command not found," or the version is less than 3.7, .. _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 @@ -34,7 +40,7 @@ This will make it so that bash scripts, like what we use to build our docs, know If you were able to do this, you can continue to :ref:`additional-reqs`. If not, continue to the next section. -### Conda +#### 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: :ref:`do-i-already-have-conda` If not, install Conda (:ref:`installing-conda-for-docs`), then come back here. Try this to check the Python version in the `base` Conda environment: @@ -46,11 +52,11 @@ Repeat with all your Conda environments as needed until you find one that's Pyth .. _additional-reqs: -## Additional requirements +### Additional requirements .. _container-or-conda-mac: -### Container software or Conda environment +#### Container software or Conda environment We recommend building the software in what's called a container—basically a tiny little operating system with just some apps and utilities needed by the doc-building process. This is nice because, if we change the doc-building process in ways that require new versions of those apps and utilities, that will be completely invisible to you. You won't need to manually do anything to update your setup to work with the new process; it'll just happen automatically. We recommend using the container software Podman, which you can install with Homebrew. (:ref:`install-homebrew-mac`) @@ -66,7 +72,7 @@ You may not be able to install Podman or any other containerization software, so .. _docs-git-tools: -### 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: @@ -80,22 +86,22 @@ If either of those fail with "command not found," you'll need to install them. T 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 +### Frequently-asked questions .. _what-kind-of-mac-chip: -### What kind of chip does my Mac have? +#### 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. .. _install-homebrew-mac: -### How do I install Homebrew? +#### How do I install Homebrew? 1. Install Homebrew using the instructions at https://brew.sh/. Make sure to follow the instructions during this process for adding Homebrew to your path. 1. Check your installation by making sure that `brew --version` doesn't error. .. _do-i-already-have-conda: -### Do I already have Conda installed? +#### Do I already have Conda installed? You can check whether you have Conda installed like so: ```shell conda env list @@ -103,8 +109,8 @@ conda env list If that shows you something like ``` -# conda environments: -# +## conda environments: +## base /Users/you/... another_env /Users/you/.../... ... @@ -114,10 +120,26 @@ instead of the "command not found" error, then you do have conda installed! (Not .. _installing-conda-for-docs: -### How do I install Conda? +#### How do I install 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. (:ref:`install-homebrew-mac`) 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. \ No newline at end of file +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. + +## Building docs on Mac +Open a terminal window and navigate to your CTSM checkout. Then do: + +.. mdinclude:: embed-build-cmd.md + +See :ref:`container-or-conda-mac` for more information on those two methods. + +## Previewing docs on Mac + +You can open your build of the documentation in your default browser with +```shell +open _build/html/index.html +``` + +.. mdinclude:: embed-preview-menu.md diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md b/doc/source/users_guide/working-with-documentation/bld-prev-docs-windows.md similarity index 75% rename from doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md rename to doc/source/users_guide/working-with-documentation/bld-prev-docs-windows.md index ceb701b5cf..71968d8ad3 100644 --- a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md +++ b/doc/source/users_guide/working-with-documentation/bld-prev-docs-windows.md @@ -1,22 +1,28 @@ -.. _building-docs-prereqs-windows: +.. _bld-prev-docs-windows: -# Initial setup: Windows +# Building and previewing the documentation on Windows + +.. contents:: + :depth: 1 + :local: + +## Initial Windows setup Note that you may need administrator privileges on your PC (or approval from your IT department) for various steps here. .. _install-wsl: -## Install Linux subsystem +### Install 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 inside a virtual machine (VM) to use instead. The process for doing this varies depending on how tightly the installation process is controlled on your computer. -### NCAR computers +#### NCAR computers Please follow the [Windows Subsystem for Linux (WSL) setup instructions](https://wiki.ucar.edu/pages/viewpage.action?pageId=514032264&spaceKey=CONFIGMGMT&title=Setup) on the UCAR Wiki. In the step about installing a Linux distribution, choose Ubuntu. Feel free to peruse the [overall WSL documentation](https://wiki.ucar.edu/spaces/CONFIGMGMT/pages/514032242/Windows+Subsystem+for+Linux) on and linked from the UCAR Wiki for additional information. -### Non-NCAR computers +#### Non-NCAR computers If your computer is managed by an organization other than NCAR, please check with your IT department or equivalent for instructions on installing Windows Subsystem for Linux (WSL) and Ubuntu. Otherwise, follow these instructions: @@ -30,45 +36,45 @@ Once Ubuntu is working and open, you'll be asked to create a new UNIX username a .. _windows-docs-ubuntu-utilities: -## Install utilities +### Install utilities Enter the following commands **into your Ubuntu terminal** to install any missing utilities we need (the `which ... ||` should make it so that no installation happens if you already have it): ```shell -# Refresh the list of available software +## Refresh the list of available software sudo apt-get update -# make: Part of the docs-building process +## make: Part of the docs-building process which make || sudo apt-get -y install make -# git and git-lfs, needed for getting and contributing to the CTSM code and docs +## git and git-lfs, needed for getting and contributing to the CTSM code and docs which git || sudo apt-get -y install git which git-lfs || sudo apt-get -y install git-lfs -# WSL utilities, which will give us the wslview command for opening HTML pages in a Windows browser +## WSL utilities, which will give us the wslview command for opening HTML pages in a Windows browser which wslview || sudo apt-get -y install wslu ``` .. _container-or-conda-windows: -## Install container software or Conda environment +### Install container software or Conda environment We recommend building the software in what's called a container—basically a tiny little operating system with just some apps and utilities needed by the doc-building process. This is nice because, if we change the doc-building process in ways that require new versions of those apps and utilities, that will be completely invisible to you. You won't need to manually do anything to update your setup to work with the new process; it'll just happen automatically. For builds in WSL (Ubuntu), we recommend using the container software Docker. You can install it in Ubuntu like so: ```shell -# If needed, download and run the Docker installation script. -# Ignore the message saying "We recommend using Docker Desktop for Windows." -# The script will make you wait 20 seconds to make sure this is want you want, -# and then it should continue automatically. +## If needed, download and run the Docker installation script. +## Ignore the message saying "We recommend using Docker Desktop for Windows." +## The script will make you wait 20 seconds to make sure this is want you want, +## and then it should continue automatically. which docker || curl -fsSL https://get.docker.com -o get-docker.sh which docker || sudo sh ./get-docker.sh -# Set up the docker "group," if needed, and add your username to it. +## Set up the docker "group," if needed, and add your username to it. sudo groupadd docker # Create docker group if it doesn't exist sudo usermod -aG docker $USER # Add your user to the docker group newgrp docker # Apply the new group membership (avoids needing to log out and back in) -# Make sure it worked: This should print a "Hello from Docker!" message +## Make sure it worked: This should print a "Hello from Docker!" message docker run hello-world ``` @@ -79,10 +85,10 @@ You may not be able to install Docker or any other containerization software, so .. _editing-text-files-wsl: -## Editing documentation files +### Editing documentation files If you prefer using an old-school text editor like `vim`, it's probably already installed in your Ubuntu VM, or can be installed with `sudo apt-get -y install EDITOR_NAME`. If you prefer a more user-friendly interface, there are several options. Note that **all commands in this section are to be run in your Ubuntu VM, not a Windows terminal**. -### In a Windows app (recommended) +#### In a Windows app (recommended) If you installed `wslview` in the instructions above, you can edit files by doing ```shell wslview path/to/file_i_want_to_edit.rst @@ -103,7 +109,7 @@ If you use [VS Code](https://code.visualstudio.com/), you can install the [WSL V code path/to/file-or-folder ``` -### In an Ubuntu app (not recommended) +#### In an Ubuntu app (not recommended) You can also install a user-friendly text editor in Ubuntu. This may be slower and have unexpected differences in behavior from what you expect from Windows apps, but it does work. For example: - [gedit](https://gedit-text-editor.org/): `sudo apt-get install -y gedit` @@ -112,9 +118,9 @@ You can also install a user-friendly text editor in Ubuntu. This may be slower a You can use all of those to open and edit files, but Kate and VS Code let you open entire folders, which can be convenient. In any case, you'd do `EDITOR_NAME path/to/thing/youre/editing` to open it, where `EDITOR_NAME` is `gedit`, `kate`, or `code`, respectively. -## Troubleshooting +### Troubleshooting -### "Permission denied" error +#### "Permission denied" error If you get this error, it may be a result of opening Ubuntu as an administrator (e.g., by right-clicking on its icon and choosing "Run as administrator.") Try not doing that, although this will result in you needing to get a new copy of CTSM to work in. @@ -125,6 +131,26 @@ chown -R $USER:$USER $HOME If that also gives a permission error, you may need to put `sudo` at the start of the command. -### "The host 'wsl$' was not found in the list of allowed hosts" +#### "The host 'wsl$' was not found in the list of allowed hosts" You may see this warning in a dialog box after trying to open a file with `wslview`, `explorer.exe`, or something else. Check "Permanently allow host 'wsl$'" and then press "Allow". + +## Building docs on Windows (Ubuntu VM) +Open a WSL terminal window and navigate to your CTSM checkout. Then do: + +.. mdinclude:: embed-build-cmd.md + +See :ref:`container-or-conda-windows` for more information on those two methods. + +## Previewing docs on Windows (Ubuntu VM) +Assuming you installed the WSL Utilities in the :ref:`windows-docs-ubuntu-utilities` setup step, you can open your build of the documentation like so: +```shell +wslview _build/html/index.html +``` +If you didn't, you can do +```shell +explorer.exe $(wslpath -w _build/html/index.html) +``` +These both do the same thing, but the `wslview` method is simpler. Either way, at least the first time you do this, it will open a window asking which app you'd like to view the HTML file in. Choose a browser like Microsoft Edge or Chrome. At the bottom of the window, you can then choose whether you always want to open HTML files using the selected app or just this once. + +.. mdinclude:: embed-preview-menu.md 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 63acab53a7..b8774b23d1 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,6 +5,6 @@ .. warning:: ⚠️⚠️⚠️WARNING⚠️⚠️⚠️ - 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`. + 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`. 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/common-docs-errors.md b/doc/source/users_guide/working-with-documentation/common-docs-errors.md new file mode 100644 index 0000000000..68fe591e21 --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/common-docs-errors.md @@ -0,0 +1,83 @@ +.. _common-docs-errors: + +# Common doc build errors and how to handle them + +## Common docs errors: doc-builder + +.. _common-rst-errors: + +## Common docs errors: reStructuredText + +.. _error-unexpected-unindent: + +### "ERROR: Unexpected indentation" + +Like Python, reStructuredText is very particular about how lines are indented. Indentation is used, for example, to denote [code ("literal") blocks](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks) and [quote blocks](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks). An error like +``` +/path/to/file.rst:102: ERROR: Unexpected indentation. [docutils] +``` +indicates that line 102 is indented but not in a way that reStructuredText expects. + +### "WARNING: Block quote ends without a blank line; unexpected unindent" + +This is essentially the inverse of :ref:`error-unexpected-unindent`: The above line was indented but this one isn't. reStructuredText tried to interpret the indented line as a [block quote](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks), but block quotes require a blank line after them. + +.. _inline-literal-start-without-end: + +### "WARNING: Inline literal start-string without end-string" + +An "inline literal" is when you want to mix code into a normal line of text (as opposed to in its own code block) ``like this``. This is accomplished with double-backticks: +```reStructuredText +An "inline literal" is when you want to mix code into a normal line of +text (as opposed to in its own code block) ``like this``. +``` +(A backtick is what you get if you press the key to the left of 1 on a standard US English keyboard.) + +If you have a double-backtick on a line, reStructuredText will think, "They want to start an inline literal here," then look for another double-backtick to end the literal. The "WARNING: Inline literal start-string without end-string" means it can't find one on that line. + +This might happen, for example, if you try to put a [Markdown code block](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks) in a .rst file. In that case, use the [reStructuredText code block syntax](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks) instead (optionally with [syntax highlighting](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight)). + +### "WARNING: Inline interpreted text or phrase reference start-string without end-string" + +Like :ref:`inline-literal-start-without-end`, this is probably related to having one double-backtick without another on the same line. As with that other error, it could be the result of a Markdown code block in a .rst file. + +### "ERROR: Error in "code" directive: maximum 1 argument(s) allowed, 19 supplied" + +This error might show something other than "code," like "highlight" or "sourcecode". It also will probably show a second number that's not 19. The problem is that you tried to write a [reStructuredText code block with syntax highlighting](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight) but didn't include a blank line after the first one: + +```reStructuredText +.. code:: shell + # How to list all the available grids + cd cime/scripts + ./query_config --grids +``` + +Fix this by adding a blank line: +```reStructuredText +.. code:: shell + + # How to list all the available grids + cd cime/scripts + ./query_config --grids +``` + +### 'ERROR: Error in "math" directive: invalid option block' + +You might have forgotten the empty line after an equation label. + +### "WARNING: Explicit markup ends without a blank line; unexpected unindent" + +You might have forgotten the leading spaces for every line after `.. math::`. As a reminder, you need at least one leading space on each line. + +You can also get this error if you forget to surround a :ref:`cross-reference label` with blank lines. In this case, the error message might point to lines far away from the actual problem. + +### "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 (b) a section. + +### "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. \ 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 deleted file mode 100644 index bd16e1ed18..0000000000 --- a/doc/source/users_guide/working-with-documentation/docs-intro-and-recommended.md +++ /dev/null @@ -1,95 +0,0 @@ -.. _docs-intro-and-recommended: - -# Working with the CTSM documentation -.. _editing-the-documentation: - -## Editing the documentation -First, you will need a clone of CTSM to get all the documentation files and infrastructure. (If you're on Windows, you will make this clone in your :ref:`Ubuntu VM `.) Note that you will clone this to your own computer, not Derecho or any cluster or anything. - -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). Note that "opening the source file" isn't completely straightforward on Windows; see :ref:`editing-text-files-wsl`. - -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) 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. - -.. _building-the-documentation: - -## Building the documentation -We strongly suggest building and previewing the documentation before submitting a pull request, so that you can check 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. - -### 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. The only restriction is that, at least for the recommended method described here, **your build directory must be somewhere in your CTSM clone**. (We recommend starting the name of your build directory with `_build` because CTSM knows to ignore such directories when it comes to `git`.) The instructions here assume you want to do your build in `doc/_build/`. - -### One-time setup for local builds -**The simplest way to build the CTSM documentation is on Casper.** If you prefer to work locally on your own computer, you will need to have some software installed in order to build the documentation and view the results: -- :ref:`building-docs-prereqs-mac` -- :ref:`building-docs-prereqs-windows` - -### Building the docs -All you need to do to build the docs with our recommended method is -```shell -module load podman # (Only if on Casper) - -cd doc -./build_docs -b _build -c -d -``` - -This runs a complicated series of scripts and software that culminate in something called Sphinx converting the .rst and .md files into HTML webpages. - -The `-c` means "do a clean build." If you leave it off, Sphinx will only rebuild files it thinks have changed since the last time you built the docs. It's not always right, which can lead to problems. If you get unexpected errors without `-c`, rerunning with `-c` is the first troubleshooting step. - -The `-d` means "run using the container." If you're not using the container and are instead using the `ctsm_pylib` Conda environment **(not recommended)**, leave off `-d`, and make sure you've activated `ctsm_pylib` before running the above command. See the "Container software or Conda environment" sections for :ref:`Mac ` or :ref:`Windows ` for more information on these two methods. - -(Do `./build_docs --help` for more information and options.) - -## Viewing your built docs - -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, see :ref:`building-docs-multiple-versions`. - -The process for viewing your build in a web browser differs depending on where you built the docs. - -### Remote build (e.g., Casper) -Open a terminal on your local machine and do this: -```shell -# user@server e.g. samrabin@casper.hpc.ucar.edu -ssh user@server echo $((10000 + $(id -u) % 50000)) -``` - -This will print an integer that we will call `YOUR_PORT`. - -Then open a new SSH connection to the server like so, replacing `YOUR_PORT` with the integer you got above: -```shell -ssh -L YOUR_PORT:localhost:YOUR_PORT user@server # e.g., samrabin@casper.hpc.ucar.edu -``` - -Once that's connected, we're going to spin up a web server. It's best to do this on a compute node rather than a login node. For Casper, use the `qinteractive` command to open an interactive session on a compute node. (Find more info about `qinteractive` [here](https://ncar-hpc-docs.readthedocs.io/en/latest/pbs/#qinteractive).) - -Once your interactive compute session is open, start the web server in it like so (again replacing `YOUR_PORT`): -```shell -cd /path/to/your/ctsm/repo -cd doc/_build/html -python3 -m http.server YOUR_PORT -``` - -Now you're ready to view your documentation! Just open a web browser on your computer and navigate to `http://localhost:YOUR_PORT`. You should see a rendered version of the documentation that you can browse as usual. - -If that doesn't work, you can download the `doc/_build/html` directory to your computer (e.g., with `scp` or `rsync`) and open `html/index.html` in a web browser. - -### Local build: Mac - -You can open your build of the documentation in your default browser with -```shell -open _build/html/index.html -``` - -### Local build: Windows (Ubuntu VM) - -Assuming you installed the WSL Utilities in the :ref:`windows-docs-ubuntu-utilities` setup step, you can open your build of the documentation like so: -```shell -wslview _build/html/index.html -``` -If you didn't, you can do -```shell -explorer.exe $(wslpath -w _build/html/index.html) -``` -These both do the same thing, but the `wslview` method is simpler. Either way, at least the first time you do this, it will open a window asking which app you'd like to view the HTML file in. Choose a browser like Microsoft Edge or Chrome. At the bottom of the window, you can then choose whether you always want to open HTML files using the selected app or just this once. diff --git a/doc/source/users_guide/working-with-documentation/docs-intro.md b/doc/source/users_guide/working-with-documentation/docs-intro.md new file mode 100644 index 0000000000..87b211959d --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/docs-intro.md @@ -0,0 +1,31 @@ +.. _docs-intro: + +# Working with the CTSM documentation + +If you're reading this page, you're probably interested in making an improvement to this CTSM documentation website—thank you! Please read this page thoroughly before starting to make it as smooth a process as possible. + +## How the documentation works +The documentation starts life as 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. + +During the "build" process, these files are converted to HTML webpages using a tool called Sphinx. This creates a directory with HTML files that can then be "previewed" to make sure they look right. When you submit a pull request (PR; see [Contribution guidelines](#docs-contribution-guidelines) below), tests will automatically run to make sure your changed documentation builds with no errors. Then, when your PR is merged to the main CTSM branch, it will be rebuilt and published automatically. + +.. _docs-contribution-guidelines: + +## Contribution guidelines +We use the [CTSM GitHub repo](https://github.com/ESCOMP/CTSM) to track issues with the documentation and bring in changes. Please have a look at our ["How to contribute"](https://github.com/ESCOMP/CTSM/blob/master/CONTRIBUTING.md) readme for some general guidelines. + +If you have found a problem with the documentation but aren't able to fix it immediately, or if you're not sure whether something is truly a problem or how to fix it, please [file an issue](https://github.com/ESCOMP/CTSM/issues/new?template=03_documentation.md). + +If you've made changes that you'd like us to bring in, you can file a [pull request](https://github.com/ESCOMP/ctsm/pulls) (PR; "New pull request" button at that link). Please try to avoid filing many small documentation PRs in a short time, as it's easier for the maintenance team if you combine similar edits into one larger PR. For example, several typo fixes in a file or across files would be a good single PR. You can also mark a PR as "draft" if you think you may be adding more to it, or if you think it's otherwise not ready for review. + +Whenever you submit a documentation PR or commit new changes to one, automated testing will check the updated documentation for any errors. If you get failures, please try to diagnose and fix them; see :ref:`common-docs-errors` for tips. If you resolve the errors, add a comment on your PR saying so, and one of the CTSM software engineers will have a look. + +## Editing the documentation +First, you will need a clone of CTSM to get all the documentation files and infrastructure. Once you have that, 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). You can mix some reStructuredText into Markdown files, but generally not the other way around. For more information, see: +- :ref:`tips-for-working-with-markdown` +- :ref:`tips-for-working-with-rst` + +We strongly recommend building and previewing the docs yourself as you're editing them, or at least before requesting review on your PR. You can find instructions for doing so here: +- :ref:`bld-prev-docs-casper` **(recommended)** +- :ref:`bld-prev-docs-mac` +- :ref:`bld-prev-docs-windows` diff --git a/doc/source/users_guide/working-with-documentation/embed-build-cmd.md b/doc/source/users_guide/working-with-documentation/embed-build-cmd.md new file mode 100644 index 0000000000..8f08a0c32c --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/embed-build-cmd.md @@ -0,0 +1,12 @@ +```shell +cd doc +./build_docs -b _build -c -d +``` + +This runs a complicated series of scripts and software that culminate in something called Sphinx converting the .rst and .md files into HTML webpages, all within the (new, if needed) `_build` directory. + +The `-c` means "do a clean build." If you leave it off, Sphinx will only rebuild files it thinks have changed since the last time you built the docs, which is faster but can lead to problems. If you get unexpected results or errors without `-c`, rerunning with `-c` is the first troubleshooting step. + +The `-d` means "run using the container." If you're not using the container and are instead using the `ctsm_pylib` Conda environment **(not recommended)**, leave off `-d`, and make sure you've activated `ctsm_pylib` before running the above command. + +(Do `./build_docs --help` for more information and options.) diff --git a/doc/source/users_guide/working-with-documentation/embed-preview-menu.md b/doc/source/users_guide/working-with-documentation/embed-preview-menu.md new file mode 100644 index 0000000000..e3ffc45625 --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/embed-preview-menu.md @@ -0,0 +1 @@ +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, see :ref:`building-docs-multiple-versions`. diff --git a/doc/source/users_guide/working-with-documentation/index.rst b/doc/source/users_guide/working-with-documentation/index.rst index 8afc3b3ded..0c80b59de0 100644 --- a/doc/source/users_guide/working-with-documentation/index.rst +++ b/doc/source/users_guide/working-with-documentation/index.rst @@ -9,11 +9,13 @@ Working with CTSM Documentation .. toctree:: :maxdepth: 1 - docs-intro-and-recommended.md + docs-intro.md + bld-prev-docs-casper.md + bld-prev-docs-mac.md + bld-prev-docs-windows.md tips-for-working-with-markdown.md tips-for-working-with-rst.md - building-docs-prereqs-mac.md - building-docs-prereqs-windows.md + common-docs-errors.md building-docs-multiple-versions.rst building-docs-original-wiki.md 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 index 164f24115b..18afbf39a6 100644 --- 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 @@ -90,76 +90,4 @@ If you already have a table in some other format, like comma-separated values (C ## reStructuredText: Common error messages and how to handle them -.. _error-unexpected-unindent: - -### "ERROR: Unexpected indentation" - -Like Python, reStructuredText is very particular about how lines are indented. Indentation is used, for example, to denote [code ("literal") blocks](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks) and [quote blocks](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks). An error like -``` -/path/to/file.rst:102: ERROR: Unexpected indentation. [docutils] -``` -indicates that line 102 is indented but not in a way that reStructuredText expects. - -### "WARNING: Block quote ends without a blank line; unexpected unindent" - -This is essentially the inverse of :ref:`error-unexpected-unindent`: The above line was indented but this one isn't. reStructuredText tried to interpret the indented line as a [block quote](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks), but block quotes require a blank line after them. - -.. _inline-literal-start-without-end: - -### "WARNING: Inline literal start-string without end-string" - -An "inline literal" is when you want to mix code into a normal line of text (as opposed to in its own code block) ``like this``. This is accomplished with double-backticks: -```reStructuredText -An "inline literal" is when you want to mix code into a normal line of -text (as opposed to in its own code block) ``like this``. -``` -(A backtick is what you get if you press the key to the left of 1 on a standard US English keyboard.) - -If you have a double-backtick on a line, reStructuredText will think, "They want to start an inline literal here," then look for another double-backtick to end the literal. The "WARNING: Inline literal start-string without end-string" means it can't find one on that line. - -This might happen, for example, if you try to put a [Markdown code block](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks) in a .rst file. In that case, use the [reStructuredText code block syntax](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks) instead (optionally with [syntax highlighting](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight)). - -### "WARNING: Inline interpreted text or phrase reference start-string without end-string" - -Like :ref:`inline-literal-start-without-end`, this is probably related to having one double-backtick without another on the same line. As with that other error, it could be the result of a Markdown code block in a .rst file. - -### "ERROR: Error in "code" directive: maximum 1 argument(s) allowed, 19 supplied" - -This error might show something other than "code," like "highlight" or "sourcecode". It also will probably show a second number that's not 19. The problem is that you tried to write a [reStructuredText code block with syntax highlighting](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight) but didn't include a blank line after the first one: - -```reStructuredText -.. code:: shell - # How to list all the available grids - cd cime/scripts - ./query_config --grids -``` - -Fix this by adding a blank line: -```reStructuredText -.. code:: shell - - # How to list all the available grids - cd cime/scripts - ./query_config --grids -``` - -### 'ERROR: Error in "math" directive: invalid option block' - -You might have forgotten the empty line after an equation label. - -### "WARNING: Explicit markup ends without a blank line; unexpected unindent" - -You might have forgotten the leading spaces for every line after `.. math::`. As a reminder, you need at least one leading space on each line. - -You can also get this error if you forget to surround a :ref:`cross-reference label` with blank lines. In this case, the error message might point to lines far away from the actual problem. - -### "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 (b) a section. - -### "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. \ No newline at end of file +See :ref:`common-rst-errors`. \ No newline at end of file From 88724c284ef57c0275cbd953e4e115e84468eb79 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 3 Apr 2026 13:20:50 -0600 Subject: [PATCH 09/17] Add instructions for previewing docs on Casper via OnDemand. --- .../bld-prev-docs-casper.md | 25 ++++++++++++++----- 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md b/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md index 5820316917..0fce52e547 100644 --- a/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md +++ b/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md @@ -19,20 +19,29 @@ See the "Container software or Conda environment" sections for :ref:`Mac Date: Fri, 3 Apr 2026 13:26:06 -0600 Subject: [PATCH 10/17] Link docs contrib guidelines in issue and PR templates. --- .github/ISSUE_TEMPLATE/03_documentation.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/03_documentation.md b/.github/ISSUE_TEMPLATE/03_documentation.md index e6c3fa0ff8..5538f047a0 100644 --- a/.github/ISSUE_TEMPLATE/03_documentation.md +++ b/.github/ISSUE_TEMPLATE/03_documentation.md @@ -3,7 +3,7 @@ name: Documentation about: Something should be added to or fixed in the documentation --- - +(Please see our [contribution guidelines for documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines).) ### What sort(s) of documentation issue is this? - [ ] Something is missing. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c4a381383b..b32248d4eb 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -22,3 +22,5 @@ Testing performed, if any: (https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review the list of common problems to watch out for (https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).** + +**If this PR changes the CTSM web documentation, please see our [contribution guidelines for documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines).** \ No newline at end of file From a70a6e4d020b3db5021410d8975c17a3b921b961 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 3 Apr 2026 13:45:42 -0600 Subject: [PATCH 11/17] Improve "Common docs errors" page. --- .../common-docs-errors.md | 108 +++++++++++++++++- 1 file changed, 107 insertions(+), 1 deletion(-) diff --git a/doc/source/users_guide/working-with-documentation/common-docs-errors.md b/doc/source/users_guide/working-with-documentation/common-docs-errors.md index 68fe591e21..2403d79953 100644 --- a/doc/source/users_guide/working-with-documentation/common-docs-errors.md +++ b/doc/source/users_guide/working-with-documentation/common-docs-errors.md @@ -2,8 +2,21 @@ # Common doc build errors and how to handle them +.. contents:: + :depth: 2 + :local: + +.. _common-doc-builder-errors: + ## Common docs errors: doc-builder +### "RuntimeError: No compatible container software found: docker, podman" + +You tried to build the documentation using our container (`./build_docs ... -d`) but didn't have any software running that could handle the container. Try again after starting up container software according to the instructions for your platform: +- :ref:`bld-prev-docs-casper` **(recommended)** +- :ref:`bld-prev-docs-mac` +- :ref:`bld-prev-docs-windows` + .. _common-rst-errors: ## Common docs errors: reStructuredText @@ -16,7 +29,100 @@ Like Python, reStructuredText is very particular about how lines are indented. I ``` /path/to/file.rst:102: ERROR: Unexpected indentation. [docutils] ``` -indicates that line 102 is indented but not in a way that reStructuredText expects. +indicates that line 102 is indented but not in a way that reStructuredText expects. There are lots of potential causes. + +#### Inconsistent indentation + +reStructuredText is whitespace-sensitive. Mixed tabs and spaces, or inconsistent indentation levels within the same block, will trigger this error. Use spaces only, and keep indentation consistent throughout a block (typically 3–4 spaces for directives). + +**Incorrect** (mixed indentation levels): + +```rst +.. note:: + + This line uses 3 spaces. + This line uses 4 spaces and will cause an error. +``` + +**Correct:** + +```rst +.. note:: + + This line uses 3 spaces. + This line also uses 3 spaces. +``` + +#### Indented content with no preceding context + +If a block appears indented but there is no list item, directive, or other block element directly above it, Sphinx has no way to interpret the indentation. Either remove the indentation or add the appropriate introducing element. + +**Incorrect:** + +```rst +This is a normal paragraph. + + This indented block has no context and will cause an error. +``` + +**Correct** (remove the indentation): + +```rst +This is a normal paragraph. + +This line is at the same level and causes no error. +``` + +**Correct** (add a introducing element): + +```rst +This is a normal paragraph:: + + Now this indented block is valid as a literal block, such as you might use for code. +``` + +#### Continuation of a list item broken by a blank line + +In rST, a blank line ends a list item. If you indent content after a blank line following a list item, Sphinx may misread it. To include multi-paragraph list items, indent all continuation paragraphs to match the list item content. + +**Incorrect:** + +```rst +- First item. + + This paragraph looks like it continues the list item, but the + indentation level doesn't match, causing an error. + +- Second item. +``` + +**Correct:** + +```rst +- First item. + + This paragraph correctly continues the list item using + consistent 2-space indentation. + +- Second item. +``` + +#### Misformatted directives + +Directives require a blank line between the directive header (and any options) and the directive body. Missing or extra blank lines inside a directive block are a frequent source of this error. Double-check that your directive follows this structure: + +``` +.. directive-name:: argument + :option: value + + Body content starts here, indented consistently. +``` + +#### General Debugging Tips + +- **Check the line number** in the error message. Sphinx usually points to the exact line where the unexpected indentation was detected, but the *cause* is often one or two lines above it. +- **Simplify the block** by temporarily removing content to isolate which element is triggering the error. +- **Avoid tabs.** Configure your editor to insert spaces instead for `.rst` files, if possible. ### "WARNING: Block quote ends without a blank line; unexpected unindent" From a8347690679f7d5a728fa8d8804ed48e818b2881 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 3 Apr 2026 13:57:44 -0600 Subject: [PATCH 12/17] Add documentation style guide. --- .../working-with-documentation/docs-style-guide.md | 8 ++++++++ .../users_guide/working-with-documentation/index.rst | 1 + 2 files changed, 9 insertions(+) create mode 100644 doc/source/users_guide/working-with-documentation/docs-style-guide.md diff --git a/doc/source/users_guide/working-with-documentation/docs-style-guide.md b/doc/source/users_guide/working-with-documentation/docs-style-guide.md new file mode 100644 index 0000000000..c740f9ffbb --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/docs-style-guide.md @@ -0,0 +1,8 @@ +.. _docs-style-guide: + +# Documentation style guide + +- 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 [here](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, or you can copy it from here. 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` would be better than `: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:` directive. diff --git a/doc/source/users_guide/working-with-documentation/index.rst b/doc/source/users_guide/working-with-documentation/index.rst index 0c80b59de0..41331eea67 100644 --- a/doc/source/users_guide/working-with-documentation/index.rst +++ b/doc/source/users_guide/working-with-documentation/index.rst @@ -13,6 +13,7 @@ Working with CTSM Documentation bld-prev-docs-casper.md bld-prev-docs-mac.md bld-prev-docs-windows.md + docs-style-guide.md tips-for-working-with-markdown.md tips-for-working-with-rst.md common-docs-errors.md From 4d4f17c2838178b0755f3841f7c1d9815ee4ea8b Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 3 Apr 2026 17:56:12 -0600 Subject: [PATCH 13/17] Docs now use MyST Markdown parser. --- .gitmodules | 2 +- doc/ctsm-docs_container/Dockerfile | 2 +- doc/ctsm-docs_container/README.md | 14 ++- doc/ctsm-docs_container/requirements.txt | 2 +- doc/doc-builder | 2 +- .../using-clm-tools/paramfile-tools.md | 2 +- .../bld-prev-docs-casper.md | 17 +-- .../bld-prev-docs-mac.md | 58 +++++----- .../bld-prev-docs-windows.md | 29 ++--- .../building-docs-original-wiki.md | 9 +- .../common-docs-errors.md | 31 ++--- .../working-with-documentation/docs-intro.md | 18 +-- .../docs-style-guide.md | 2 +- .../embed-build-cmd.md | 4 + .../embed-preview-menu.md | 6 +- .../working-with-documentation/index.rst | 3 +- .../tips-for-working-with-markdown.md | 56 +++++---- .../tips-for-working-with-rst.md | 93 --------------- .../tips-for-working-with-rst.rst | 107 ++++++++++++++++++ 19 files changed, 251 insertions(+), 206 deletions(-) delete mode 100644 doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.md create mode 100644 doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.rst diff --git a/.gitmodules b/.gitmodules index d8ee1b86a8..f9257f3393 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.2.8 +fxtag = v3.0.0 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/doc/ctsm-docs_container/Dockerfile b/doc/ctsm-docs_container/Dockerfile index 3a24e1d4a4..e5ec2a6488 100644 --- a/doc/ctsm-docs_container/Dockerfile +++ b/doc/ctsm-docs_container/Dockerfile @@ -29,4 +29,4 @@ CMD ["/bin/bash", "-l"] LABEL org.opencontainers.image.title="Container for building CTSM documentation" LABEL org.opencontainers.image.source=https://github.com/ESCOMP/CTSM -LABEL org.opencontainers.image.version="v1.0.2e" +LABEL org.opencontainers.image.version="v2.0.1" diff --git a/doc/ctsm-docs_container/README.md b/doc/ctsm-docs_container/README.md index bff10aada2..2c8110275d 100644 --- a/doc/ctsm-docs_container/README.md +++ b/doc/ctsm-docs_container/README.md @@ -33,21 +33,22 @@ Here's where you need to specify the version number in the Dockerfile: ```docker LABEL org.opencontainers.image.version="vX.Y.Z" ``` -The string there can technically be anything as long as (a) it starts with a lowercase `v` and (b) it hasn't yet been used on a published version of the container. +The string there can technically be anything as long as (a) it starts with a lowercase `v` and (b) it hasn't yet been used on a published version of the container. You may need to "bump" the version string in order for various tests to pass; if so, just add a lowercase letter at the end. You can check the results of the automatic publication on the [container's GitHub page](https://github.com/ESCOMP/CTSM/pkgs/container/ctsm%2Fctsm-docs). ### Updating doc-builder After the new version of the container is published, you will probably want to tell [doc-builder](https://github.com/ESMCI/doc-builder) to use the new one. Open a PR where you change the tag (the part after the colon) in the definition of `DEFAULT_IMAGE` in `doc_builder/build_commands.py`. Remember, **use the version number**, not "latest". -## Publishing manually (NOT recommended) +## Publishing manually -It's vastly preferable to let GitHub build and publish the new repo using the `docker-image-build-publish.yml` workflow as described above. However, if you need to publish manually for some reason, here's how. +It's vastly preferable to let GitHub build and publish the new repo using the `docker-image-build-publish.yml` workflow as described above. However, you may need to publish manually if, for instance, you introduce a change that breaks `doc-builder`. You could work around that by first merging a CTSM `master` PR that updates the container, then updating `doc-builder` to use it, then updating CTSM to use the new `doc-builder`. That's not always practical, though, so here's how to publish the container manually. ### Building the multi-architecture version When publishing our container, we need to make sure it can run on either arm64 or amd64 processor architecture. This requires a special build process: ```shell +podman manifest rm ctsm-docs-manifest 2>/dev/null podman manifest create ctsm-docs-manifest podman build --platform linux/amd64,linux/arm64 --manifest ctsm-docs-manifest . ``` @@ -66,16 +67,17 @@ export HISTCONTROL=ignoreboth ``` ### Tagging -You'll next need to tag the image. Lots of container instructions tell you to use the `latest` tag, and Podman may actually add that for you. However, `latest` can lead to support headaches as users think they have the right version but actually don't. Instead, you'll make a new version number incremented from the [previous one](https://github.com/ESCOMP/CTSM/pkgs/container/ctsm%2Fctsm-docs/versions), in the `vX.Y.Z` format. +You'll next need to tag the image. Lots of container instructions tell you to use the `latest` tag, and Podman may actually add that for you. However, using `latest` in `doc-builder` can lead to support headaches as users think they have the right version but actually don't. So in addition to `latest`, you'll make a new version number incremented from the [previous one](https://github.com/ESCOMP/CTSM/pkgs/container/ctsm%2Fctsm-docs/versions), in the `vX.Y.Z` format. -Copy the relevant image ID (see `podman images` instructions above) and tag it with your version number like so: +Tag the manifest with your version number like so: ```shell -podman tag 6464f26339bc ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z +podman tag ctsm-docs-manifest ghcr.io/escomp/ctsm/ctsm-docs:v2.0.1 ``` Push to the repo: ```shell podman manifest push --all ctsm-docs-manifest ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z +podman manifest push --all ctsm-docs-manifest ghcr.io/escomp/ctsm/ctsm-docs:latest ``` Then browse to the [container's GitHub page](https://github.com/ESCOMP/CTSM/pkgs/container/ctsm%2Fctsm-docs) to make sure this all worked and the image is public. diff --git a/doc/ctsm-docs_container/requirements.txt b/doc/ctsm-docs_container/requirements.txt index 178f356b13..19872cb9c0 100644 --- a/doc/ctsm-docs_container/requirements.txt +++ b/doc/ctsm-docs_container/requirements.txt @@ -2,5 +2,5 @@ rst2pdf == 0.103.1 sphinx == 8.2.3 sphinxcontrib_programoutput == 0.18 -sphinx-mdinclude == 0.6.2 +myst-parser == 5.0.0 sphinx_rtd_theme == 3.0.2 diff --git a/doc/doc-builder b/doc/doc-builder index b65672695e..df0cac38b8 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit b65672695e73d00dee1cadb1b0b8ccb7001a5c67 +Subproject commit df0cac38b82d9e4066d1fd598f4b881ba831687e diff --git a/doc/source/users_guide/using-clm-tools/paramfile-tools.md b/doc/source/users_guide/using-clm-tools/paramfile-tools.md index eddba06d94..84b4d496eb 100644 --- a/doc/source/users_guide/using-clm-tools/paramfile-tools.md +++ b/doc/source/users_guide/using-clm-tools/paramfile-tools.md @@ -3,7 +3,7 @@ This guide describes the features and usage of the `query_paramfile` and `set_paramfile` tools, located in `tools/param_utils/`. These utilities help users inspect and modify CLM parameter files. -Note that you need to have the `ctsm_pylib` conda environment activated to use these tools. See Sect. :numref:`using-ctsm-pylib` for more information. +Note that you need to have the `ctsm_pylib` conda environment activated to use these tools. See Sect. {numref}`using-ctsm-pylib` for more information. ## `query_paramfile` **Purpose:** Print the values of one or more parameters from a CTSM parameter file (netCDF format). diff --git a/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md b/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md index 0fce52e547..992299b2ef 100644 --- a/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md +++ b/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md @@ -1,10 +1,11 @@ -.. _bld-prev-docs-casper: +(bld-prev-docs-casper)= # Building and previewing the documentation on Casper (RECOMMENDED) -.. contents:: - :depth: 1 - :local: +```{contents} +:depth: 1 +:local: +``` ## Initial Casper setup @@ -13,9 +14,10 @@ None! This is why Casper is the recommended method for building and previewing t ## Building docs on Casper Casper uses the Podman software for running containers like the one we recommend for building the CTSM documentation. Make sure it's enabled before building: `module load podman`. Then do: -.. mdinclude:: embed-build-cmd.md +```{include} embed-build-cmd.md +``` -See the "Container software or Conda environment" sections for :ref:`Mac ` or :ref:`Windows ` for more information on these two methods. +See the "Container software or Conda environment" sections for {ref}`Mac ` or {ref}`Windows ` for more information on these two methods. ## Previewing docs on Casper @@ -58,4 +60,5 @@ If neither of the above work, you can download the `doc/_build/html` directory t ### A note about previewing the docs -.. mdinclude:: embed-preview-menu.md +```{include} embed-preview-menu.md +``` diff --git a/doc/source/users_guide/working-with-documentation/bld-prev-docs-mac.md b/doc/source/users_guide/working-with-documentation/bld-prev-docs-mac.md index b2b2adf437..3f4c15873d 100644 --- a/doc/source/users_guide/working-with-documentation/bld-prev-docs-mac.md +++ b/doc/source/users_guide/working-with-documentation/bld-prev-docs-mac.md @@ -1,16 +1,17 @@ -.. _bld-prev-docs-mac: +(bld-prev-docs-mac)= # Building and previewing the documentation on Mac -.. contents:: - :depth: 1 - :local: +```{contents} +:depth: 1 +:local: +``` ## Initial Mac setup Note that you may need administrator privileges on your Mac for the installation steps detailed here. -.. _building-docs-git-tools: +(building-docs-git-tools)= ### Python To test whether you already have the required Python version, open a Terminal window and try the following: @@ -18,16 +19,15 @@ To test whether you already have the required Python version, open a Terminal wi 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:`additional-reqs`. +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}`additional-reqs`. -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:`additional-reqs`. +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}`additional-reqs`. -.. - The paragraph above was tested 2025-04-25 on a fresh-ish installation of macOS 15.3.2. +% 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`. Otherwise, continue to :ref:`additional-reqs`. +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`. Otherwise, continue to {ref}`additional-reqs`. -.. _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`: @@ -38,10 +38,10 @@ 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:`additional-reqs`. If not, continue to the next section. +If you were able to do this, you can continue to {ref}`additional-reqs`. If not, continue to the next section. #### 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: :ref:`do-i-already-have-conda` If not, install Conda (:ref:`installing-conda-for-docs`), then come back here. +If your `python` doesn't exist or is too old, we suggest using Python via Conda. First, check whether you already have Conda installed: {ref}`do-i-already-have-conda` If not, install Conda ({ref}`installing-conda-for-docs`), then come back here. Try this to check the Python version in the `base` Conda environment: ```shell @@ -50,16 +50,16 @@ 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. -.. _additional-reqs: +(additional-reqs)= ### Additional requirements -.. _container-or-conda-mac: +(container-or-conda-mac)= #### Container software or Conda environment We recommend building the software in what's called a container—basically a tiny little operating system with just some apps and utilities needed by the doc-building process. This is nice because, if we change the doc-building process in ways that require new versions of those apps and utilities, that will be completely invisible to you. You won't need to manually do anything to update your setup to work with the new process; it'll just happen automatically. -We recommend using the container software Podman, which you can install with Homebrew. (:ref:`install-homebrew-mac`) +We recommend using the container software Podman, which you can install with Homebrew. ({ref}`install-homebrew-mac`) 1. Install Podman with `brew install podman`. 1. Set up and start a Podman "virtual machine" with `podman machine init --now`. @@ -67,10 +67,10 @@ We recommend using the container software Podman, which you can install with Hom You may not be able to install Podman or any other containerization software, so there is an alternative method: a Conda environment. -1. Install Conda, if needed (see :ref:`installing-conda-for-docs`). -1. Follow the instructions for setting up the `ctsm_pylib` Conda environment in Sect. :numref:`using-ctsm-pylib`. +1. Install Conda, if needed (see {ref}`installing-conda-for-docs`). +1. Follow the instructions for setting up the `ctsm_pylib` Conda environment in Sect. {numref}`using-ctsm-pylib`. -.. _docs-git-tools: +(docs-git-tools)= #### Git tools Note: Do this section after handling Python, because the Python installation process might bring the Git tools with it. @@ -81,25 +81,25 @@ 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. (:ref:`install-homebrew-mac`) +If either of those fail with "command not found," you'll need to install them. The recommended way is with Homebrew. ({ref}`install-homebrew-mac`) 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-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. -.. _install-homebrew-mac: +(install-homebrew-mac)= #### How do I install Homebrew? 1. Install Homebrew using the instructions at https://brew.sh/. Make sure to follow the instructions during this process for adding Homebrew to your path. 1. Check your installation by making sure that `brew --version` doesn't error. -.. _do-i-already-have-conda: +(do-i-already-have-conda)= #### Do I already have Conda installed? You can check whether you have Conda installed like so: @@ -118,12 +118,12 @@ 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.) -.. _installing-conda-for-docs: +(installing-conda-for-docs)= #### How do I install 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. (:ref:`install-homebrew-mac`) +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. ({ref}`install-homebrew-mac`) 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. @@ -131,9 +131,10 @@ You should now have `conda` and an up-to-date version of `python3` available, al ## Building docs on Mac Open a terminal window and navigate to your CTSM checkout. Then do: -.. mdinclude:: embed-build-cmd.md +```{include} embed-build-cmd.md +``` -See :ref:`container-or-conda-mac` for more information on those two methods. +See {ref}`container-or-conda-mac` for more information on those two methods. ## Previewing docs on Mac @@ -142,4 +143,5 @@ You can open your build of the documentation in your default browser with open _build/html/index.html ``` -.. mdinclude:: embed-preview-menu.md +```{include} embed-preview-menu.md +``` diff --git a/doc/source/users_guide/working-with-documentation/bld-prev-docs-windows.md b/doc/source/users_guide/working-with-documentation/bld-prev-docs-windows.md index 71968d8ad3..2894334199 100644 --- a/doc/source/users_guide/working-with-documentation/bld-prev-docs-windows.md +++ b/doc/source/users_guide/working-with-documentation/bld-prev-docs-windows.md @@ -1,16 +1,17 @@ -.. _bld-prev-docs-windows: +(bld-prev-docs-windows)= # Building and previewing the documentation on Windows -.. contents:: - :depth: 1 - :local: +```{contents} +:depth: 1 +:local: +``` ## Initial Windows setup Note that you may need administrator privileges on your PC (or approval from your IT department) for various steps here. -.. _install-wsl: +(install-wsl)= ### Install Linux subsystem @@ -34,7 +35,7 @@ If Ubuntu opens in that last step but you see an error, you may need to manually Once Ubuntu is working and open, you'll be asked to create a new UNIX username and password. This doesn't have to match your Windows username and password, but do make sure to save this information somewhere secure. -.. _windows-docs-ubuntu-utilities: +(windows-docs-ubuntu-utilities)= ### Install utilities Enter the following commands **into your Ubuntu terminal** to install any missing utilities we need (the `which ... ||` should make it so that no installation happens if you already have it): @@ -53,7 +54,7 @@ which git-lfs || sudo apt-get -y install git-lfs which wslview || sudo apt-get -y install wslu ``` -.. _container-or-conda-windows: +(container-or-conda-windows)= ### Install container software or Conda environment @@ -81,9 +82,9 @@ docker run hello-world You may not be able to install Docker or any other containerization software, so there is an alternative method: a Conda environment. 1. Check whether you already have Conda installed by doing `which conda`. If that doesn't print anything, [install Miniconda](https://www.anaconda.com/docs/getting-started/miniconda/install#linux). -1. Follow the instructions for setting up the `ctsm_pylib` Conda environment in Sect. :numref:`using-ctsm-pylib`. +1. Follow the instructions for setting up the `ctsm_pylib` Conda environment in Sect. {numref}`using-ctsm-pylib`. -.. _editing-text-files-wsl: +(editing-text-files-wsl)= ### Editing documentation files If you prefer using an old-school text editor like `vim`, it's probably already installed in your Ubuntu VM, or can be installed with `sudo apt-get -y install EDITOR_NAME`. If you prefer a more user-friendly interface, there are several options. Note that **all commands in this section are to be run in your Ubuntu VM, not a Windows terminal**. @@ -138,12 +139,13 @@ You may see this warning in a dialog box after trying to open a file with `wslvi ## Building docs on Windows (Ubuntu VM) Open a WSL terminal window and navigate to your CTSM checkout. Then do: -.. mdinclude:: embed-build-cmd.md +```{include} embed-build-cmd.md +``` -See :ref:`container-or-conda-windows` for more information on those two methods. +See {ref}`container-or-conda-windows` for more information on those two methods. ## Previewing docs on Windows (Ubuntu VM) -Assuming you installed the WSL Utilities in the :ref:`windows-docs-ubuntu-utilities` setup step, you can open your build of the documentation like so: +Assuming you installed the WSL Utilities in the {ref}`windows-docs-ubuntu-utilities` setup step, you can open your build of the documentation like so: ```shell wslview _build/html/index.html ``` @@ -153,4 +155,5 @@ explorer.exe $(wslpath -w _build/html/index.html) ``` These both do the same thing, but the `wslview` method is simpler. Either way, at least the first time you do this, it will open a window asking which app you'd like to view the HTML file in. Choose a browser like Microsoft Edge or Chrome. At the bottom of the window, you can then choose whether you always want to open HTML files using the selected app or just this once. -.. mdinclude:: embed-preview-menu.md +```{include} embed-preview-menu.md +``` 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 b8774b23d1..cc52558b1f 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 @@ -1,10 +1,9 @@ -.. _building-docs-original-wiki: +(building-docs-original-wiki)= # ⚠️ Original docs documentation from the GitHub Wiki -.. warning:: - - ⚠️⚠️⚠️WARNING⚠️⚠️⚠️ - 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`. +```{warning} + 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`. +``` 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/common-docs-errors.md b/doc/source/users_guide/working-with-documentation/common-docs-errors.md index 2403d79953..746b470f2b 100644 --- a/doc/source/users_guide/working-with-documentation/common-docs-errors.md +++ b/doc/source/users_guide/working-with-documentation/common-docs-errors.md @@ -1,27 +1,28 @@ -.. _common-docs-errors: +(common-docs-errors)= # Common doc build errors and how to handle them -.. contents:: - :depth: 2 - :local: +```{contents} +:depth: 2 +:local: +``` -.. _common-doc-builder-errors: +(common-doc-builder-errors)= ## Common docs errors: doc-builder ### "RuntimeError: No compatible container software found: docker, podman" You tried to build the documentation using our container (`./build_docs ... -d`) but didn't have any software running that could handle the container. Try again after starting up container software according to the instructions for your platform: -- :ref:`bld-prev-docs-casper` **(recommended)** -- :ref:`bld-prev-docs-mac` -- :ref:`bld-prev-docs-windows` +- {ref}`bld-prev-docs-casper` **(recommended)** +- {ref}`bld-prev-docs-mac` +- {ref}`bld-prev-docs-windows` -.. _common-rst-errors: +(common-rst-errors)= ## Common docs errors: reStructuredText -.. _error-unexpected-unindent: +(error-unexpected-unindent)= ### "ERROR: Unexpected indentation" @@ -126,9 +127,9 @@ Directives require a blank line between the directive header (and any options) a ### "WARNING: Block quote ends without a blank line; unexpected unindent" -This is essentially the inverse of :ref:`error-unexpected-unindent`: The above line was indented but this one isn't. reStructuredText tried to interpret the indented line as a [block quote](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks), but block quotes require a blank line after them. +This is essentially the inverse of {ref}`error-unexpected-unindent`: The above line was indented but this one isn't. reStructuredText tried to interpret the indented line as a [block quote](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks), but block quotes require a blank line after them. -.. _inline-literal-start-without-end: +(inline-literal-start-without-end)= ### "WARNING: Inline literal start-string without end-string" @@ -145,7 +146,7 @@ This might happen, for example, if you try to put a [Markdown code block](https: ### "WARNING: Inline interpreted text or phrase reference start-string without end-string" -Like :ref:`inline-literal-start-without-end`, this is probably related to having one double-backtick without another on the same line. As with that other error, it could be the result of a Markdown code block in a .rst file. +Like {ref}`inline-literal-start-without-end`, this is probably related to having one double-backtick without another on the same line. As with that other error, it could be the result of a Markdown code block in a .rst file. ### "ERROR: Error in "code" directive: maximum 1 argument(s) allowed, 19 supplied" @@ -175,14 +176,14 @@ You might have forgotten the empty line after an equation label. You might have forgotten the leading spaces for every line after `.. math::`. As a reminder, you need at least one leading space on each line. -You can also get this error if you forget to surround a :ref:`cross-reference label` with blank lines. In this case, the error message might point to lines far away from the actual problem. +You can also get this error if you forget to surround a {ref}`cross-reference label` with blank lines. In this case, the error message might point to lines far away from the actual problem. ### "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 (b) a section. ### "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. +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" diff --git a/doc/source/users_guide/working-with-documentation/docs-intro.md b/doc/source/users_guide/working-with-documentation/docs-intro.md index 87b211959d..01fc8deb36 100644 --- a/doc/source/users_guide/working-with-documentation/docs-intro.md +++ b/doc/source/users_guide/working-with-documentation/docs-intro.md @@ -1,15 +1,15 @@ -.. _docs-intro: +(docs-intro)= # Working with the CTSM documentation If you're reading this page, you're probably interested in making an improvement to this CTSM documentation website—thank you! Please read this page thoroughly before starting to make it as smooth a process as possible. ## How the documentation works -The documentation starts life as 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. +The documentation starts life as 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. During the "build" process, these files are converted to HTML webpages using a tool called Sphinx. This creates a directory with HTML files that can then be "previewed" to make sure they look right. When you submit a pull request (PR; see [Contribution guidelines](#docs-contribution-guidelines) below), tests will automatically run to make sure your changed documentation builds with no errors. Then, when your PR is merged to the main CTSM branch, it will be rebuilt and published automatically. -.. _docs-contribution-guidelines: +(docs-contribution-guidelines)= ## Contribution guidelines We use the [CTSM GitHub repo](https://github.com/ESCOMP/CTSM) to track issues with the documentation and bring in changes. Please have a look at our ["How to contribute"](https://github.com/ESCOMP/CTSM/blob/master/CONTRIBUTING.md) readme for some general guidelines. @@ -18,14 +18,14 @@ If you have found a problem with the documentation but aren't able to fix it imm If you've made changes that you'd like us to bring in, you can file a [pull request](https://github.com/ESCOMP/ctsm/pulls) (PR; "New pull request" button at that link). Please try to avoid filing many small documentation PRs in a short time, as it's easier for the maintenance team if you combine similar edits into one larger PR. For example, several typo fixes in a file or across files would be a good single PR. You can also mark a PR as "draft" if you think you may be adding more to it, or if you think it's otherwise not ready for review. -Whenever you submit a documentation PR or commit new changes to one, automated testing will check the updated documentation for any errors. If you get failures, please try to diagnose and fix them; see :ref:`common-docs-errors` for tips. If you resolve the errors, add a comment on your PR saying so, and one of the CTSM software engineers will have a look. +Whenever you submit a documentation PR or commit new changes to one, automated testing will check the updated documentation for any errors. If you get failures, please try to diagnose and fix them; see {ref}`common-docs-errors` for tips. If you resolve the errors, add a comment on your PR saying so, and one of the CTSM software engineers will have a look. ## Editing the documentation First, you will need a clone of CTSM to get all the documentation files and infrastructure. Once you have that, 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). You can mix some reStructuredText into Markdown files, but generally not the other way around. For more information, see: -- :ref:`tips-for-working-with-markdown` -- :ref:`tips-for-working-with-rst` +- {ref}`tips-for-working-with-markdown` +- {ref}`tips-for-working-with-rst` We strongly recommend building and previewing the docs yourself as you're editing them, or at least before requesting review on your PR. You can find instructions for doing so here: -- :ref:`bld-prev-docs-casper` **(recommended)** -- :ref:`bld-prev-docs-mac` -- :ref:`bld-prev-docs-windows` +- {ref}`bld-prev-docs-casper` +- {ref}`bld-prev-docs-mac` +- {ref}`bld-prev-docs-windows` diff --git a/doc/source/users_guide/working-with-documentation/docs-style-guide.md b/doc/source/users_guide/working-with-documentation/docs-style-guide.md index c740f9ffbb..448481630d 100644 --- a/doc/source/users_guide/working-with-documentation/docs-style-guide.md +++ b/doc/source/users_guide/working-with-documentation/docs-style-guide.md @@ -1,4 +1,4 @@ -.. _docs-style-guide: +(docs-style-guide)= # Documentation style guide diff --git a/doc/source/users_guide/working-with-documentation/embed-build-cmd.md b/doc/source/users_guide/working-with-documentation/embed-build-cmd.md index 8f08a0c32c..25d59912e5 100644 --- a/doc/source/users_guide/working-with-documentation/embed-build-cmd.md +++ b/doc/source/users_guide/working-with-documentation/embed-build-cmd.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + ```shell cd doc ./build_docs -b _build -c -d diff --git a/doc/source/users_guide/working-with-documentation/embed-preview-menu.md b/doc/source/users_guide/working-with-documentation/embed-preview-menu.md index e3ffc45625..eed8bd709a 100644 --- a/doc/source/users_guide/working-with-documentation/embed-preview-menu.md +++ b/doc/source/users_guide/working-with-documentation/embed-preview-menu.md @@ -1 +1,5 @@ -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, see :ref:`building-docs-multiple-versions`. +--- +orphan: true +--- + +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, see {ref}`building-docs-multiple-versions`. diff --git a/doc/source/users_guide/working-with-documentation/index.rst b/doc/source/users_guide/working-with-documentation/index.rst index 41331eea67..50735b4307 100644 --- a/doc/source/users_guide/working-with-documentation/index.rst +++ b/doc/source/users_guide/working-with-documentation/index.rst @@ -15,8 +15,7 @@ Working with CTSM Documentation bld-prev-docs-windows.md docs-style-guide.md tips-for-working-with-markdown.md - tips-for-working-with-rst.md + tips-for-working-with-rst.rst common-docs-errors.md building-docs-multiple-versions.rst 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 index 9575092459..2f6e43a488 100644 --- 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 @@ -1,45 +1,59 @@ -.. _tips-for-working-with-markdown: +(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. +Markdown is great for very simple documentation files—it's much easier to write and read Markdown source than reStructuredText source. -.. _md-cross-references: +Note that our documentation build system uses the MyST Markdown parser. MyST is a special "flavor" of Markdown that has a lot of reStructuredText-like features added to it; see the guide to MyST Markdown syntax [here](https://myst-parser.readthedocs.io/en/v5.0.0/syntax/typography.html), although note that we don't include a lot of the referenced extensions. + +(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!) +You can [link to Markdown section headers](#md-cross-references) by adding a label before the header: +```markdown +(md-cross-references)= -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$`, ... +## Markdown: Cross-references ``` -We could also use :ref:`rST's syntax` like so: + +and then referring to it like `[link to section headers](#md-cross-references)`. You can also have the display text just be the title of the relevant section—e.g., [](#md-cross-references)—by doing `[](#md-cross-references)`. + +That linking syntax also works for links to [section labels in reStructuredText files](#rst-cross-references): `[reStructuredText section labels](#rst-cross-references)`. + +(md-math)= + +## Markdown: Math + +Inline math can be achieved with the typical Markdown syntax of just surrounding your expression with dollar signs. E.g., $y = mx + b$: ``` -So to render :math:`y = mx + b`, ... +E.g., $y = mx + b$: ``` -You can also use Markdown's math block syntax for big equations on their own lines: +You can also use Markdown's math block syntax for big equations on their own lines, with an optional label after the second `$$` that will give it a number and make it cross-referenceable: ``` $$ y = mx + b -$$ +$$ (my-equation-label) ``` $$ y = mx + b -$$ +$$ (my-equation-label) -However, you won't get the equation numbering or labeling that you would with the :ref:`reStructuredText math format`. +Then you can get the equation number {eq}`my-equation-label` like so: +``` +Then you can get the equation number {eq}`my-equation-label` like so: +``` ## 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. +If you want to add some text that's only visible in the documentation source file, you can put a `%` at the beginning of a line. E.g.: + +```markdown +% This will not appear on the webpage. +``` + +% This will not appear on the webpage. ## 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 +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. 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 deleted file mode 100644 index 18afbf39a6..0000000000 --- a/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.md +++ /dev/null @@ -1,93 +0,0 @@ -.. _tips-for-working-with-rst: - -# Tips for working with reStructuredText - -If you've never used reStructuredText before, you should be aware that its syntax is pretty different from anything you've ever used before. We recommend the following resources as references for the syntax: -- [Sphinx's reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) -- The [Quick reStructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html) cheat sheet - -Some especially useful bits: -- [Section headers](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections) -- [Hyperlinks](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks) -- [Callout blocks (e.g., warning, tip)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#admonitions-messages-and-warnings) - -On this page, we've compiled some supplemental information that might be helpful, including a list of common errors and their causes. - -.. contents:: - :depth: 1 - :backlinks: top - :local: - -.. _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. - -.. _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)`. - -.. _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. - - -## reStructuredText: Common error messages and how to handle them - -See :ref:`common-rst-errors`. \ No newline at end of file diff --git a/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.rst b/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.rst new file mode 100644 index 0000000000..39fb689bc2 --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.rst @@ -0,0 +1,107 @@ +.. _tips-for-working-with-rst: + +Tips for working with reStructuredText +======================================== + +If you've never used reStructuredText before, you should be aware that its syntax is pretty different from anything you've ever used before. We recommend the following resources as references for the syntax: + +- `Sphinx's reStructuredText Primer `_ +- The `Quick reStructuredText `_ cheat sheet + +Some especially useful bits: + +- `Section headers `_ +- `Hyperlinks `_ +- `Callout blocks (e.g., warning, tip) `_ + +On this page, we've compiled some supplemental information that might be helpful, including a list of common errors and their causes. + +.. contents:: + :depth: 1 + :backlinks: top + :local: + +.. _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: + +.. code-block:: 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. + +.. _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.: + +.. code-block:: reStructuredText + + 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)`. + +.. _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: + +.. code-block:: reStructuredText + + .. + 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 `_ 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: `_ 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 `_. Its `kable `_ command allows automatic conversion of R dataframes to tables in reStructuredText and other formats. + + +reStructuredText: Common error messages and how to handle them +-------------------------------------------------------------- + +See :ref:`common-rst-errors`. \ No newline at end of file From 825c0aa15fbb5bdbe59a86c0466f42261e0039f4 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 3 Apr 2026 18:05:37 -0600 Subject: [PATCH 14/17] Fix some docs tests. --- .gitmodules | 4 ++-- doc/ctsm-docs_container/Dockerfile | 2 +- doc/doc-builder | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.gitmodules b/.gitmodules index f9257f3393..77471c1c27 100644 --- a/.gitmodules +++ b/.gitmodules @@ -123,8 +123,8 @@ fxDONOTUSEurl = https://github.com/ESMCI/mpi-serial [submodule "doc-builder"] path = doc/doc-builder -url = https://github.com/ESMCI/doc-builder -fxtag = v3.0.0 +url = https://github.com/samsrabin/doc-builder +fxtag = 37e54b3eb09e525bfef4d1f52a2464c9e8f7354f 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/doc/ctsm-docs_container/Dockerfile b/doc/ctsm-docs_container/Dockerfile index e5ec2a6488..c38a384f80 100644 --- a/doc/ctsm-docs_container/Dockerfile +++ b/doc/ctsm-docs_container/Dockerfile @@ -29,4 +29,4 @@ CMD ["/bin/bash", "-l"] LABEL org.opencontainers.image.title="Container for building CTSM documentation" LABEL org.opencontainers.image.source=https://github.com/ESCOMP/CTSM -LABEL org.opencontainers.image.version="v2.0.1" +LABEL org.opencontainers.image.version="v2.0.1a" diff --git a/doc/doc-builder b/doc/doc-builder index df0cac38b8..37e54b3eb0 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit df0cac38b82d9e4066d1fd598f4b881ba831687e +Subproject commit 37e54b3eb09e525bfef4d1f52a2464c9e8f7354f From 025d55b81693237d7a75d1901c402fd18b880aec Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 3 Apr 2026 18:14:02 -0600 Subject: [PATCH 15/17] Update doc-builder to v3.0.1: Fix CTSM tests broken by MyST parser. --- .gitmodules | 4 ++-- doc/doc-builder | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitmodules b/.gitmodules index 77471c1c27..28ecf7791e 100644 --- a/.gitmodules +++ b/.gitmodules @@ -123,8 +123,8 @@ fxDONOTUSEurl = https://github.com/ESMCI/mpi-serial [submodule "doc-builder"] path = doc/doc-builder -url = https://github.com/samsrabin/doc-builder -fxtag = 37e54b3eb09e525bfef4d1f52a2464c9e8f7354f +url = https://github.com/ESMCI/doc-builder +fxtag = v3.0.1 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/doc/doc-builder b/doc/doc-builder index 37e54b3eb0..1eb3ebf46d 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 37e54b3eb09e525bfef4d1f52a2464c9e8f7354f +Subproject commit 1eb3ebf46d0d6e2a2cb2eb1ce9c25d21142634a5 From 3d0b96e74bc235d723ad2f086d61b5717d9189c0 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 3 Apr 2026 18:38:20 -0600 Subject: [PATCH 16/17] Docs docs: Add instructions for admonitions. --- .../tips-for-working-with-markdown.md | 47 ++++++++++++++++- .../tips-for-working-with-rst.rst | 51 ++++++++++++++++++- 2 files changed, 96 insertions(+), 2 deletions(-) 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 index 2f6e43a488..bb276e2557 100644 --- 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 @@ -4,7 +4,12 @@ Markdown is great for very simple documentation files—it's much easier to write and read Markdown source than reStructuredText source. -Note that our documentation build system uses the MyST Markdown parser. MyST is a special "flavor" of Markdown that has a lot of reStructuredText-like features added to it; see the guide to MyST Markdown syntax [here](https://myst-parser.readthedocs.io/en/v5.0.0/syntax/typography.html), although note that we don't include a lot of the referenced extensions. +Note that our documentation build system uses the MyST Markdown parser. MyST is a special "flavor" of Markdown that has a lot of reStructuredText-like features added to it; see the guide to MyST Markdown syntax [here](https://myst-parser.readthedocs.io/en/v5.0.0/syntax/typography.html), although note that we don't include a lot of the referenced extensions. + +```{contents} +:depth: 1 +:local: +``` (md-cross-references)= @@ -57,3 +62,43 @@ If you want to add some text that's only visible in the documentation source fil ## 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. + +## Markdown: Admonitions +[Admonitions](https://myst-parser.readthedocs.io/en/v5.0.0/syntax/admonitions.html) are rendered as special "call-out" boxes. The general syntax is: +~~~ +```{admonition} This is the title of a generic admonition + It needs a title specified. Synonyms you can put in the `{}` instead of `admonition` include `note` and `seealso`; if you use one of those, you don't need to specify a title. +``` +~~~ +```{admonition} This is the title of a generic admonition + It needs a title specified. Synonyms you can put in the `{}` instead of `admonition` include `note` and `seealso`; if you use one of those, you don't need to specify a title. +``` + +There are also a number of built-in admonition types that get their own special rendering: + +~~~ +```{attention} +The reader should pay special attention to this. Synonyms you can put in the `{}` instead of `attention` include `caution` and `warning`. +``` +~~~ +```{attention} +The reader should pay special attention to this. Synonyms you can put in the `{}` instead of `attention` include `caution` and `warning`. +``` + +~~~ +```{danger} +This tells the reader about something dangerous. You can also put `error` in the `{}` instead of `danger`. +``` +~~~ +```{danger} +This tells the reader about something dangerous. You can also put `error` in the `{}` instead of `danger`. +``` + +~~~ +```{hint} +Here's a hint. Synonyms you can put in the `{}` instead of `hint` include `important` and `tip`. +``` +~~~ +```{hint} +Here's a hint. Synonyms you can put in the `{}` instead of `hint` include `important` and `tip`. +``` diff --git a/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.rst b/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.rst index 39fb689bc2..c356064ab4 100644 --- a/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.rst +++ b/doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.rst @@ -12,7 +12,6 @@ Some especially useful bits: - `Section headers `_ - `Hyperlinks `_ -- `Callout blocks (e.g., warning, tip) `_ On this page, we've compiled some supplemental information that might be helpful, including a list of common errors and their causes. @@ -100,6 +99,56 @@ Tables defined with the `:table: directive `_. Its `kable `_ command allows automatic conversion of R dataframes to tables in reStructuredText and other formats. +reStructuredText: Admonitions (e.g., warning, tip) +-------------------------------------------------- + +`Admonitions `_ are rendered as special "call-out" boxes. The general syntax is: + +.. code-block:: reStructuredText + + .. admonition:: This is the title of a generic admonition + + It needs a title specified. Synonyms you can put in the ``{}`` instead of ``admonition`` include ``note`` and ``seealso``; if you use one of those, you don't need to specify a title. + + +.. admonition:: This is the title of a generic admonition + + It needs a title specified. Synonyms you can put in the ``{}`` instead of ``admonition`` include ``note`` and ``seealso``; if you use one of those, you don't need to specify a title. + + +There are also a number of built-in admonition types that get their own special rendering: + +.. code-block:: reStructuredText + + .. attention:: + + The reader should pay special attention to this. Synonyms you can put in the ``{}`` instead of ``attention`` include ``caution`` and ``warning``. + +.. attention:: + + The reader should pay special attention to this. Synonyms you can put in the ``{}`` instead of ``attention`` include ``caution`` and ``warning``. + +.. code-block:: reStructuredText + + .. danger:: + + This tells the reader about something dangerous. You can also put ``error`` in the ``{}`` instead of ``danger``. + +.. danger:: + + This tells the reader about something dangerous. You can also put ``error`` in the ``{}`` instead of ``danger``. + +.. code-block:: reStructuredText + + .. hint:: + + Here's a hint. Synonyms you can put in the ``{}`` instead of ``hint`` include ``important`` and ``tip``. + +.. hint:: + + Here's a hint. Synonyms you can put in the ``{}`` instead of ``hint`` include ``important`` and ``tip``. + + reStructuredText: Common error messages and how to handle them -------------------------------------------------------------- From baab89fc2fa221780e052601020a8c6d20379ef3 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 3 Apr 2026 18:42:47 -0600 Subject: [PATCH 17/17] Previewing docs on Casper with OnDemand: Need to be in home dir. --- .../working-with-documentation/bld-prev-docs-casper.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md b/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md index 992299b2ef..b138fbd195 100644 --- a/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md +++ b/doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md @@ -9,7 +9,7 @@ ## Initial Casper setup -None! This is why Casper is the recommended method for building and previewing the docs. +You don't need to install any software! This is why Casper is the recommended method for building and previewing the docs. ## Building docs on Casper Casper uses the Podman software for running containers like the one we recommend for building the CTSM documentation. Make sure it's enabled before building: `module load podman`. Then do: @@ -25,6 +25,10 @@ There are a few different ways to do this. ### Previewing docs on Casper with OnDemand +```{attention} +Your CTSM checkout will need to be in (or symlinked to) your home directory (`$HOME`) for this method to work. +``` + The simplest way to preview your built documentation on Casper is to use [NCAR's OnDemand service](https://ondemand.hpc.ucar.edu/pun/sys/dashboard). After you [open a new Casper Login VNC Desktop session](https://ondemand.hpc.ucar.edu/pun/sys/dashboard/batch_connect/sys/login_desktop_ncar/session_contexts/new), wait for it to start, then click the "Launch Casper Login VNC Desktop" button. This will open a Linux desktop in your browser. Click on the "Home" icon and navigate to your CTSM checkout, then the `doc/_build/html` directory, then open the `index.html` file. That should open it in the Linux desktop's Firefox, at which point you can browse around as usual. If you rebuild the documentation but don't see your changes updated in the webpage, and the reload button doesn't work, you may need to navigate to a different page and then come back.