From ad4bbb0f9c2e312a1b7d932d97e5c45889d3a494 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 23 May 2025 16:42:30 -0600 Subject: [PATCH 01/21] doc-builder: Add Podman support. --- .gitmodules | 4 ++-- doc/doc-builder | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitmodules b/.gitmodules index 0f6df73ea1..a7a9a7f7c9 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 = v2.1.2 +url = https://github.com/samsrabin/doc-builder +fxtag = 0a5150e4f9986146178bf0fc3314d17bd91b7f07 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 a8ddea246b..0a5150e4f9 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit a8ddea246bcffc65b053ecd9bd94c57542211982 +Subproject commit 0a5150e4f9986146178bf0fc3314d17bd91b7f07 From 158f650fadd517929db9f051e3d3e6ceb62afaa2 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 23 May 2025 17:12:18 -0600 Subject: [PATCH 02/21] Genericize "Docker" to "container" in doc-builder and tools. --- .gitmodules | 2 +- doc/ctsm-docs_container/README.md | 6 +++--- doc/doc-builder | 2 +- doc/testing.sh | 8 ++++---- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.gitmodules b/.gitmodules index a7a9a7f7c9..bf12584e1a 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/samsrabin/doc-builder -fxtag = 0a5150e4f9986146178bf0fc3314d17bd91b7f07 +fxtag = 2cd353796ea210acfbed82fdc5ca89ee774b8983 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/README.md b/doc/ctsm-docs_container/README.md index 0af0ae71c0..34a9dd09ff 100644 --- a/doc/ctsm-docs_container/README.md +++ b/doc/ctsm-docs_container/README.md @@ -3,7 +3,7 @@ This directory and its Dockerfile are used to build a Docker container for build ## Introduction -This Readme tells you how to update the ctsm-docs Docker container if a need to do so arises—for example, adding a Python module that brings new functionality in the build. After you've followed all these instructions, you will probably want to push an update to [doc-builder](https://github.com/ESMCI/doc-builder) that updates `DEFAULT_DOCKER_IMAGE` in [build_commands.py](https://github.com/ESMCI/doc-builder/blob/master/doc_builder/build_commands.py) to point to the new tag. +This Readme tells you how to update the ctsm-docs Docker container if a need to do so arises—for example, adding a Python module that brings new functionality in the build. After you've followed all these instructions, you will probably want to push an update to [doc-builder](https://github.com/ESMCI/doc-builder) that updates `DEFAULT_IMAGE` in [build_commands.py](https://github.com/ESMCI/doc-builder/blob/master/doc_builder/build_commands.py) to point to the new tag. ## Building @@ -19,7 +19,7 @@ ghcr.io/escomp/ctsm/ctsm-docs latest ab51446519a4 3 seconds ago 233M ... ``` -To test, you can tell `build_docs` to use your new version by adding `--docker-image IMAGE_ID` to your call, where in the example above `IMAGE_ID` is `ab51446519a4`. +To test, you can tell `build_docs` to use your new version by adding `--container-image IMAGE_ID` to your call, where in the example above `IMAGE_ID` is `ab51446519a4`. ## Publishing automatically @@ -36,7 +36,7 @@ The string there can technically be anything as long as (a) it starts with a low 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_DOCKER_IMAGE` in `doc_builder/build_commands.py`. Remember, **use the version number**, not "latest". +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) diff --git a/doc/doc-builder b/doc/doc-builder index 0a5150e4f9..2cd353796e 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 0a5150e4f9986146178bf0fc3314d17bd91b7f07 +Subproject commit 2cd353796ea210acfbed82fdc5ca89ee774b8983 diff --git a/doc/testing.sh b/doc/testing.sh index 9d39955fe4..4b59360000 100755 --- a/doc/testing.sh +++ b/doc/testing.sh @@ -28,8 +28,8 @@ diff -qr "${d1}" "${d2}" # Check that -r -v works echo "~~~~~ Check that -r -v works" # Also do a custom --conf-py-path -rm -rf _build_docker -./build_docs -r _build_docker -v latest -d -c --conf-py-path doc-builder/test/conf.py --static-path ../_static --templates-path ../_templates +rm -rf _build_container +./build_docs -r _build_container -v latest -d -c --conf-py-path doc-builder/test/conf.py --static-path ../_static --templates-path ../_templates # Check that Makefile method works echo "~~~~~ Check that Makefile method works" @@ -38,8 +38,8 @@ make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build html # Check that -b works echo "~~~~~ Check that -b works" -rm -rf _build_docker -./build_docs -b _build_docker -d -c +rm -rf _build_container +./build_docs -b _build_container -d -c # Check that doc-builder tests pass # Don't run if on a GitHub runner; failing 🤷. Trust that doc-builder does this test. From f485a7e0ae713e6c0bb8aae4a14ad85278f89d7e Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 23 May 2025 17:15:18 -0600 Subject: [PATCH 03/21] Rename some docs files that didn't need "docker" in their name. --- ...ocs-prereqs-docker-mac.md => building-docs-prereqs-mac.md} | 2 +- ...eqs-docker-windows.md => building-docs-prereqs-windows.md} | 2 +- .../working-with-documentation/docs-intro-and-recommended.md | 4 ++-- doc/source/users_guide/working-with-documentation/index.rst | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) rename doc/source/users_guide/working-with-documentation/{building-docs-prereqs-docker-mac.md => building-docs-prereqs-mac.md} (99%) rename doc/source/users_guide/working-with-documentation/{building-docs-prereqs-docker-windows.md => building-docs-prereqs-windows.md} (96%) diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-mac.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md similarity index 99% rename from doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-mac.md rename to doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md index 45a1f2bb96..2e4dbb5eca 100644 --- a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-mac.md +++ b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md @@ -1,4 +1,4 @@ -.. _building-docs-prereqs-docker-mac: +.. _building-docs-prereqs-mac: # Initial setup: Mac diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-windows.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md similarity index 96% rename from doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-windows.md rename to doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md index 10e62c1220..71c8fb76d3 100644 --- a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-docker-windows.md +++ b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md @@ -1,4 +1,4 @@ -.. _building-docs-prereqs-docker-windows: +.. _building-docs-prereqs-windows: # Initial setup: Windows 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 e74290f8e3..b327a6841e 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 @@ -5,8 +5,8 @@ ## One-time setup In addition to a CTSM checkout in which to work, you will need to have some software installed in order to build the documentation: -- :ref:`building-docs-prereqs-docker-mac` -- :ref:`building-docs-prereqs-docker-windows` +- :ref:`building-docs-prereqs-mac` +- :ref:`building-docs-prereqs-windows` ## Editing the documentation The CTSM documentation is built from files in the `doc/source/tech_note/` and `doc/source/users_guide/` directories. These files are written in a mixture of what are called "markup languages." You may already be familiar—for better or for worse—with the LaTeX markup language. Fortunately, our documentation is simpler than that. It was originally written entirely in [reStructuredText](http://www.sphinx-doc.org/en/stable/rest.html), and it still mostly is, as you can tell by the predominance of .rst files. However, it's also possible to write Markdown documents (.md), which is nice because it's a much simpler and more widespread format (although see :ref:`tips-for-working-with-markdown`). If you've formatted text on GitHub, for instance, you've used Markdown. diff --git a/doc/source/users_guide/working-with-documentation/index.rst b/doc/source/users_guide/working-with-documentation/index.rst index fec10dc4c9..198da612d4 100644 --- a/doc/source/users_guide/working-with-documentation/index.rst +++ b/doc/source/users_guide/working-with-documentation/index.rst @@ -10,8 +10,8 @@ Working with CTSM Documentation :maxdepth: 1 docs-intro-and-recommended.md - building-docs-prereqs-docker-mac.md - building-docs-prereqs-docker-windows.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 From 9efc3d906bbb5da71289dc8864c470ddbcf881f6 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 23 May 2025 17:29:35 -0600 Subject: [PATCH 04/21] Update docs instructions to use Podman. --- .../working-with-documentation/building-docs-prereqs-mac.md | 6 +++--- .../building-docs-prereqs-windows.md | 5 ++--- .../docs-intro-and-recommended.md | 2 +- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md index 2e4dbb5eca..56927809da 100644 --- a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md +++ b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md @@ -71,10 +71,10 @@ You should now have `conda` and an up-to-date version of `python3` available, al ## Additional requirements The remaining software you need to install depends on which documentation-building method(s) you plan to use. -### Docker (recommended) -Install Docker Desktop through the [download page on Docker's website](https://docs.docker.com/desktop/setup/install/mac-install/). (:ref:`what-kind-of-mac-chip`) +### Container (recommended) +Install Podman Desktop through the [download page on Podman's website](https://podman-desktop.io/downloads/macos). Follow the installation instructions [here](https://podman-desktop.io/docs/installation/macos-install#installing-podman-desktop-on-macos-using-dmg-file). (:ref:`what-kind-of-mac-chip`) -### Non-Docker method +### Non-container method Install Conda, if needed (see :ref:`installing-conda-for-docs`). Then follow the instructions for setting up the `ctsm_pylib` Conda environment in Sect. :numref:`using-ctsm-pylib`. diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md index 71c8fb76d3..6fbbad6173 100644 --- a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md +++ b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md @@ -17,6 +17,5 @@ Next, download and install Ubuntu (a version of Linux) via the Microsoft Store. Finally, try opening Ubuntu. If you run into an error, you may need to manually enable WSL. To do so: Open Control Panel, go to "Programs and Features," and then "Turn Windows features on or off." Check the box next to "Windows Subsystem for Linux" and click OK. -## Docker Desktop -1. Install Docker Desktop through the Microsoft Store or the [download page on Docker's website](https://docs.docker.com/desktop/setup/install/windows-install/). -1. Open Docker Desktop. In Settings > Resources > WSL, Enable Docker to work under Ubuntu. +## Podman +Follow the [installation instructions on Podman's website](https://podman.io/docs/installation#ubuntu), entering the commands into your Ubuntu terminal. 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 b327a6841e..5a98de620a 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 @@ -26,7 +26,7 @@ You will need a place to build the documentation. It's fine if that doesn't exis Your CTSM clone, from which you're building the documentation, also needs to be somewhere in your user home directory. ### Building a preview -Ensure that Docker Desktop is running. (You do not actually need to do anything in Docker Desktop; it just needs to be running. It's fine for it to be minimized or hidden.) Then all you need to do is +All you need to do is ```shell cd doc ./build_docs -b $HOME/path/to/build-dir -c -d From 4f239104226d03f17573c0f396471d86357bf7a6 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 23 May 2025 17:54:09 -0600 Subject: [PATCH 05/21] Update ctsm-docs container build instructions to use Podman. --- doc/ctsm-docs_container/README.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/doc/ctsm-docs_container/README.md b/doc/ctsm-docs_container/README.md index 34a9dd09ff..bc50011b09 100644 --- a/doc/ctsm-docs_container/README.md +++ b/doc/ctsm-docs_container/README.md @@ -7,12 +7,14 @@ This Readme tells you how to update the ctsm-docs Docker container if a need to ## Building -If you actually want to build the container, make sure Docker is running. In the Docker Desktop settings, make sure you've enabled the [`containerd` image store](https://docs.docker.com/desktop/features/containerd/), which allows multi-platform builds. Then do: +If you actually want to build the container, you will need to have Podman installed. We previously used Docker for this, but had to move away from it due to licensing issues. Note that these issues have to do specifically with Docker Desktop, which is required to get the Docker Engine on some platforms. The Docker Engine itself is open-source, so our ctsm-docs container testing and publishing workflows are fine to continue using it. We are also fine to use the Docker Engine via Podman for local builds, which is what's described here. + +One you have Podman installed, you can do: ```shell -docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/escomp/ctsm/ctsm-docs . +podman buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/escomp/ctsm/ctsm-docs . ``` -To use your new version for local testing, you'll need to tell doc-builder to use that image. Call `docker images`, which should return something like this: +To use your new version for local testing, you'll need to tell doc-builder to use that image. Call `podman images`, which should return something like this: ```shell REPOSITORY TAG IMAGE ID CREATED SIZE ghcr.io/escomp/ctsm/ctsm-docs latest ab51446519a4 3 seconds ago 233MB @@ -47,22 +49,25 @@ If you want to publish the container, you first need a [GitHub Personal Access T Once you have a PAT(C), you can authenticate in your shell session like so: -```shell - echo YOUR_PERSONAL_ACCESS_TOKEN_CLASSIC | docker login ghcr.io -u YOUR_USERNAME --password-stdin +```bash +# bash: Make it so that, in this session, commands with a leading space are not saved to terminal history +export HISTCONTROL=ignoreboth + +# Include leading spaces so that your secret PAT(C) isn't included in terminal history + echo YOUR_PERSONAL_ACCESS_TOKEN_CLASSIC | podman login ghcr.io -u YOUR_USERNAME --password-stdin ``` -The leading spaces are intended to prevent this command, which contains your secret PAT(C), from being written to your shell's history file. That at least works in bash... sometimes. To be extra safe, in bash you can do `history -c` and it will clear your entire bash history. That can be pretty disruptive, but fortunately you should only need to authenticate once. ### Tagging You'll next need to tag the image. Lots of Docker instructions tell you to use the `latest` tag, and Docker may actually do 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. -Copy the relevant image ID (see `docker images` instructions above) and tag it with your version number like so: +Copy the relevant image ID (see `podman images` instructions above) and tag it with your version number like so: ```shell -docker tag ab51446519a4 ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z +podman tag ab51446519a4 ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z ``` Push to the repo: ```shell -docker push ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z +podman push ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z ``` 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. From b7ecd99da728ec41698c83636e2f71a74cadeb35 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 23 May 2025 18:03:11 -0600 Subject: [PATCH 06/21] Point to ESMCI doc-builder v2.2.0. --- .gitmodules | 4 ++-- doc/doc-builder | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitmodules b/.gitmodules index bf12584e1a..f5347daefe 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 = 2cd353796ea210acfbed82fdc5ca89ee774b8983 +url = https://github.com/ESMCI/doc-builder +fxtag = v2.2.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/doc-builder b/doc/doc-builder index 2cd353796e..a95bf9a25b 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 2cd353796ea210acfbed82fdc5ca89ee774b8983 +Subproject commit a95bf9a25bc1bbbebd10966998a195a20869c99d From e054cdee0050a442574bf07de8a1481b6c669492 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 25 May 2025 14:29:28 -0600 Subject: [PATCH 07/21] UG: Docs prereqs Mac: Install podman with homebrew. --- .../building-docs-prereqs-mac.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md index 56927809da..6133b50033 100644 --- a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md +++ b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md @@ -63,7 +63,7 @@ If you don't have Conda yet, go on to the next section. Otherwise, continue to : ### Installing Conda We suggest installing Conda, if needed, via Miniforge: -1. [Download Miniforge](https://conda-forge.org/download/) and install it. (:ref:`what-kind-of-mac-chip`) You can also [install Miniforge via Homebrew](https://formulae.brew.sh/cask/miniforge#default), if you already have that installed. +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. @@ -72,7 +72,11 @@ You should now have `conda` and an up-to-date version of `python3` available, al The remaining software you need to install depends on which documentation-building method(s) you plan to use. ### Container (recommended) -Install Podman Desktop through the [download page on Podman's website](https://podman-desktop.io/downloads/macos). Follow the installation instructions [here](https://podman-desktop.io/docs/installation/macos-install#installing-podman-desktop-on-macos-using-dmg-file). (:ref:`what-kind-of-mac-chip`) +We use Podman to build and run our containers. The recommended way to install Podman is 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`. +1. Test your installation by doing `podman run --rm hello-world`. If it worked, you should see ASCII art of the Podman logo. ### Non-container method @@ -89,9 +93,8 @@ git --version git-lfs --version ``` -If either of those fail with "command not found," you'll need to install them. The recommended way is with [Homebrew](https://brew.sh/). +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`) -1. [Install Homebrew](https://brew.sh/), if needed. (Check using `brew --version`.) Make sure to follow the instructions for adding Homebrew to your path. (:ref:`what-kind-of-mac-chip`) 2. Use Homebrew to [install Git](https://formulae.brew.sh/formula/git#default), if needed. 3. Use Homebrew to [install Git LFS](https://formulae.brew.sh/formula/git-lfs#default), if needed. @@ -100,4 +103,10 @@ If either of those fail with "command not found," you'll need to install them. T .. _what-kind-of-mac-chip: ### What kind of chip does my Mac have? -For certain steps in this installation process, you may need to know whether your Mac has an Intel (`x86_64`) or an Apple Silicon (`arm64`) chip. If you don't know, visit Apple's [Mac computers with Apple silicon](https://support.apple.com/en-us/116943) page for instructions. \ No newline at end of file +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? +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. \ No newline at end of file From a60699eae8b5ce920d8212af0e6bc5f79edfb20b Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 25 May 2025 15:03:31 -0600 Subject: [PATCH 08/21] doc-builder: Start Podman or Docker automatically. --- .gitmodules | 2 +- doc/doc-builder | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitmodules b/.gitmodules index f5347daefe..42fbf9a7e7 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.0 +fxtag = v2.2.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 a95bf9a25b..4cabf6afa4 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit a95bf9a25bc1bbbebd10966998a195a20869c99d +Subproject commit 4cabf6afa4be51f323183932615d7b533bb643c9 From 9c83414b22fd6134e22a0a60620ee7d53cea9c2b Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 25 May 2025 15:47:32 -0600 Subject: [PATCH 09/21] Fix ctsm-docs container build/publish instructions. --- doc/ctsm-docs_container/README.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/doc/ctsm-docs_container/README.md b/doc/ctsm-docs_container/README.md index bc50011b09..bff10aada2 100644 --- a/doc/ctsm-docs_container/README.md +++ b/doc/ctsm-docs_container/README.md @@ -1,33 +1,33 @@ # The ctsm-docs container -This directory and its Dockerfile are used to build a Docker container for building the CTSM documentation. Unless you're a developer working on the container, you probably don't need to care about anything in here. +This directory and its Dockerfile are used to build a container for building the CTSM documentation. Unless you're a developer working on the container, you probably don't need to care about anything in here. ## Introduction -This Readme tells you how to update the ctsm-docs Docker container if a need to do so arises—for example, adding a Python module that brings new functionality in the build. After you've followed all these instructions, you will probably want to push an update to [doc-builder](https://github.com/ESMCI/doc-builder) that updates `DEFAULT_IMAGE` in [build_commands.py](https://github.com/ESMCI/doc-builder/blob/master/doc_builder/build_commands.py) to point to the new tag. +This Readme tells you how to update the ctsm-docs container if a need to do so arises—for example, adding a Python module that brings new functionality in the build. After you've followed all these instructions, you will probably want to push an update to [doc-builder](https://github.com/ESMCI/doc-builder) that updates `DEFAULT_IMAGE` in [build_commands.py](https://github.com/ESMCI/doc-builder/blob/master/doc_builder/build_commands.py) to point to the new tag. ## Building If you actually want to build the container, you will need to have Podman installed. We previously used Docker for this, but had to move away from it due to licensing issues. Note that these issues have to do specifically with Docker Desktop, which is required to get the Docker Engine on some platforms. The Docker Engine itself is open-source, so our ctsm-docs container testing and publishing workflows are fine to continue using it. We are also fine to use the Docker Engine via Podman for local builds, which is what's described here. -One you have Podman installed, you can do: +Once you have Podman installed, you can do: ```shell -podman buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/escomp/ctsm/ctsm-docs . +podman build --no-cache -t ctsm-docs . ``` To use your new version for local testing, you'll need to tell doc-builder to use that image. Call `podman images`, which should return something like this: ```shell -REPOSITORY TAG IMAGE ID CREATED SIZE -ghcr.io/escomp/ctsm/ctsm-docs latest ab51446519a4 3 seconds ago 233MB +REPOSITORY TAG IMAGE ID CREATED SIZE +localhost/ctsm-docs latest 6464f26339bc 22 seconds ago 241 MB ... ``` -To test, you can tell `build_docs` to use your new version by adding `--container-image IMAGE_ID` to your call, where in the example above `IMAGE_ID` is `ab51446519a4`. +To test, you can tell `build_docs` to use your new version by adding `--container-image IMAGE_ID` to your call, where in the example above `IMAGE_ID` is `6464f26339bc`. ## Publishing automatically The `docker-image-build-publish.yml` workflow makes it so that new versions of the workflow will be published to the GitHub Container Registry whenever changes to the container setup are merged to CTSM's `master` branch. This will fail (as will a similar, no-publish workflow that happens on PRs) unless you specify exactly one new version number in the Dockerfile. This version number will be used as a tag that can be referenced by, e.g., doc-builder. -Lots of Docker instructions tell you to use the `latest` tag, and indeed the workflow will add that tag automatically. However, actually _using_ `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. +Lots of container instructions tell you to use the `latest` tag, and indeed the workflow will add that tag automatically. However, actually _using_ `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. Here's where you need to specify the version number in the Dockerfile: ```docker @@ -44,6 +44,14 @@ After the new version of the container is published, you will probably want to t 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. +### 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 create ctsm-docs-manifest +podman build --platform linux/amd64,linux/arm64 --manifest ctsm-docs-manifest . +``` + ### Pushing to GitHub Container Registry If you want to publish the container, you first need a [GitHub Personal Access Token (Classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic) with the `write:packages` permissions. You can see your existing PAT(C)s [here](https://github.com/settings/tokens). If you don't have one with the right permissions, [this link](https://github.com/settings/tokens/new?scopes=write:packages) should start the setup process for you. @@ -58,16 +66,16 @@ export HISTCONTROL=ignoreboth ``` ### Tagging -You'll next need to tag the image. Lots of Docker instructions tell you to use the `latest` tag, and Docker may actually do 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, `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. Copy the relevant image ID (see `podman images` instructions above) and tag it with your version number like so: ```shell -podman tag ab51446519a4 ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z +podman tag 6464f26339bc ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z ``` Push to the repo: ```shell -podman push ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z +podman manifest push --all ctsm-docs-manifest ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z ``` 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. From 096549f488396c99267a57c57cdc25dc3926b129 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 25 May 2025 16:31:29 -0600 Subject: [PATCH 10/21] doc-builder: Various improvements. --- .gitignore | 3 ++- .gitmodules | 4 ++-- doc/doc-builder | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 0d723b2e00..4ef520757a 100644 --- a/.gitignore +++ b/.gitignore @@ -112,6 +112,7 @@ core.* *.pyc Depends -# Docs build output +# Docs build and testing output _build*/ _publish*/ +doc/.coverage diff --git a/.gitmodules b/.gitmodules index 42fbf9a7e7..d0f87b54e5 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 = v2.2.1 +url = https://github.com/samsrabin/doc-builder +fxtag = c8ddc0bf1b32e28faeb0646f2b881a27a5e69cc7 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 4cabf6afa4..c8ddc0bf1b 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 4cabf6afa4be51f323183932615d7b533bb643c9 +Subproject commit c8ddc0bf1b32e28faeb0646f2b881a27a5e69cc7 From d2ccfe9567406f20bf5e640dbd5aab6a0aec34c8 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 26 May 2025 21:54:02 -0600 Subject: [PATCH 11/21] doc-builder: Always make build dir. --- .gitmodules | 2 +- doc/doc-builder | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitmodules b/.gitmodules index d0f87b54e5..f27efd8d5a 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/samsrabin/doc-builder -fxtag = c8ddc0bf1b32e28faeb0646f2b881a27a5e69cc7 +fxtag = 02349f2ed89cbea5f71e899a833080ff4cbdf770 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 c8ddc0bf1b..02349f2ed8 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit c8ddc0bf1b32e28faeb0646f2b881a27a5e69cc7 +Subproject commit 02349f2ed89cbea5f71e899a833080ff4cbdf770 From 7d48fa1e864de06c852c5958ae7f4d960f231c74 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 26 May 2025 22:05:18 -0600 Subject: [PATCH 12/21] test-build-docs-container: Use Docker. --- .github/workflows/docs.yml | 2 +- .gitmodules | 2 +- doc/doc-builder | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index dd859acf80..3f12f6a40e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -56,4 +56,4 @@ jobs: - name: Build docs using container id: build-docs run: | - cd doc && ./build_docs -b ${PWD}/_build -c -d + cd doc && ./build_docs -b ${PWD}/_build -c -d --container-cli-tool docker diff --git a/.gitmodules b/.gitmodules index f27efd8d5a..7269dfe643 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/samsrabin/doc-builder -fxtag = 02349f2ed89cbea5f71e899a833080ff4cbdf770 +fxtag = a3d483c8a293cff8fb4b9c05739e7ad837e2e7e6 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 02349f2ed8..a3d483c8a2 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 02349f2ed89cbea5f71e899a833080ff4cbdf770 +Subproject commit a3d483c8a293cff8fb4b9c05739e7ad837e2e7e6 From 73d77218cfbbff1cf729a0ad3f2d2796e2de69af Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 26 May 2025 22:14:47 -0600 Subject: [PATCH 13/21] Always use Docker in GitHub runners. Podman has permissions trouble for some reason. --- .github/workflows/docker-image-common.yml | 2 +- .github/workflows/docs-build-and-deploy.yml | 2 +- doc/testing.sh | 11 ++++++++--- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docker-image-common.yml b/.github/workflows/docker-image-common.yml index 224e06e2dc..9c056bc2d7 100644 --- a/.github/workflows/docker-image-common.yml +++ b/.github/workflows/docker-image-common.yml @@ -87,7 +87,7 @@ jobs: - name: Build docs using container id: build-docs run: | - cd doc && ./build_docs -b ${PWD}/_build -c -d -i $IMAGE_TAG + cd doc && ./build_docs -b ${PWD}/_build -c -d --container-cli-tool docker -i $IMAGE_TAG check-version: diff --git a/.github/workflows/docs-build-and-deploy.yml b/.github/workflows/docs-build-and-deploy.yml index e293080a4a..98886698b0 100644 --- a/.github/workflows/docs-build-and-deploy.yml +++ b/.github/workflows/docs-build-and-deploy.yml @@ -51,7 +51,7 @@ jobs: run: | bin/git-fleximod update -o cd doc - ./build_docs_to_publish -d --site-root https://escomp.github.io/ctsm + ./build_docs_to_publish -d --container-cli-tool docker --site-root https://escomp.github.io/ctsm - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/doc/testing.sh b/doc/testing.sh index 4b59360000..4e818d74a1 100755 --- a/doc/testing.sh +++ b/doc/testing.sh @@ -4,12 +4,17 @@ set -x rm -rf _publish* +# For some reason, Podman has trouble on GH Actions runners, so force use of Docker +if [[ "${GITHUB_ACTION}" == "" ]]; then + containercli="--container-cli-tool docker" +fi + # Build all docs using container echo "~~~~~ Build all docs using container" # Also do a custom --conf-py-path rm -rf _build _publish d1="$PWD/_publish_container" -./build_docs_to_publish -r _build -d --site-root "$PWD/_publish" +./build_docs_to_publish -r _build -d --site-root "$PWD/_publish" ${containercli} # VERSION LINKS WILL NOT RESOLVE IN _publish_container cp -a _publish "${d1}" @@ -29,7 +34,7 @@ diff -qr "${d1}" "${d2}" echo "~~~~~ Check that -r -v works" # Also do a custom --conf-py-path rm -rf _build_container -./build_docs -r _build_container -v latest -d -c --conf-py-path doc-builder/test/conf.py --static-path ../_static --templates-path ../_templates +./build_docs -r _build_container -v latest -d ${containercli} -c --conf-py-path doc-builder/test/conf.py --static-path ../_static --templates-path ../_templates # Check that Makefile method works echo "~~~~~ Check that Makefile method works" @@ -39,7 +44,7 @@ make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build html # Check that -b works echo "~~~~~ Check that -b works" rm -rf _build_container -./build_docs -b _build_container -d -c +./build_docs -b _build_container -d ${containercli} -c # Check that doc-builder tests pass # Don't run if on a GitHub runner; failing 🤷. Trust that doc-builder does this test. From 39f7bdead636c3356dba7f7c3e84c567d06f2fe0 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 26 May 2025 22:22:48 -0600 Subject: [PATCH 14/21] Update .gitmodules to use doc-builder v2.2.2. --- .gitmodules | 4 ++-- doc/doc-builder | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitmodules b/.gitmodules index 7269dfe643..5eea7c4789 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 = a3d483c8a293cff8fb4b9c05739e7ad837e2e7e6 +url = https://github.com/ESMCI/doc-builder +fxtag = v2.2.2 fxrequired = ToplevelOptional # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESMCI/doc-builder diff --git a/doc/doc-builder b/doc/doc-builder index a3d483c8a2..4ad289d022 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit a3d483c8a293cff8fb4b9c05739e7ad837e2e7e6 +Subproject commit 4ad289d0226e7e95013db2c09263bd57cc2b0e1e From fc8167f307efd9ca1394d87267dac14d4c2accc5 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 26 May 2025 22:25:46 -0600 Subject: [PATCH 15/21] Fix testing.sh on GH runner. --- doc/testing.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/testing.sh b/doc/testing.sh index 4e818d74a1..f2ae533bfb 100755 --- a/doc/testing.sh +++ b/doc/testing.sh @@ -5,7 +5,7 @@ set -x rm -rf _publish* # For some reason, Podman has trouble on GH Actions runners, so force use of Docker -if [[ "${GITHUB_ACTION}" == "" ]]; then +if [[ "${GITHUB_ACTION}" != "" ]]; then containercli="--container-cli-tool docker" fi From 900e882f65190c7b8bc5635414b2b2ab26021774 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 26 May 2025 22:43:52 -0600 Subject: [PATCH 16/21] Update ctsm-docs image version so Workflows pass. No actual difference in contents expected. --- doc/ctsm-docs_container/Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ctsm-docs_container/Dockerfile b/doc/ctsm-docs_container/Dockerfile index 1a0ae0c9f8..6d7a8d5677 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.2" +LABEL org.opencontainers.image.version="v1.0.2b" From 7d8dbba667a94aac5302b669ca33e504b6ab3f4d Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 26 May 2025 22:50:02 -0600 Subject: [PATCH 17/21] Trying again to fix testing.sh on GH Actions runner. --- doc/testing.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/testing.sh b/doc/testing.sh index f2ae533bfb..f6c1a2a6f7 100755 --- a/doc/testing.sh +++ b/doc/testing.sh @@ -5,7 +5,7 @@ set -x rm -rf _publish* # For some reason, Podman has trouble on GH Actions runners, so force use of Docker -if [[ "${GITHUB_ACTION}" != "" ]]; then +if [[ "${GITHUB_ACTIONS}" != "" ]]; then containercli="--container-cli-tool docker" fi @@ -48,7 +48,7 @@ rm -rf _build_container # Check that doc-builder tests pass # Don't run if on a GitHub runner; failing 🤷. Trust that doc-builder does this test. -if [[ "${GITHUB_ACTION}" == "" ]]; then +if [[ "${GITHUB_ACTIONS}" == "" ]]; then echo "~~~~~ Check that doc-builder tests pass" cd doc-builder/test conda run -n ctsm_pylib make test From 70af927b8195bb8484672cc17395ecc4018e9c74 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 26 May 2025 23:05:49 -0600 Subject: [PATCH 18/21] build_docs_to_publish: Pass --container-cli-tool to build_docs. --- .gitmodules | 2 +- doc/doc-builder | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitmodules b/.gitmodules index 5eea7c4789..740b5e1495 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.2 +fxtag = v2.2.3 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 4ad289d022..4ad641bd6f 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 4ad289d0226e7e95013db2c09263bd57cc2b0e1e +Subproject commit 4ad641bd6f18007e2599ae4ef526153c8bc1154d From ff915aaadc58ee225350a340a10c5544aabfd6bc Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 27 May 2025 09:13:42 -0600 Subject: [PATCH 19/21] Update Pages links to use /CTSM instead of /ctsm. --- .github/ISSUE_TEMPLATE/03_documentation.md | 4 ++-- .github/workflows/docs-build-and-deploy.yml | 2 +- README.md | 2 +- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 ++ doc/source/users_guide/overview/introduction.rst | 2 +- .../building-docs-multiple-versions.rst | 2 +- 6 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/03_documentation.md b/.github/ISSUE_TEMPLATE/03_documentation.md index 782656e83c..e674ba585d 100644 --- a/.github/ISSUE_TEMPLATE/03_documentation.md +++ b/.github/ISSUE_TEMPLATE/03_documentation.md @@ -12,8 +12,8 @@ about: Something should be added to or fixed in the documentation - [ ] Something is broken. ### What part(s) of the documentation does this concern? -- [ ] [Technical Note](https://escomp.github.io/ctsm/tech_note/index.html) (science and design of the model) -- [ ] [User's Guide](https://escomp.github.io/ctsm/users_guide/index.html) (using the model and related tools) +- [ ] [Technical Note](https://escomp.github.io/CTSM/tech_note/index.html) (science and design of the model) +- [ ] [User's Guide](https://escomp.github.io/CTSM/users_guide/index.html) (using the model and related tools) - [ ] Somewhere else (e.g., README file, tool help text, or code comment): _Please specify_ - [ ] I don't know diff --git a/.github/workflows/docs-build-and-deploy.yml b/.github/workflows/docs-build-and-deploy.yml index 98886698b0..84764a37ee 100644 --- a/.github/workflows/docs-build-and-deploy.yml +++ b/.github/workflows/docs-build-and-deploy.yml @@ -51,7 +51,7 @@ jobs: run: | bin/git-fleximod update -o cd doc - ./build_docs_to_publish -d --container-cli-tool docker --site-root https://escomp.github.io/ctsm + ./build_docs_to_publish -d --container-cli-tool docker --site-root https://escomp.github.io/CTSM - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/README.md b/README.md index cca41e3473..5ea26566c9 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ http://www.cesm.ucar.edu/models/cesm2.0/land/ and -https://escomp.github.io/ctsm/ +https://escomp.github.io/CTSM/ For help with how to work with CTSM in git, see diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index bb0ab9eef5..b931dc8fed 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -152,6 +152,8 @@ Introduction The purpose of this document is to fully describe the biogeophysical and biogeochemical parameterizations and numerical implementation of version 5.0 of the Community Land Model (CLM5.0). Scientific justification and evaluation of these parameterizations can be found in the referenced scientific papers (:ref:`rst_References`). This document and the CLM5.0 User's Guide together provide the user with the scientific description and operating instructions for CLM. +.. _model-history: + Model History --------------- diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 3a2520c62d..deb1a3ee56 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -33,7 +33,7 @@ Developers that are making changes to CLM either for their own development or fo What is New with |version| ============================ -`What's new with |version| science `_ gives a synopsis of the changes to CLM since the CLM4.5 release. More details are given in the CLM ChangeLog files: +The :ref:`model history section ` section gives a synopsis of the changes to CLM in each release. More details are given in the CLM ChangeLog files: - `CLM 3.0 ChangeLog file `_ - `CLM 4.0 ChangeLog file `_ diff --git a/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.rst b/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.rst index 20e9481e0a..bbfd42904c 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 @@ -24,4 +24,4 @@ How this works For each member of `VERSION_LIST`, ``build_docs_to_publish`` checks out its `ref`, then builds the documentation in a build directory. (`LATEST_REF` is set because some files, folders, and submodules are important for how the build works and need to stay the same for each build.) Once the build is complete, ``build_docs_to_publish`` should reset your local repo copy (CTSM clone) to how it was before you called ``build_docs_to_publish``. -Next, ``build_docs_to_publish`` moves the HTML files from the build directory to the publish directory. The publish directory has a structure that matches the paths in the version dropdown menu's links. If a member of ``VERSION_LIST`` has ``landing_version=True``, its HTML will be at the top level. That makes it simple for people to find the default version of the docs at https://escomp.github.io/ctsm, rather than having to drill down further into something like ``https://escomp.github.io/ctsm/versions/latest``. +Next, ``build_docs_to_publish`` moves the HTML files from the build directory to the publish directory. The publish directory has a structure that matches the paths in the version dropdown menu's links. If a member of ``VERSION_LIST`` has ``landing_version=True``, its HTML will be at the top level. That makes it simple for people to find the default version of the docs at https://escomp.github.io/CTSM, rather than having to drill down further into something like ``https://escomp.github.io/CTSM/versions/latest``. From 916c535db5b28154afea4aa2aebbc8cb5cb3fd7f Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 27 May 2025 12:40:31 -0600 Subject: [PATCH 20/21] Docs docs: update Windows instructions. --- .../building-docs-prereqs-windows.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md index 6fbbad6173..dac8775baa 100644 --- a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md +++ b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md @@ -15,7 +15,11 @@ The first step is to install Windows Subsystem for Linux (WSL), if you haven't a Next, download and install Ubuntu (a version of Linux) via the Microsoft Store. -Finally, try opening Ubuntu. If you run into an error, you may need to manually enable WSL. To do so: Open Control Panel, go to "Programs and Features," and then "Turn Windows features on or off." Check the box next to "Windows Subsystem for Linux" and click OK. +Finally, try opening Ubuntu. If you run into an error, you may need to manually enable WSL. To do so: Open Control Panel, go to "Programs" > "Programs and Features" > "Turn Windows features on or off". Check the box next to "Windows Subsystem for Linux" and click OK. ## Podman -Follow the [installation instructions on Podman's website](https://podman.io/docs/installation#ubuntu), entering the commands into your Ubuntu terminal. +Follow the [installation instructions in the Ubuntu section on Podman's website](https://podman.io/docs/installation#ubuntu), entering the commands into your Ubuntu terminal: +```shell +sudo apt-get update +sudo apt-get -y install podman +``` From 4d3becbca4e1c6dc6315abe2dcdaa0d66d2a3381 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 27 May 2025 12:43:11 -0600 Subject: [PATCH 21/21] Workflows: Add comment about Podman trouble on GitHub runners. --- .github/workflows/docker-image-common.yml | 2 +- .github/workflows/docs.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docker-image-common.yml b/.github/workflows/docker-image-common.yml index 9c056bc2d7..8e2a38b32f 100644 --- a/.github/workflows/docker-image-common.yml +++ b/.github/workflows/docker-image-common.yml @@ -84,7 +84,7 @@ jobs: id: set-image-tag run: | echo "IMAGE_TAG=$(echo '${{ steps.meta.outputs.tags }}' | head -n 1 | cut -d',' -f1)" >> $GITHUB_ENV - - name: Build docs using container + - name: Build docs using Docker (Podman has trouble on GitHub runners) id: build-docs run: | cd doc && ./build_docs -b ${PWD}/_build -c -d --container-cli-tool docker -i $IMAGE_TAG diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3f12f6a40e..3137d31f5c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -53,7 +53,7 @@ jobs: run: | bin/git-fleximod update doc-builder - - name: Build docs using container + - name: Build docs using Docker (Podman has trouble on GitHub runners) id: build-docs run: | cd doc && ./build_docs -b ${PWD}/_build -c -d --container-cli-tool docker