[WIP] Add hillslope scripts (to python/ctsm/) and external, plus docs

[samsrabin]

Work in progress! Do not review! At risk of force pushes!

Description of changes

Sean Swenson has various scripts related to making files/variables for use in hillslope runs. Some of these are not CTSM-specific, so they're in a separate Representative_Hillslopes repo. Some are CTSM-specific, though, so this PR will add those to python/ctsm/. It also adds the Representative_Hillslopes repo as an optional external to CTSM.

Also adds the ability to include Markdown files natively in .rst files, making the following easier and/or more valuable to tackle:
- #1718
- #2753
- #2761
- #2771
However, it does that by pointing to a new version of the Docker container that I made. This is only temporary while I wait for @briandobbins to update the escomp/base container with sphinx_mdinclude. If that's not ready in time, I'll change any such mdincludes back to includes. Otherwise,

• Point back to escomp/base.

Replaces PR #2401, which I couldn't get to rebase properly.

Specific notes

Contributors other than yourself, if any: Sean Swenson (@swensosc)

CTSM Issues Fixed (include github issue #):

• Resolves Add hillslope scripts #2400

Are answers expected to change (and if so in what way)? No

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

Testing performed, if any: None so far.

Remaining work

• Finish testing and pylint cleanup of combine_chunk_files
• Finish pylint cleanup of synthetic_hillslope
• Add system tests
• Add unit tests
• Rework scripts to make hillslope_file instead of fsurdat
• Add documentation

[samsrabin]

This can move forward now that #2434 is done.

[samsrabin]

• Change this to Sean's repo, not my fork. Waiting on Improvements to shell_scripts/README.md swensosc/Representative_Hillslopes#6.

[samsrabin]

• Change this back to ESMCI repo, not my fork. Waiting on updates there that (a) treat sphinx warnings as errors and (b) point to an updated version of the escomp/base container that includes sphinx-mdinclude (see this comment).

[samsrabin]

I think the problem with the test builds at this point is that I need to manually do bin/git-fleximod update -o. However, when I add that like so:

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index f8d7b4962..20927f776 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -42,7 +42,7 @@ jobs:
       # Build documentation under ${PWD}/_build
       - name: Build Sphinx docs with makefile
         run: |
-          make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build -C doc/ html
+          bin/git-fleximod update -o && make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build -C doc/ html

   test-doc-builder:
     if: ${{ always() }}
@@ -71,4 +71,4 @@ jobs:
       # Build documentation under ${PWD}/_build
       - name: Build Sphinx docs with doc-builder
         run: |
-          cd doc && ./build_docs -b ${PWD}/_build -c
+          bin/git-fleximod update -o && cd doc && ./build_docs -b ${PWD}/_build -c

act gives me this error:

| e                fates not checked out, aligned at tag sci.1.78.2_api.36.0.0
| root - ERROR - Failed to checkout fates False None /Users/samrabin/Documents/git_repos/CTSM_myfork/src/fates src/fates
| Traceback (most recent call last):
|   File "/Users/samrabin/Documents/git_repos/CTSM_myfork/bin/git-fleximod", line 8, in <module>
|     sys.exit(main())
|              ^^^^^^
|   File "/Users/samrabin/Documents/git_repos/CTSM_myfork/.lib/git-fleximod/git_fleximod/git_fleximod.py", line 607, in main
|     submodules_update(gitmodules, root_dir, fxrequired, force)
|   File "/Users/samrabin/Documents/git_repos/CTSM_myfork/.lib/git-fleximod/git_fleximod/git_fleximod.py", line 421, in submodules_update
|     single_submodule_checkout(
|   File "/Users/samrabin/Documents/git_repos/CTSM_myfork/.lib/git-fleximod/git_fleximod/git_fleximod.py", line 257, in single_submodule_checkout
|     utils.fatal_error(
|   File "/Users/samrabin/Documents/git_repos/CTSM_myfork/.lib/git-fleximod/git_fleximod/utils.py", line 130, in fatal_error
|     raise RuntimeError("{0}ERROR: {1}".format(os.linesep, message))
| RuntimeError:
| ERROR: Failed to checkout fates False None /Users/samrabin/Documents/git_repos/CTSM_myfork/src/fates src/fates

• Fix this. Done (2024-10-13)