Use doc-builder for building and publishing docs

.github/workflows/docs-build-and-deploy.yml

@@ -0,0 +1,67 @@
+name: Deploy static content to Pages
+
+on:
+  push:
+    # Run when a change to these files is pushed to any of these branches.
+    # Make sure to add any files that you "include" in your docs that live outside doc/ !
+    branches: ['master', 'add-github-workflows-with-tmp-docs']
+    paths:
+      - 'doc/**'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+
+  build-and-deploy:
+
+    # Only run on upstream repository.
+    if: ${{ github.repository == 'ESCOMP/CISM-wrapper' }}
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          # Get all history, ensuring all branches are available for checkout
+          fetch-depth: 0
+
+      - name: Setup Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b  # v5
+
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
+        if: ${{ hashFiles('bin/git-fleximod') != '' }}
+        run: bin/git-fleximod update -o
+
+      - name: Build docs using container
+        id: build-docs
+        run: |
+          [[ -e doc ]] && cd doc
+          ./build_docs_to_publish -d --site-root https://escomp.github.io/cism-wrapper --verbose
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@0252fc4ba7626f0298f0cf00902a25c6afc77fa8  # v3
+        with:
+          # Upload publish dir
+          path: 'doc/_publish'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@f33f41b675f0ab2dc5a6863c9a170fe83af3571e  # v4

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

@@ -0,0 +1,56 @@
+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: ['*']
+    # Make sure to add any files that you "include" in your docs that live outside doc/ !
+    paths:
+      - 'doc/**'
+
+  pull_request:
+    # Run on pull requests that change the listed files
+    # Make sure to add any files that you "include" in your docs that live outside doc/ !
+    paths:
+      - '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
+
+      - 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 --verbose 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

@@ -37,4 +37,7 @@ test/unit/time_management/shr_infnan_mod.F90
 test/unit/time_management/time_management_test
 test/unit/time_management/time_management_test_in
 
+# Standard documentation directory names
+_build/
+_publish/
 

.gitmodules

@@ -83,4 +83,12 @@ fxrequired = ToplevelRequired
 	url = https://github.com/NCAR/CUPiD.git
 fxDONOTUSEurl = https://github.com/NCAR/CUPiD.git
 fxrequired = ToplevelRequired
-fxtag = v0.5.1
+fxtag = v0.5.1
+
+[submodule "doc-builder"]
+	path = doc/doc-builder
+	url = https://github.com/ESMCI/doc-builder
+fxtag = v3.5.2
+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

@@ -6,15 +6,24 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = cismdoc
 SOURCEDIR     = source
+DIRWITHCONFPY = doc-builder
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+# '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)" $(SPHINXOPTS) $(O)
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" $(SPHINXOPTS) $(O)