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 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..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,13 +5,15 @@ 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 :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 -------------- 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.