diff --git a/.github/workflows/docker-image-build-publish.yml b/.github/workflows/docker-image-build-publish.yml new file mode 100644 index 0000000000..b52be7f031 --- /dev/null +++ b/.github/workflows/docker-image-build-publish.yml @@ -0,0 +1,83 @@ +# Based on https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#publishing-a-package-using-an-action (last accessed 2025-05-09) +name: Build and publish ctsm-docs Docker image + +on: + # Run this whenever something gets pushed to master + push: + branches: ['master'] + paths: + - 'doc/ctsm-docs_container/Dockerfile' + - 'doc/ctsm-docs_container/requirements.txt' + + # Run this whenever it's manually called + workflow_dispatch: + +jobs: + # This first job checks that the container can be built, and that we can use it to build the docs without error. + build-image-and-test-docs: + name: Build image and test docs + uses: ./.github/workflows/docker-image-common.yml + secrets: inherit + + # This second job actually builds and publishes the container. + push-and-attest: + name: Publish and attest + runs-on: ubuntu-latest + + # Wait to run this job until after build-image-and-test-docs. If that job fails, something might be wrong with the container, so don't try this one. (It might also have failed because of something wrong with doc-builder or the documentation.) + needs: build-image-and-test-docs + + # Variables output by the build-image-and-test-docs job. + env: + REGISTRY: ${{ needs.build-image-and-test-docs.outputs.REGISTRY }} + IMAGE_NAME: ${{ needs.build-image-and-test-docs.outputs.IMAGE_NAME }} + IMAGE_TAG: ${{ needs.build-image-and-test-docs.outputs.image_tag }} + + # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job. + permissions: + contents: read + packages: write + attestations: write + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + # Uses the `docker/login-action` action to log in to the Container registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here. + - name: Log in to the Container registry + uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + # This step sets up Docker Buildx, which is needed for the multi-platform build in the next step + # https://docs.docker.com/build/ci/github-actions/multi-platform/ + # v3.1.0 + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 + + # This step uses the `docker/build-push-action` action to build the image, based on the ctsm-docs `Dockerfile`. + # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository. + # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step. + # v6.15.0 + - name: Push Docker image + id: push + uses: docker/build-push-action@471d1dc4e07e5cdedd4c2171150001c434f0b7a4 + with: + context: doc/ctsm-docs_container + platforms: linux/amd64,linux/arm64 + push: true + load: false + tags: ${{ env.IMAGE_TAG }} + labels: "" + + # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see [Using artifact attestations to establish provenance for builds](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds). + - name: Generate artifact attestation + uses: actions/attest-build-provenance@v2 + with: + subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + subject-digest: ${{ steps.push.outputs.digest }} + push-to-registry: true + diff --git a/.github/workflows/docker-image-build.yml b/.github/workflows/docker-image-build.yml new file mode 100644 index 0000000000..e013b888a7 --- /dev/null +++ b/.github/workflows/docker-image-build.yml @@ -0,0 +1,25 @@ +# Modified from https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#publishing-a-package-using-an-action (last accessed 2025-05-09) +name: Test building ctsm-docs Docker image and using it to build the docs + +# Configures this workflow to run every time a change in the Docker container setup is pushed to the master branch +on: + push: + paths: + - 'doc/ctsm-docs_container/**' + - '.github/workflows/docker-image-ctsm-docs-build.yml' + - '.github/workflows/docker-image-build-common.yml' + + pull_request: + paths: + - 'doc/ctsm-docs_container/**' + - '.github/workflows/docker-image-ctsm-docs-build.yml' + - '.github/workflows/docker-image-build-common.yml' + + workflow_dispatch: + +# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu. +jobs: + build-image-and-test-docs: + name: Build image and test docs + uses: ./.github/workflows/docker-image-common.yml + secrets: inherit diff --git a/.github/workflows/docker-image-common.yml b/.github/workflows/docker-image-common.yml new file mode 100644 index 0000000000..40cbd90ac3 --- /dev/null +++ b/.github/workflows/docker-image-common.yml @@ -0,0 +1,83 @@ +name: Workflow used by docker-image workflows + +on: + workflow_call: + outputs: + REGISTRY: + description: "Container registry" + value: ${{ jobs.build-image-and-test-docs.outputs.REGISTRY }} + IMAGE_NAME: + description: "Docker image name" + value: ${{ jobs.build-image-and-test-docs.outputs.IMAGE_NAME }} + image_tag: + description: "First image tag" + value: ${{ jobs.build-image-and-test-docs.outputs.image_tag }} + +# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds. +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }}/ctsm-docs + +# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu. +jobs: + build-image-and-test-docs: + runs-on: ubuntu-latest + # Variables that might be needed by the calling workflow + outputs: + REGISTRY: ${{ env.REGISTRY }} + IMAGE_NAME: ${{ env.IMAGE_NAME }} + image_tag: ${{ steps.set-image-tag.outputs.IMAGE_TAG }} + # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job. + permissions: + contents: read + packages: write + attestations: write + id-token: write + + steps: + + - name: Checkout repository + uses: actions/checkout@v4 + + # Uses the `docker/login-action` action to log in to the Container registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here. + - name: Log in to the Container registry + uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels. + - name: Extract metadata (tags, labels) for Docker + id: meta + uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + + # This step uses the `docker/build-push-action` action to build the image, based on the ctsm-docs `Dockerfile`. + # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository. + # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step. + # v6.15.0 + - name: Build Docker image + id: build-image + uses: docker/build-push-action@471d1dc4e07e5cdedd4c2171150001c434f0b7a4 + with: + context: doc/ctsm-docs_container + push: false + load: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + + # Try building our docs using the new container + - name: Checkout doc-builder external + run: | + bin/git-fleximod update doc-builder + - name: Set image tag for docs build + id: set-image-tag + run: | + echo "IMAGE_TAG=$(echo '${{ steps.meta.outputs.tags }}' | cut -d',' -f1)" >> $GITHUB_ENV + echo "IMAGE_TAG=$(echo '${{ steps.meta.outputs.tags }}' | cut -d',' -f1)" >> $GITHUB_OUTPUT + - name: Build docs using container + id: build-docs + run: | + cd doc && ./build_docs -b ${PWD}/_build -c -d -i $IMAGE_TAG diff --git a/.github/workflows/docs-common.yml b/.github/workflows/docs-common.yml new file mode 100644 index 0000000000..6dd8f7d53b --- /dev/null +++ b/.github/workflows/docs-common.yml @@ -0,0 +1,78 @@ +name: Jobs shared by docs workflows + +on: + workflow_call: + inputs: + use_conda: + required: false + type: boolean + default: false + conda_env_file: + required: false + type: string + default: "" + conda_env_name: + required: false + type: string + default: "" + secrets: {} + +jobs: + build-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + lfs: true + + - name: Checkout doc-builder external + run: | + bin/git-fleximod update doc-builder + + # Do this if not using conda + # Based on https://github.com/actions/cache/blob/main/examples.md#python---pip + - name: Install python + if: ${{ ! inputs.use_conda }} + uses: actions/setup-python@v2 + with: + python-version: '3.13.2' # needs to be coordinated with version in python/conda_env_ctsm_py.txt + - name: Cache pip + if: ${{ ! inputs.use_conda }} + uses: actions/cache@v3 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('doc/ctsm-docs_container/requirements.txt') }} + restore-keys: | + ${{ runner.os }}-pip- + - name: Install Python requirements + if: ${{ ! inputs.use_conda }} + run: | + pip install -r doc/ctsm-docs_container/requirements.txt + + # Do this if using conda + - name: Set up conda environment + if: ${{ inputs.use_conda }} + uses: conda-incubator/setup-miniconda@v3 + with: + activate-environment: ${{ inputs.conda_env_name }} + environment-file: ${{ inputs.conda_env_file }} + channels: conda-forge + auto-activate-base: false + + - name: Build Sphinx docs with makefile + run: | + if ${{ inputs.use_conda }}; then + conda run -n ${{ inputs.conda_env_name }} make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build -C doc/ html + else + make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build -C doc/ html + fi + + - name: Build Sphinx docs with doc-builder + if: success() || failure() + run: | + if ${{ inputs.use_conda }}; then + cd doc && conda run -n ${{ inputs.conda_env_name }} ./build_docs -b ${PWD}/_build -c + else + cd doc && ./build_docs -b ${PWD}/_build -c + fi diff --git a/.github/workflows/docs-ctsm_pylib.issue_template.md b/.github/workflows/docs-ctsm_pylib.issue_template.md new file mode 100644 index 0000000000..dfeafd5b66 --- /dev/null +++ b/.github/workflows/docs-ctsm_pylib.issue_template.md @@ -0,0 +1,6 @@ +--- +title: Scheduled ctsm_pylib docs build test failed +assignees: samsrabin +labels: bug, next +--- +{{ date }}: A failure occurred during the most recent run of the `test-build-docs-ctsm_pylib` job in `.github/workflows/docs-ctsm_pylib.yml`. diff --git a/.github/workflows/docs-ctsm_pylib.yml b/.github/workflows/docs-ctsm_pylib.yml new file mode 100644 index 0000000000..e4efc973a2 --- /dev/null +++ b/.github/workflows/docs-ctsm_pylib.yml @@ -0,0 +1,49 @@ +name: Test building docs with ctsm_pylib + +on: + push: + paths: + - 'python/conda_env_ctsm_py.txt' + + pull_request: + paths: + - 'python/conda_env_ctsm_py.txt' + + schedule: + # 8 am every Monday UTC + - cron: '0 8 * * 1' + + workflow_dispatch: + +permissions: + contents: read +jobs: + test-build-docs-ctsm_pylib: + if: ${{ always() }} + name: With ctsm_pylib + uses: ./.github/workflows/docs-common.yml + with: + use_conda: true + conda_env_file: python/conda_env_ctsm_py.yml + conda_env_name: ctsm_pylib + + # File an issue if the docs build failed during a scheduled run + file-issue-on-failure: + if: | + failure() && + github.event_name == 'schedule' + needs: test-build-docs-ctsm_pylib + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Create issue + uses: JasonEtco/create-an-issue@1b14a70e4d8dc185e5cc76d3bec9eab20257b2c5 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + filename: .github/workflows/docs-ctsm_pylib.issue_template.md + update_existing: true + search_existing: open + + diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..8cc1b7c7c2 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,42 @@ +name: Test building docs when they're updated +# Does not include a test of building docs with ctsm_pylib; that's in a different Workflow because we only want it to run when ctsm_pylib is updated. + +on: + push: + paths: + - 'doc/**' + + pull_request: + paths: + - 'doc/**' + + workflow_dispatch: + +permissions: + contents: read +jobs: + + test-build-docs: + if: ${{ always() }} + name: Without ctsm_pylib or container + uses: ./.github/workflows/docs-common.yml + with: + use_conda: false + + test-build-docs-container: + if: ${{ always() }} + name: With container from registry + runs-on: ubuntu-latest + steps: + + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Checkout doc-builder external + run: | + bin/git-fleximod update doc-builder + + - name: Build docs using container + id: build-docs + run: | + cd doc && ./build_docs -b ${PWD}/_build -c -d diff --git a/.gitignore b/.gitignore index 7c74c9d8ca..278c0957f0 100644 --- a/.gitignore +++ b/.gitignore @@ -110,3 +110,7 @@ core.* *.log !run.log *.pyc Depends + +# Docs build output +_build*/ + diff --git a/.gitmodules b/.gitmodules index 9517410b54..0310b9efd9 100644 --- a/.gitmodules +++ b/.gitmodules @@ -68,7 +68,7 @@ fxDONOTUSEurl = https://github.com/ESCOMP/mizuRoute [submodule "ccs_config"] path = ccs_config url = https://github.com/ESMCI/ccs_config_cesm.git -fxtag = ccs_config_cesm1.0.20 +fxtag = ccs_config_cesm1.0.23 fxrequired = ToplevelRequired # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESMCI/ccs_config_cesm.git @@ -76,7 +76,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/ccs_config_cesm.git [submodule "cime"] path = cime url = https://github.com/ESMCI/cime -fxtag = cime6.1.59 +fxtag = cime6.1.72 fxrequired = ToplevelRequired # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESMCI/cime @@ -84,7 +84,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/cime [submodule "cmeps"] path = components/cmeps url = https://github.com/ESCOMP/CMEPS.git -fxtag = cmeps1.0.33 +fxtag = cmeps1.0.39 fxrequired = ToplevelRequired # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESCOMP/CMEPS.git @@ -100,7 +100,7 @@ fxDONOTUSEurl = https://github.com/ESCOMP/CDEPS.git [submodule "share"] path = share url = https://github.com/ESCOMP/CESM_share -fxtag = share1.1.8 +fxtag = share1.1.9 fxrequired = ToplevelRequired # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESCOMP/CESM_share @@ -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 = v1.0.8 +fxtag = v2.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/bld/CLMBuildNamelist.pm b/bld/CLMBuildNamelist.pm index 400c831b73..6cd11084fe 100755 --- a/bld/CLMBuildNamelist.pm +++ b/bld/CLMBuildNamelist.pm @@ -2190,11 +2190,8 @@ sub setup_logic_snow { my ($opts, $nl_flags, $definition, $defaults, $nl) = @_; add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snow_thermal_cond_method' ); - - my $var = $nl->get_value('snow_thermal_cond_method'); - if ( $var ne "'Jordan1991'" && $var ne "'Sturm1997'" ) { - $log->fatal_error("$var is incorrect entry for the namelist variable snow_thermal_cond_method; expected Jordan1991 or Sturm1997"); - } + add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snow_thermal_cond_glc_method' ); + add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'snow_thermal_cond_lake_method' ); my $numrad_snw = $nl->get_value('snicar_numrad_snw'); add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'fsnowoptics', diff --git a/bld/namelist_files/namelist_defaults_ctsm.xml b/bld/namelist_files/namelist_defaults_ctsm.xml index f3b0fd8d0c..7adb380a61 100644 --- a/bld/namelist_files/namelist_defaults_ctsm.xml +++ b/bld/namelist_files/namelist_defaults_ctsm.xml @@ -484,6 +484,14 @@ attributes from the config_cache.xml file (with keys converted to upper-case). Jordan1991 Sturm1997 + +Jordan1991 +Sturm1997 + + +Jordan1991 +Jordan1991 + diff --git a/ccs_config b/ccs_config index 77fd32c6c4..c1f57b1db9 160000 --- a/ccs_config +++ b/ccs_config @@ -1 +1 @@ -Subproject commit 77fd32c6c4b57bb195239753f4c7838f05c1dfe8 +Subproject commit c1f57b1db90529fdc3766777103c8d6a9cd4ccb2 diff --git a/cime b/cime index addf9e67ce..71d2b71216 160000 --- a/cime +++ b/cime @@ -1 +1 @@ -Subproject commit addf9e67ceeb0e056de33ee793d67491176dd3a5 +Subproject commit 71d2b71216cc39abfb8224cc55861bd6424c95f9 diff --git a/cime_config/config_archive.xml b/cime_config/config_archive.xml index e78861e451..c219a1d1ef 100644 --- a/cime_config/config_archive.xml +++ b/cime_config/config_archive.xml @@ -8,14 +8,12 @@ e locfnh - rpointer.lnd$NINST_STRING.$DATENAME + rpointer.lnd$NINST_STRING ./$CASE.clm2$NINST_STRING.r.$DATENAME.nc - rpointer.lnd.1976-01-01-00000 - rpointer.lnd_9999.1976-01-01-00000 - rpointer.lnd.0000-01-01-00000 - rpointer.lnd_9999.1976-01-03-00000 + rpointer.lnd + rpointer.lnd_9999 casename.clm2.r.1976-01-01-00000.nc casename.clm2.rh4.1976-01-01-00000.nc casename.clm2.h0.1976-01-01-00000.nc @@ -34,14 +32,12 @@ e locfnh - rpointer.lnd$NINST_STRING.$DATENAME + rpointer.lnd$NINST_STRING ./$CASE.ctsm$NINST_STRING.r.$DATENAME.nc - rpointer.lnd.1976-01-01-00000 - rpointer.lnd_9999.1976-01-01-00000 - rpointer.lnd.0000-01-01-00000 - rpointer.lnd_9999.1976-01-03-00000 + rpointer.lnd + rpointer.lnd_9999 casename.ctsm.r.1976-01-01-00000.nc casename.ctsm.rh4.1976-01-01-00000.nc casename.ctsm.h0.1976-01-01-00000.nc diff --git a/components/cmeps b/components/cmeps index 4b636c6f79..189b02e2b3 160000 --- a/components/cmeps +++ b/components/cmeps @@ -1 +1 @@ -Subproject commit 4b636c6f794ca02d854d15c620e26644751b449b +Subproject commit 189b02e2b36b9a5a064150179721de45af3bbacf diff --git a/doc/ChangeLog b/doc/ChangeLog index f94a553685..e594c688a0 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,4 +1,79 @@ =============================================================== +Tag name: ctsm5.3.043 +Originator(s): slevis (Samuel Levis,UCAR/TSS,303-665-1310) +Date: Fri 09 May 2025 12:28:17 PM MDT +One-line Summary: Merge b4b-dev + +Purpose and description of changes +---------------------------------- + + Updates to the b4b-dev branch since its last merge to master (PRs #3091 #3092), as shown by git log: + + - Merge pull request Update docs infrastructure #2809 from samsrabin/update-docs-builder-2 + Update docs infrastructure + - Merge pull request Update externals to cesm3_0_alpha06c #3106 from ekluzek/update_to_alpha06c + Update externals to cesm3_0_alpha06c + - Merge pull request User control over snow thermal conductivity scheme over glaciers #3072 from wwieder/JordanGlacier + User control over snow thermal conductivity scheme over glaciers + +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) [one per line]: +Resolves #2818 Update doc-builder +Resolves #3098 st-archive issues in ctsm5.3.041 +Resolves #3071 Opt to use Jordan1991 over glacier land +Resolves #3080 Lake snow thermal conductivity hard coded to Jordan + +Notes of particular relevance for users +--------------------------------------- +Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables): + Introduce user control over snow thermal conductivity scheme over glaciers + +Changes to documentation: + #2809 updates docs infrastructure + +Testing summary: +---------------- + + [PASS means all tests PASS; OK means tests PASS other than expected fails.] + + regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing): + + derecho ----- OK + izumi ------- OK + +Answer changes +-------------- + +Changes answers relative to baseline: No + +Other details +------------- +List any git submodules updated (cime, rtm, mosart, cism, fates, etc.): + #3106 updates submodules to cesm3_0_alpha06c + +Pull Requests that document the changes (include PR ids): + https://github.com/ESCOMP/ctsm/pull/3123 + +=============================================================== +=============================================================== Tag name: ctsm5.3.042 Originator(s): glemieux (Gregory Lemieux, LBNL, glemieux@lbl.gov) Date: Thu May 8 16:15:48 MDT 2025 diff --git a/doc/ChangeSum b/doc/ChangeSum index e0fe92e5aa..e805a39512 100644 --- a/doc/ChangeSum +++ b/doc/ChangeSum @@ -1,5 +1,6 @@ Tag Who Date Summary ============================================================================================================================ + ctsm5.3.043 slevis 05/09/2025 Merge b4b-dev ctsm5.3.042 glemieux 05/08/2025 Update FATES tag, tests and address namelist option bug ctsm5.3.041 samrabin 04/25/2025 Merge b4b-dev to master ctsm5.3.040 samrabin 04/15/2025 Update ctsm_pylib to 3.13.2 diff --git a/doc/Makefile b/doc/Makefile index 49e9764b7a..7e74b6e545 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -17,7 +17,7 @@ help: # have configured this repository (via an .lfsconfig file at the top level) to NOT # automatically fetch any of the large files when cloning / fetching. fetch-images: - git lfs install + git lfs install --force git lfs pull --exclude="" --include="" .PHONY: help fetch-images Makefile diff --git a/doc/build_docs b/doc/build_docs index 45c7099ec5..89434622a6 100755 --- a/doc/build_docs +++ b/doc/build_docs @@ -1,10 +1,15 @@ #!/usr/bin/env bash +set -e -if [ -f doc-builder/build_docs ]; then - echo "Running: make fetch-images" - make fetch-images - echo "Running: ./doc-builder/build_docs $@" - ./doc-builder/build_docs "$@" -else - echo "Obtain doc-builder by running './bin/git-fleximod update --optional' from the top-level" +if [ ! -f doc-builder/build_docs ]; then + script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" + ${script_dir}/../bin/git-fleximod update doc-builder fi + +echo "Running: make fetch-images" +make fetch-images + +echo "Running: ./doc-builder/build_docs $@" +./doc-builder/build_docs "$@" + +exit 0 \ No newline at end of file diff --git a/doc/ctsm-docs_container/Dockerfile b/doc/ctsm-docs_container/Dockerfile new file mode 100644 index 0000000000..90e3a6160e --- /dev/null +++ b/doc/ctsm-docs_container/Dockerfile @@ -0,0 +1,31 @@ +################################################################### +# A base linux install + packages for building CTSM documentation # +################################################################### + +FROM python:3.13.2-alpine + +# Update the default packages and install some other necessary ones +RUN apk update +RUN apk add --no-cache git sudo +RUN apk add --no-cache git-lfs +RUN apk add --no-cache make +ADD requirements.txt requirements.txt +RUN pip3 install --break-system-packages -r requirements.txt + +# Add user etc. +RUN addgroup escomp +RUN adduser -h /home/user -G escomp -s /bin/bash -D user +RUN echo 'export USER=$(whoami)' >> /etc/profile.d/escomp.sh +RUN echo 'export PS1="[\u@escomp \W]\$ "' >> /etc/profile.d/escomp.sh +RUN echo 'user ALL=(ALL) NOPASSWD: ALL' >> /etc/sudoers.d/escomp + +ENV SHELL=/bin/bash \ + LANG=C.UTF-8 \ + LC_ALL=C.UTF-8 + +USER user +WORKDIR /home/user +CMD ["/bin/bash", "-l"] + +LABEL org.opencontainers.image.title="Container for building CTSM documentation" +LABEL org.opencontainers.image.source=https://github.com/ESCOMP/CTSM \ No newline at end of file diff --git a/doc/ctsm-docs_container/README.md b/doc/ctsm-docs_container/README.md new file mode 100644 index 0000000000..bdd4eb3fa7 --- /dev/null +++ b/doc/ctsm-docs_container/README.md @@ -0,0 +1,57 @@ +# 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. + +## 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. + +## 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 [`continerd` image store](https://docs.docker.com/desktop/features/containerd/), which allows multi-platform builds. Then do: +```shell +docker 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: +```shell +REPOSITORY TAG IMAGE ID CREATED SIZE +ghcr.io/escomp/ctsm/ctsm-docs latest ab51446519a4 3 seconds ago 233MB +... +``` + +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`. + +## Publishing + +### 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. + +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 +``` +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 the session's history entirely. + +### 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: +```shell +docker 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 +``` + +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. + +### Updating doc-builder +Since you've updated the container, 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". + +## See also + +- [GitHub: Working with the container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) +- [GitHub: Connecting a repository to a package](https://docs.github.com/en/packages/learn-github-packages/connecting-a-repository-to-a-package) \ No newline at end of file diff --git a/doc/ctsm-docs_container/requirements.txt b/doc/ctsm-docs_container/requirements.txt new file mode 100644 index 0000000000..178f356b13 --- /dev/null +++ b/doc/ctsm-docs_container/requirements.txt @@ -0,0 +1,6 @@ +# Python packages used for building docs +rst2pdf == 0.103.1 +sphinx == 8.2.3 +sphinxcontrib_programoutput == 0.18 +sphinx-mdinclude == 0.6.2 +sphinx_rtd_theme == 3.0.2 diff --git a/doc/doc-builder b/doc/doc-builder index ab9bc93dd0..9a25c4a20d 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit ab9bc93dd09d0173f8097c7a18c7d061c1cd3b79 +Subproject commit 9a25c4a20db152f57f334c2eb86ea5246b406674 diff --git a/doc/source/_static/pop_ver.js b/doc/source/_static/pop_ver.js deleted file mode 100644 index b8c58658a8..0000000000 --- a/doc/source/_static/pop_ver.js +++ /dev/null @@ -1,37 +0,0 @@ -$(document).ready(function() { - /* For a URL that looks like - https://blah.github.io/versions/VERSIONFOO/html/bar/index.html, set cur_version_dir to - 'VERSIONFOO' (i.e., the portion of the path following 'versions'). - */ - var proj_end = document.baseURI.indexOf("versions") + 9; - var end = document.baseURI.indexOf("/", proj_end); - var cur_version_dir = document.baseURI.substring(proj_end, end); - var mylist = $("#version-list"); - mylist.empty(); - $.getJSON(version_json_loc, function(data) { - if (data.hasOwnProperty(cur_version_dir)) { - /* First add the current version so that it appears first in the drop-down - menu and starts as the selected element of the menu. If you click on the - current version, you should stay at the current page. - - The conditional around this block should generally be true, but we check it - just in case the current version is missing from the versions.json file for - some reason. - */ - cur_version_name = data[cur_version_dir]; - mylist.append($("