Automatically publish updated docs

[samsrabin]

It should be possible to host docs here without bloating clones (see discussion linked below) which would then enable us to publish updated docs automatically. I have a proof-of-concept here, which uses this workflow. As of 11fdc30, that workflow runs (a) on a push to main or (b) manually via the Actions tab.

• Figure out how to generate different versions for ctsm5.0 vs. master. I think this might be helpful.

Just set up a workflow in the existing docs repo that checks for changes to docs/ on master in this repo and builds/deploys if it sees any.

---

Discussed in #2819

^{Originally posted by samsrabin October 7, 2024}
CIME is able to generate documentation previews on PRs and automatically update their documentation upon pushes to master because they host their docs in the same repo as their code. Our use of the separate ctsm-docs repo makes this impossible (or at least difficult enough that I can't figure it out given my lack of Github workflow experience).

[samsrabin]

I think that link is actually not helpful after all. The issue is that we're talking about generating docs with different versions of the repo itself; I don't think there's a way to handle that in a workflow run.

So as I see it now, there are two options.

Option 1: Host here

1. Generate a .zip file with the HTML (i.e., html/ directory) for the preserved release version of the website (at the moment, that's release-clm5.0). Upload that (with git lfs) to this repo.
2. Change the workflow's "Build Sphinx docs with makefile" step so that after building the current docs to ${PWD}/_build/html, it does:

# Create directory structure we need
build_dir=${PWD}/_build
mkdir -p $build_dir/versions/master
mkdir -p $build_dir/versions/release-clm5.0

# Move the current docs build to that structure
mv $build_dir/html $build_dir/versions/master/

# Unzip the release-clm5.0 build to that structure
unzip release-clm5.0.zip -d $build_dir/versions/release-clm5.0/

3. Change the workflow's "Upload artifact" step to use path: $build_dir/versions.

Pros

• Keeping everything within this repo is neat and tidy.

Cons

• Every clone would see the release-clm5.0 .zip file, even if they didn't actually download it. This would inflate the size of fresh clones to some extent, more so whenever that .zip file is changed.
• Would need to set up a redirect (hopefully automatic? maybe manual) for when people go to the ctsm-docs publish url (https://escomp.github.io/ctsm-docs).
• I'm not sure this would even work.

Option 2: Keep hosting at ctsm-docs

It should be possible to set up a workflow in the ctsm-docs repo that could build and publish the latest documentation at a regular interval (e.g., nightly). It would do this by checking out the latest master tag from that repo and building that, then the latest on a new release-clm5.0-docs branch and building that. The uploaded artifact would have both (see step 3 of Option 1 above).

Pros

• Zero risk of inflating the size of fresh clones of the CTSM repo.

Cons

• A bit convoluted.

[samsrabin]

Just do (2). Added label:external because the work needs to be done in the ctsm-docs repo. Adding label:blocked because it's blocked by #2809.

[samsrabin]

No. Just deploy with an action from here. E.g.:

name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # 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

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Build docs using container
        id: build-docs
        run: |
          build_dir_top="${PWD}/_build"
          cd doc
          ./build_docs -r "${build_dir_top}" -c -d -v latest && \
          ./build_docs -r "${build_dir_top}" -c -d -v another && \
          ln -s "${build_dir_top}/versions/latest/html/index.html" "${build_dir_top}/index.html"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload build dir
          path: '_build'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4