Fix and test doc build

.github/workflows/docs-pr-failure-post-comment.yml

@@ -0,0 +1,66 @@
+name: Post PR comment with doc-build failure log
+
+env:
+  DOCS_FAILURE_ARTIFACT: test-build-docs-container_failed
+
+on:
+  workflow_run:
+    workflows: ["Test building docs when they're updated"]
+    types: [completed]
+
+jobs:
+  comment:
+    if: >-
+      github.event.workflow_run.event == 'pull_request'
+      && github.event.workflow_run.conclusion == 'failure'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      actions: read
+    steps:
+      - name: Check for failure artifact
+        id: check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          gh api repos/$REPO/actions/runs/${{ github.event.workflow_run.id }}/artifacts \
+            --jq '.artifacts[] | select(.name == "${{ env.DOCS_FAILURE_ARTIFACT }}") | .id' > artifact_id.txt
+
+          if [ -s artifact_id.txt ]; then
+            echo "found=true" >> $GITHUB_OUTPUT
+          else
+            echo "found=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Download logs
+        if: steps.check.outputs.found == 'true'
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ env.DOCS_FAILURE_ARTIFACT }}
+          path: ${{ env.DOCS_FAILURE_ARTIFACT }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Post comment
+        if: steps.check.outputs.found == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          PR_NUMBER=$(cat "${DOCS_FAILURE_ARTIFACT}/pr_number.txt")
+
+          {
+            echo "### ❌ Docs build failed"
+            echo
+            echo '<details open="true">'
+            echo "<summary>Build logs</summary>"
+            echo
+            echo '```'
+            cat "${DOCS_FAILURE_ARTIFACT}/build.log"
+            echo '```'
+            echo
+            echo "</details>"
+          } > comment-body.md
+
+          gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file comment-body.md

.github/workflows/docs-to-publish.yml

@@ -0,0 +1,59 @@
+name: Test building docs "to publish"
+
+on:
+  push:
+    # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
+    branches: ['*']
+    paths:
+      - 'doc/doc-builder/**'
+      - 'doc/build_docs_to_publish'
+
+  pull_request:
+    # Run on pull requests that change the listed files
+    paths:
+      - 'doc/doc-builder/**'
+      - 'doc/build_docs_to_publish'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+jobs:
+
+  test-build-docs-to-publish-container:
+    if: ${{ always() }}
+    name: With container from registry
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          submodules: true
+
+      - name: Build docs using Docker (Podman has trouble on GitHub runners)
+        id: build-docs
+        run: |
+          set -o pipefail
+          mkdir -p build-logs
+          [[ -e doc ]] && cd doc
+          git fetch
+          PYTHONUNBUFFERED=1 ./build_docs_to_publish -r ${PWD}/_build -d --verbose --site-root "$PWD/_publish" 2>&1 | tee >(sed -E $'s/\x1b\\[[0-9;]*[a-zA-Z]//g' > "${GITHUB_WORKSPACE}/build-logs/build.log")
+        # The tee writes build.log for the PR comment (posted by docs-pr-failure-post-comment.yml); the inner sed strips ANSI color codes that would otherwise render as garbage in the comment.
+        # PYTHONUNBUFFERED=1 because otherwise the teed log will be out of order
+
+      # The rest of the steps only trigger on failure of above build-docs step.
+      # They upload logs that will be used by the docs-pr-failure-post-comment.yml workflow.
+
+      - name: Record PR number on failure
+        if: failure() && steps.build-docs.outcome == 'failure' && github.event_name == 'pull_request'
+        run: |
+          mkdir -p build-logs
+          echo "${{ github.event.pull_request.number }}" > build-logs/pr_number.txt
+
+      - name: Upload logs on failure
+        if: failure() && steps.build-docs.outcome == 'failure'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: test-build-docs-to-publish-container_failed
+          path: build-logs/

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Test building docs when they're updated
+
+on:
+  push:
+    # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
+    branches: ['*']
+    paths:
+      - 'doc/**'
+    # And also make sure to add any files that you "include" in your docs that live outside doc/
+
+  pull_request:
+    # Run on pull requests that change the listed files
+    paths:
+      - 'doc/**'
+    # And also make sure to add any files that you "include" in your docs that live outside doc/
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+jobs:
+
+  test-build-docs-container:
+    if: ${{ always() }}
+    name: With container from registry
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          submodules: true
+
+      - name: Build docs using Docker (Podman has trouble on GitHub runners)
+        id: build-docs
+        run: |
+          set -o pipefail
+          mkdir -p build-logs
+          [[ -e doc ]] && cd doc
+          PYTHONUNBUFFERED=1 ./build_docs -b ${PWD}/_build -c -d 2>&1 | tee >(sed -E $'s/\x1b\\[[0-9;]*[a-zA-Z]//g' > "${GITHUB_WORKSPACE}/build-logs/build.log")
+        # The tee writes build.log for the PR comment (posted by docs-pr-failure-post-comment.yml); the inner sed strips ANSI color codes that would otherwise render as garbage in the comment.
+        # PYTHONUNBUFFERED=1 because otherwise the teed log will be out of order
+
+      # The rest of the steps only trigger on failure of above build-docs step.
+      # They upload logs that will be used by the docs-pr-failure-post-comment.yml workflow.
+
+      - name: Record PR number on failure
+        if: failure() && steps.build-docs.outcome == 'failure' && github.event_name == 'pull_request'
+        run: |
+          mkdir -p build-logs
+          echo "${{ github.event.pull_request.number }}" > build-logs/pr_number.txt
+
+      - name: Upload logs on failure
+        if: failure() && steps.build-docs.outcome == 'failure'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: test-build-docs-container_failed
+          path: build-logs/

.gitignore

@@ -11,6 +11,7 @@
 CMakeCache.txt
 CMakeFiles
 Makefile
+!doc/Makefile
 autocopy.log
 Makefile.am
 build
@@ -68,3 +69,4 @@ cube_to_target/smooth_topo_cube_sph.mod
 
 # Ignore docs files
 _build/
+_publish/

doc/Makefile

@@ -0,0 +1,28 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+DIRWITHCONFPY = $(if $(wildcard $(dir $(lastword $(MAKEFILE_LIST)))doc-builder),doc-builder,.)
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" $(SPHINXOPTS) $(O)
+
+# 'make fetch-images' should be run before building the documentation. (If building via
+# the build_docs command, this is run automatically for you.) This is needed because we
+# 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 --force
+	git lfs pull --exclude="" --include=""
+
+.PHONY: help fetch-images Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" $(SPHINXOPTS) $(O)

doc/build_docs

@@ -1,6 +1,33 @@
 #!/usr/bin/env bash
 set -e
 
+# $scriptname will already be set if build_docs is getting called from build_docs_to_publish.
+# Otherwise, we need to set it to the basename of this script.
+if [[ -z "${scriptname}" ]]; then
+    scriptname="${0##*/}"
+fi
+
+if [ ! -e doc-builder ]; then
+    # We're in the doc-builder directory itself
+    script="./tools/${scriptname}.py"
+    files_to_copy_to_source="conf.py substitutions.py _templates _static"
+    cp -a ${files_to_copy_to_source} source/
+else
+    # We're in a repo that *includes* doc-builder
+    script="./doc-builder/tools/${scriptname}.py"
+
+    # Make sure the doc-builder submodule is checked out. If doc-builder isn't a submodule but is
+    # instead manually included, we will perform the `else`, which is safe because it's a no-op in
+    # that situation.
+    # (Assume that if the repo uses git-fleximod, doc-builder is handled with it.)
+    git_fleximod_path="$(git rev-parse --show-toplevel)/bin/git-fleximod"
+    if [[ -e "${git_fleximod_path}" ]]; then
+        "${git_fleximod_path}" update doc-builder
+    else
+        git submodule update --init -- doc-builder
+    fi
+fi
+
 # Check if --verbose or -V was passed
 verbose=false
 for arg in "$@"; do
@@ -17,8 +44,18 @@ else
 fi
 
 if $verbose; then
-    echo "Running: ./doc-builder/build_docs $@"
+    echo "Running: ${script} $@"
+fi
+set +e
+${script} "$@"
+exit_code=$?
+set -e
+
+if [ ! -e doc-builder ]; then
+    # Clean up these things we copied
+    for f in ${files_to_copy_to_source}; do
+        rm -r "source/$f"
+    done
 fi
-./doc-builder/build_docs "$@"
 
-exit 0
+exit $exit_code

doc/build_docs_to_publish

@@ -1,27 +1,6 @@
 #!/usr/bin/env bash
 set -e
 
-# Check if --verbose or -V was passed
-verbose=false
-for arg in "$@"; do
-    case "$arg" in
-        --verbose|-V) verbose=true; break ;;
-    esac
-done
+scriptname=build_docs_to_publish
 
-cd "${script_dir}"
-
-if $verbose; then
-    echo "Running: make fetch-images"
-    make fetch-images
-else
-    make fetch-images > /dev/null 2>&1
-fi
-
-if $verbose; then
-    echo "Running: ./doc-builder/build_docs_to_publish $@"
-    pwd
-fi
-./doc-builder/build_docs_to_publish "$@"
-
-exit 0
+. ./build_docs

doc/doc-builder/README.md

@@ -1,5 +1,5 @@
 $$$$$$$$$$$$$$$$$$$
-This instance of doc-builder was copied from https://github.com/ESMCI/doc-builder/tree/v3.4.1
+This instance of doc-builder was copied from https://github.com/ESMCI/doc-builder/tree/v3.5.9
 $$$$$$$$$$$$$$$$$$$
 
 This tool wraps the build command to build sphinx-based documentation.

doc/doc-builder/build_docs

@@ -1,14 +1,61 @@
-#!/usr/bin/env python3
+#!/usr/bin/env bash
+set -e
 
-"""Main driver wrapper around the doc_builder/build_docs utility.
+# $scriptname will already be set if build_docs is getting called from build_docs_to_publish.
+# Otherwise, we need to set it to the basename of this script.
+if [[ -z "${scriptname}" ]]; then
+    scriptname="${0##*/}"
+fi
 
-This tool wraps the build command to build sphinx-based documentation.
+if [ ! -e doc-builder ]; then
+    # We're in the doc-builder directory itself
+    script="./tools/${scriptname}.py"
+    files_to_copy_to_source="conf.py substitutions.py _templates _static"
+    cp -a ${files_to_copy_to_source} source/
+else
+    # We're in a repo that *includes* doc-builder
+    script="./doc-builder/tools/${scriptname}.py"
 
-This should be run from the directory that contains the Makefile for
-building the documentation.
-"""
+    # Make sure the doc-builder submodule is checked out. If doc-builder isn't a submodule but is
+    # instead manually included, we will perform the `else`, which is safe because it's a no-op in
+    # that situation.
+    # (Assume that if the repo uses git-fleximod, doc-builder is handled with it.)
+    git_fleximod_path="$(git rev-parse --show-toplevel)/bin/git-fleximod"
+    if [[ -e "${git_fleximod_path}" ]]; then
+        "${git_fleximod_path}" update doc-builder
+    else
+        git submodule update --init -- doc-builder
+    fi
+fi
 
-from doc_builder import build_docs  # pylint: disable=import-error
+# Check if --verbose or -V was passed
+verbose=false
+for arg in "$@"; do
+    case "$arg" in
+        --verbose|-V) verbose=true; break ;;
+    esac
+done
 
-if __name__ == "__main__":
-    build_docs.main()
+if $verbose; then
+    echo "Running: make fetch-images"
+    make fetch-images
+else
+    make fetch-images > /dev/null 2>&1
+fi
+
+if $verbose; then
+    echo "Running: ${script} $@"
+fi
+set +e
+${script} "$@"
+exit_code=$?
+set -e
+
+if [ ! -e doc-builder ]; then
+    # Clean up these things we copied
+    for f in ${files_to_copy_to_source}; do
+        rm -r "source/$f"
+    done
+fi
+
+exit $exit_code