ctsm5.3.048: Automatically publish docs to this repo

.github/ISSUE_TEMPLATE/03_documentation.md

@@ -12,8 +12,8 @@ about: Something should be added to or fixed in the documentation
 - [ ] Something is broken.
 
 ### What part(s) of the documentation does this concern?
-- [ ] [Technical Note](https://escomp.github.io/ctsm-docs/versions/master/html/tech_note/index.html) (science and design of the model)
-- [ ] [User's Guide](https://escomp.github.io/ctsm-docs/versions/master/html/users_guide/index.html) (using the model and related tools)
+- [ ] [Technical Note](https://escomp.github.io/ctsm/tech_note/index.html) (science and design of the model)
+- [ ] [User's Guide](https://escomp.github.io/ctsm/users_guide/index.html) (using the model and related tools)
 - [ ] Somewhere else (e.g., README file, tool help text, or code comment): _Please specify_
 - [ ] I don't know
 

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

@@ -0,0 +1,64 @@
+name: Deploy static content to Pages
+
+on:
+  push:
+    # Run when a change to these files is pushed to master.
+    branches: ['master', 'release-clm5.0']
+    paths:
+      - 'doc/**'
+      - '!doc/*ChangeLog*'
+      - '!doc/*ChangeSum*'
+      - '!doc/UpdateChangelog.pl'
+      # Include all include::ed files outside doc/ directory!
+      - 'src/README.unit_testing'
+      - 'tools/README'
+
+  # 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:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # Get all history, ensuring all branches are available for checkout
+          fetch-depth: 0
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build docs using container
+        id: build-docs
+        run: |
+          bin/git-fleximod update -o
+          cd doc
+          ./build_docs_to_publish -d --site-root https://escomp.github.io/ctsm
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload publish dir
+          path: 'doc/_publish'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/docs-ctsm_pylib.yml

@@ -6,11 +6,13 @@ on:
     branches: ['*']
     paths:
       - 'python/conda_env_ctsm_py.txt'
+      - '.github/workflows/docs-common.yml'
 
   pull_request:
     # Run on pull requests that change the listed files
     paths:
       - 'python/conda_env_ctsm_py.txt'
+      - '.github/workflows/docs-common.yml'
 
   schedule:
     # 8 am every Monday UTC

.github/workflows/docs-omnibus.yml

@@ -0,0 +1,54 @@
+name: Run an omnibus test script for the docs
+
+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/*ChangeLog*'
+      - '!doc/*ChangeSum*'
+      - '!doc/UpdateChangelog.pl'
+      # Include all include::ed files outside doc/ directory!
+      - 'src/README.unit_testing'
+      - 'tools/README'
+
+  pull_request:
+    # Run on pull requests that change the listed files
+    paths:
+      - 'doc/**'
+      - '!doc/*ChangeLog*'
+      - '!doc/*ChangeSum*'
+      - '!doc/UpdateChangelog.pl'
+      # Include all include::ed files outside doc/ directory!
+      - 'src/README.unit_testing'
+      - 'tools/README'
+
+  workflow_dispatch:
+
+jobs:
+  build-docs-omnibus-test:
+    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
+
+      # Set up conda
+      - name: Set up conda environment
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          activate-environment: ctsm_pylib
+          environment-file: python/conda_env_ctsm_py.yml
+          channels: conda-forge
+          auto-activate-base: false
+
+      # TODO: Split testing.sh tests into their own steps in this job
+      - name: Text Sphinx builds with omnibus script
+        run: |
+          cd doc && conda run -n ctsm_pylib ./testing.sh

.github/workflows/docs.yml

@@ -10,6 +10,10 @@ on:
       - '!doc/*ChangeLog*'
       - '!doc/*ChangeSum*'
       - '!doc/UpdateChangelog.pl'
+      - '.github/workflows/docs-common.yml'
+      # Include all include::ed files outside doc/ directory!
+      - 'src/README.unit_testing'
+      - 'tools/README'
 
   pull_request:
     # Run on pull requests that change the listed files
@@ -18,6 +22,10 @@ on:
       - '!doc/*ChangeLog*'
       - '!doc/*ChangeSum*'
       - '!doc/UpdateChangelog.pl'
+      - '.github/workflows/docs-common.yml'
+      # Include all include::ed files outside doc/ directory!
+      - 'src/README.unit_testing'
+      - 'tools/README'
 
   workflow_dispatch:
 

.gitignore

@@ -114,4 +114,4 @@ Depends
 
 # Docs build output
 _build*/
-
+_publish*/

.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 = v2.0.0
+fxtag = v2.1.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

README.md

@@ -15,7 +15,7 @@ http://www.cesm.ucar.edu/models/cesm2.0/land/
 
 and
 
-https://escomp.github.io/ctsm-docs/
+https://escomp.github.io/ctsm/
 
 For help with how to work with CTSM in git, see
 

doc/ChangeLog

@@ -1,4 +1,68 @@
 ===============================================================
+Tag name: ctsm5.3.048
+Originator(s): samrabin (Sam Rabin, UCAR/TSS)
+Date: Mon May 26 18:30:59 MDT 2025
+One-line Summary: Automatically publish docs to this repo
+
+Purpose and description of changes
+----------------------------------
+
+Enables automatic publication of documentation to this repo's GitHub Pages, making ctsm-docs repo obsolete. Also updates documentation documentation.
+
+
+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.)
+
+[ ] clm6_0
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed
+----------
+
+List of CTSM issues fixed (include CTSM Issue # and description):
+- [Issue #2541: Some links in User's Guide sidebar are broken](https://github.com/ESCOMP/CTSM/issues/2541)
+- [Issue #2839: Automatically publish updated docs](https://github.com/ESCOMP/CTSM/issues/2839)
+- [Issue #3121: Fix capital letter in doc filenames](https://github.com/ESCOMP/CTSM/issues/3121)
+
+Notes of particular relevance for users
+---------------------------------------
+
+Changes to documentation:
+- Canonical URL for User's Guide and Tech Note will be changing from https://escomp.github.io/ctsm-docs to https://escomp.github.io/ctsm.
+- Updates to "Working with the CTSM documentation" section
+
+
+Notes of particular relevance for developers:
+---------------------------------------------
+
+We're going to get rid of the ctsm-docs repo!
+
+
+Testing summary:
+----------------
+
+None, as no code is changing aside from the documentation infrastructure, which is tested in GitHub Workflows.
+
+Other details
+-------------
+
+List any git submodules updated (cime, rtm, mosart, cism, fates, etc.):
+- doc-builder
+
+Pull Requests that document the changes (include PR ids):
+- [Pull Request #3146: ctsm5.3.048: Automatically publish docs to this repo by samsrabin](https://github.com/ESCOMP/CTSM/pull/3146/files)
+
+===============================================================
+===============================================================
 Tag name: ctsm5.3.047
 Originator(s): samrabin (Sam Rabin, UCAR/TSS)
 Date: Mon May 26 16:30:10 MDT 2025

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       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
        ctsm5.3.045 glemieux 05/20/2025 FATES default parameter update for API 40

doc/Makefile

@@ -6,11 +6,12 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = clmdoc
 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)
 
 # '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
@@ -33,9 +34,9 @@ fetch-images:
 #
 # The use of $(0) is as in the catch-all target.
 latexpdf:
-	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)/tech_note" "$(BUILDDIR)" -c "$(SOURCEDIR)" -D numfig_secnum_depth=1 $(SPHINXOPTS) $(O)
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)/tech_note" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" -D numfig_secnum_depth=1 $(SPHINXOPTS) $(O)
 
 # 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)

doc/build_docs_to_publish

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -e
+
+script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+if [ ! -f doc-builder/build_docs_to_publish ]; then
+    "${script_dir}"/../bin/git-fleximod update doc-builder
+fi
+
+cd "${script_dir}"
+
+echo "Running: make fetch-images"
+make fetch-images
+
+echo "Running: ./doc-builder/build_docs_to_publish $@"
+pwd
+./doc-builder/build_docs_to_publish "$@"
+
+exit 0