Update docs infrastructure

.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
+

.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

.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

.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

.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`.

.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
+
+

.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

.gitignore

@@ -110,3 +110,7 @@ core.*
 *.log !run.log
 *.pyc
 Depends
+
+# Docs build output
+_build*/
+

.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 = 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

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