From 634c7a04232073737c1b3188d6e2c05f83e804e1 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 May 2025 23:07:19 -0600 Subject: [PATCH 1/6] Point doc-builder at v2.2.6... Prefer Podman on Mac, Docker Engine elsewhere. - Use --mount instead of -v where possible (on Mac, or Ubuntu Docker). - Don't allow build_docs_to_publish with Podman except on Mac. See ESMCI/doc-builder#27. --- .gitmodules | 2 +- doc/doc-builder | 2 +- doc/testing.sh | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.gitmodules b/.gitmodules index e7b57b25e..c1414bf04 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.5 +fxtag = v2.2.6 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 08eba8322..3ab6d0697 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 08eba83221dcccdc4640425a0ce0fb0c5e040d9f +Subproject commit 3ab6d06971e508f2886f0079db37156ab93c2b07 diff --git a/doc/testing.sh b/doc/testing.sh index 701814d43..a44b6ad18 100755 --- a/doc/testing.sh +++ b/doc/testing.sh @@ -9,7 +9,7 @@ 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" ${containercli} +./build_docs_to_publish -r _build -d --site-root "$PWD/_publish" # VERSION LINKS WILL NOT RESOLVE IN _publish_container cp -a _publish "${d1}" @@ -26,10 +26,10 @@ echo "~~~~~ Make sure container version is identical to no-container version" diff -qr "${d1}" "${d2}" # Check that -r -v works -echo "~~~~~ Check that -r -v works" +echo "~~~~~ Check that -r -v works (Docker)" # Also do a custom --conf-py-path rm -rf _build_container -./build_docs -r _build_container -v latest -d ${containercli} -c --conf-py-path doc-builder/test/conf.py --static-path ../_static --templates-path ../_templates +./build_docs -r _build_container -v latest -d -c --conf-py-path doc-builder/test/conf.py --static-path ../_static --templates-path ../_templates --container-cli-tool docker # Check that Makefile method works echo "~~~~~ Check that Makefile method works" @@ -37,9 +37,9 @@ rm -rf _build make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build html # Check that -b works -echo "~~~~~ Check that -b works" +echo "~~~~~ Check that -b works (Podman)" rm -rf _build_container -./build_docs -b _build_container -d ${containercli} -c +./build_docs -b _build_container -d -c --container-cli-tool docker # Check that doc-builder tests pass # Don't run if on a GitHub runner; failing 🤷. Trust that doc-builder does this test. From 90c0b72a901c9c39ef3722a4e21f3b20ded7d00c Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 29 May 2025 10:12:39 -0600 Subject: [PATCH 2/6] Docs docs: build_docs_to_publish not supported w/ Linux Podman. --- .../building-docs-multiple-versions.rst | 2 ++ 1 file changed, 2 insertions(+) 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 bbfd42904..8b73fbaf2 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 @@ -12,6 +12,8 @@ If you'd like to try, this will generate a local site for you in ``_publish/`` a :end-before: VERSION LINKS WILL NOT RESOLVE :append: open _publish/index.html +**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 `_. + How this works -------------- From e86e83c3098d4866fbcf312efcfa18e332345a92 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 29 May 2025 10:12:49 -0600 Subject: [PATCH 3/6] Minor update to docs issue template. --- .github/ISSUE_TEMPLATE/03_documentation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/03_documentation.md b/.github/ISSUE_TEMPLATE/03_documentation.md index e674ba585..e6c3fa0ff 100644 --- a/.github/ISSUE_TEMPLATE/03_documentation.md +++ b/.github/ISSUE_TEMPLATE/03_documentation.md @@ -5,9 +5,9 @@ about: Something should be added to or fixed in the documentation --- -### What sort(s) of issue is this? +### What sort(s) of documentation issue is this? - [ ] Something is missing. -- [ ] Something is (or might be) incorrect. +- [ ] Something is (or might be) incorrect or outdated. - [ ] Something is confusing. - [ ] Something is broken. From a2143278e425930b8202aae2955518fe69b88024 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 29 May 2025 10:16:45 -0600 Subject: [PATCH 4/6] Docs docs: Note that build_docs_to_publish isn't needed to contribute. --- .../building-docs-multiple-versions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 8b73fbaf2..e28029d7f 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,7 +5,7 @@ Building multiple versions of the documentation There is a menu in the lower left of the webpage that lets readers switch between different versions of the documentation. To build a website with this menu properly set up—so that all our versions appear and all the links work—you need to use ``docs/build_docs_to_publish`` instead of ``docs/build_docs``. -If you'd like to try, this will generate a local site for you in ``_publish/`` and then open it: +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:: ../../../testing.sh :start-at: ./build_docs_to_publish From 4e96d4f5785f0697606e1b36e37b310fa4fee04b Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 29 May 2025 11:22:11 -0600 Subject: [PATCH 5/6] Docs docs: Fix open instructions. --- .../working-with-documentation/docs-intro-and-recommended.md | 4 ++-- 1 file changed, 2 insertions(+), 2 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 a6df82868..1501f8d48 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 @@ -50,13 +50,13 @@ The process for viewing your build in a web browser differs depending on what ki You can open your build of the documentation in your default browser with ```shell -open _build/index.html +open _build/html/index.html ``` ### Windows (Ubuntu VM) Assuming you installed Chromium in the :ref:`windows-docs-ubuntu-utilities` setup step, you can open your build of the documentation like so: ```shell -chromium _build/index.html & +chromium _build/html/index.html & ``` This will generate a lot of warnings in the terminal that seem to be inconsequential to our purpose here. You may need to press Ctrl-C and/or Enter a few times to clear them and return your cursor to the prompt. From f1d63ce17f05b6e2266d8e3a250fd79a30161449 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 29 May 2025 11:35:46 -0600 Subject: [PATCH 6/6] Update ChangeLog and ChangeSum. Includes ctsm5.3.049. --- doc/ChangeLog | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/ChangeSum | 2 + 2 files changed, 121 insertions(+) diff --git a/doc/ChangeLog b/doc/ChangeLog index 03dec466b..b14ed335b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,4 +1,123 @@ =============================================================== +Tag name: ctsm5.3.050 +Originator(s): samrabin (Sam Rabin) +Date: Thu May 29 11:26:21 MDT 2025 +One-line Summary: Fix Linux Podman; prefer Linux Docker; update docs docs. + +Purpose and description of changes +---------------------------------- + +- Fixes Podman builds on Ubuntu (mostly; see ESMCI/doc-builder#27) +- Docker now preferred on non-Mac systems +- Improves docs docs + +Significant changes to scientifically-supported configurations +-------------------------------------------------------------- + +Does this tag change answers significantly for any of the following physics configurations? +(Details of any changes will be given in the "Answer changes" section below.) + + [Put an [X] in the box for any configuration with significant answer changes.] + +[ ] clm6_0 + +[ ] clm5_0 + +[ ] ctsm5_0-nwp + +[ ] clm4_5 + + +Bugs fixed +---------- +List of CTSM issues fixed (include CTSM Issue # and description): +- [Issue #3163: Docs docs: Extraneous variable in a command](https://github.com/ESCOMP/CTSM/issues/3163) + +Notes of particular relevance for users +--------------------------------------- + +User's Guide section on docs updated with new instructions. + + +Notes of particular relevance for developers: +--------------------------------------------- + +Caveats for developers (e.g., code that is duplicated that requires double maintenance): +- If you're running doc/testing.sh locally, you'll need both Docker and Podman installed. + + +Testing summary: +---------------- + +All required testing happened in GitHub workflows on the PR. + + +Other details +------------- + +List any git submodules updated: doc-builder + +Pull Requests that document the changes (include PR ids): +- [Pull Request #3184: ctsm5.3.050: Doc infrastructure and docs: fixes and improvements by samsrabin](https://github.com/ESCOMP/CTSM/pull/3184) + +=============================================================== +=============================================================== +Tag name: ctsm5.3.049 +Originator(s): samrabin (Sam Rabin) +Date: Tue May 27 12:49:00 MDT 2025 +One-line Summary: Switch docs to use Podman + +Purpose and description of changes +---------------------------------- + +Updates doc-builder to a version that prefers to use podman instead of docker. Also updates documentation to instruct docs-writers to use Podman instead of Docker, along with some other improvements. + + +Significant changes to scientifically-supported configurations +-------------------------------------------------------------- + +Does this tag change answers significantly for any of the following physics configurations? +(Details of any changes will be given in the "Answer changes" section below.) + + [Put an [X] in the box for any configuration with significant answer changes.] + +[ ] clm6_0 + +[ ] clm5_0 + +[ ] ctsm5_0-nwp + +[ ] clm4_5 + + +Bugs fixed +---------- +[Remove any lines that don't apply. Remove entire section if nothing applies.] + +List of CTSM issues fixed (include CTSM Issue # and description) [one per line]: + +Notes of particular relevance for users +--------------------------------------- + +User's Guide section on docs updated with new instructions. + + +Testing summary: +---------------- + +All required testing happened in GitHub workflows on the PR. + + +Other details +------------- + +List any git submodules updated: doc-builder + +Pull Requests that document the changes (include PR ids): +- [Pull Request #3153: ctsm5.3.049: Preferentially use Podman for ctsm-docs container by samsrabin](https://github.com/ESCOMP/CTSM/pull/3153) + +=============================================================== +=============================================================== Tag name: ctsm5.3.048 Originator(s): samrabin (Sam Rabin, UCAR/TSS) Date: Mon May 26 18:30:59 MDT 2025 diff --git a/doc/ChangeSum b/doc/ChangeSum index c48dd71c1..d5ac32d2e 100644 --- a/doc/ChangeSum +++ b/doc/ChangeSum @@ -1,5 +1,7 @@ Tag Who Date Summary ============================================================================================================================ + ctsm5.3.050 samrabin 05/29/2025 Fix Linux Podman; prefer Linux Docker; update docs docs. + ctsm5.3.049 samrabin 05/27/2025 Switch docs to use Podman ctsm5.3.048 samrabin 05/26/2025 Automatically publish docs to this repo ctsm5.3.047 samrabin 05/26/2025 Merge b4b-dev to master ctsm5.3.046 rgknox 05/26/2025 For FATES set itype to ispval and a few unused variables to nan to help prevent future problems