Host docs here instead of ctsm-docs

[samsrabin]

It should be possible without bloating clones; see discussion linked below. 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.

---

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.