Update docs infrastructure

[samsrabin]

Description of changes

• Removes dependence on outdated version of sphinx_rtd_theme
• Enables embedding of Markdown docs in .rst files (this feature is blocking [WIP] Add hillslope scripts (to python/ctsm/) and external, plus docs #2425)
• Adds GitHub Workflow jobs (on push, pull_request, workflow_dispatch) to test doc build with both make and build_docs calls:
  • With minimal Python setup and with latest published ghcr.io/escomp/ctsm/ctsm-docs container whenever anything changes in docs/
  • With ctsm_pylib whenever anything changes in ctsm_pylib env file, and also at 8 am UTC Mondays
  • With a test build of the ghcr.io/escomp/ctsm/ctsm-docs container whenever the setup of that container changes
• Adds GitHub workflow job to build and publish ghcr.io/escomp/ctsm/ctsm-docs container whenever it's updated
• New GitHub workflows allow:
  • Closure of PR [WIP] Add Github workflow: "Pull Request Docs Check" #2499
  • Deletion of test: docs label
  • Deletion of samr-test-20241003 branch
• Publish docs update on merge No, do this separately. See Automatically publish updated docs #2839.

Version before rebase is preserved here.

Contributors other than yourself, if any: None

CTSM Issues Fixed:

• Resolves Update doc-builder #2818

Are answers expected to change (and if so in what way)? Model code is unaffected. Various parts of the documentation will see minor changes.

Any User Interface Changes (namelist or namelist defaults changes)? No

Testing performed, if any: Local builds and new GitHub Workflows.

[ekluzek]

Awesome. Great work here. You already had us try the build workflow out and it worked for the group. So it obviously is working.

I have some suggestions, comments, and questions. I think the only important things I note is that ESMCI/doc-builder will need to be updated (but the new workflow is already telling you that). And I thought version_list should be different.

But, approving so you can do what you need to do and not need to get back to me.

[ekluzek]

@billsacks it seems like this would be good for you to review some of this. Just the doc building part of this that is. So ignore the .github workflow part and the python directory part, and just look at the changes under the doc directory that are outside of the users-guide and tech-note changes.

Let us know if that's something you could do. Thanks for considering.

[samsrabin]

File issue:

• Fix links that are messed up because they assume capital letter in filename. E.g., Running-with-custom-crop-calendars.rst in doc/source/users_guide/running-special-cases/index.rst. That page path seems to get produced as running-with-custom-crop-calendars.html instead of Running-with-custom-crop-calendars.html, so the link is broken.
• Add a GitHub workflow to fail if any .rst or .md filename in (or linked in) the docs has a capital letter.

Added as #3121.

[billsacks]

I took a quick look at this. Thank you very much @samsrabin for all of your work to streamline the documentation build. This is very useful!!

[samsrabin]

Thanks, @billsacks!