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

.git-blame-ignore-revs

@@ -24,9 +24,11 @@ e4d38681df23ccca0ae29581a45f8362574e0630
 a9d96219902cf609636886c7073a84407f450d9a
 d866510188d26d51bcd6d37239283db690af7e82
 0dcd0a3c1abcaffe5529f8d79a6bc34734b195c7
+179e2eeb1ad919539e21f92947fcc80c9b054869
 e096358c832ab292ddfd22dd5878826c7c788968
 475831f0fb0e31e97f630eac4e078c886558b61c
 fd5f177131d63d39e79a13918390bdfb642d781e
+4b03f5a93d781d8ef0ca58fa88fc510784ba9b1a
 # Ran SystemTests and python/ctsm through black python formatter
 5364ad66eaceb55dde2d3d598fe4ce37ac83a93c
 8056ae649c1b37f5e10aaaac79005d6e3a8b2380
@@ -36,6 +38,11 @@ fd5f177131d63d39e79a13918390bdfb642d781e
 183fc26a6691bbdf87f515dc47924a64be3ced9b
 6fccf682eaf718615407d9bacdd3903b8786a03d
 2500534eb0a83cc3aff94b30fb62e915054030bf
+# Ran individual files through black python formatter
+f05fcbc10eda44e574de7554c8ac2b0417215b61
+eb4906d8ee78b4f5ad5b3b990c414f6e113b661f
+63c4873eab8af9fdd1f89bfe0a5416dcc53394fa
+7053b2980da08bb46f82d9cf1a5c4c63b98b37f6
 78d05967c2b027dc9776a884716597db6ef7f57c
 47839a77229c61555e3b8932927bb54cdc511b27
 a0d014fae9550dd9ffbc934abd29ef16176f8208

.github/workflows/docs.yml

@@ -0,0 +1,80 @@
+name: docs
+
+on:
+  push:
+    paths:
+      - 'doc/**'
+
+  pull_request:
+    paths:
+      - 'doc/**'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+jobs:
+
+  test-build-makefile:
+    if: ${{ always() }}
+    name: Test building documentation with makefile
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Install python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+      # https://github.com/actions/cache/blob/main/examples.md#python---pip
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -r doc/requirements.txt
+      - name: Call git-fleximod
+        run: |
+          bin/git-fleximod update -o
+      # Build documentation under ${PWD}/_build
+      - name: Build Sphinx docs with makefile
+        run: |
+          make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build -C doc/ html
+
+  test-doc-builder:
+    if: ${{ always() }}
+    name: Test building documentation with doc-builder
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Install python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+      # https://github.com/actions/cache/blob/main/examples.md#python---pip
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -r doc/requirements.txt
+      - name: Call git-fleximod
+        run: |
+          bin/git-fleximod update -o
+      # Build documentation under ${PWD}/_build
+      - name: Build Sphinx docs with doc-builder
+        run: |
+           rm -r .git/hooks && cd doc && ./build_docs -b ${PWD}/_build -c

.gitignore

@@ -1,3 +1,19 @@
+# directories checked out by manage_externals, and other files created
+# by manage_externals
+manage_externals.log
+ccs_config
+/src/fates/
+/cime/
+/components/
+/libraries/
+/share/
+/doc/doc-builder/
+/tools/external/
+
+# ignore svn directories
+**/.svn/**
+.svn/
+
 # netcdf files
 *.nc
 # but don't ignore netcdf files here:

.gitmodules

@@ -123,8 +123,16 @@ fxDONOTUSEurl = https://github.com/NCAR/ParallelIO
 
 [submodule "doc-builder"]
 path = doc/doc-builder
-url = https://github.com/ESMCI/doc-builder
-fxtag = v1.0.8
+url = https://github.com/samsrabin/doc-builder
+fxtag = c51795f65d230803418c932bfd8639c85c33a19a
 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
+
+[submodule "representative-hillslopes"]
+path = tools/external/representative-hillslopes
+url = https://github.com/samsrabin/Representative_Hillslopes
+fxtag = 2126ffe018b2268ed479469421763cbb45d9c264
+fxrequired = ToplevelOptional
+# Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
+fxDONOTUSEurl = https://github.com/swensosc/Representative_Hillslopes

.lib/git-fleximod/.github/workflows/pytest.yaml

@@ -18,7 +18,7 @@ jobs:
       # reference the matrixe python version here.
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.12'
 
       # Cache the installation of Poetry itself, e.g. the next step. This prevents the workflow
       # from installing Poetry every time, which can be slow. Note the use of the Poetry version
@@ -29,7 +29,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.local
-          key: poetry-1.7.1
+          key: poetry-1.8.2
 
       # Install Poetry. You could do this manually, or there are several actions that do this.
       # `snok/install-poetry` seems to be minimal yet complete, and really just calls out to
@@ -42,7 +42,7 @@ jobs:
       # cache it.
       - uses: snok/install-poetry@v1
         with:
-          version: 1.7.1
+          version: 1.8.2
           virtualenvs-create: true
           virtualenvs-in-project: true
 
@@ -74,4 +74,7 @@ jobs:
           git config --global user.name "${GITHUB_ACTOR}"
           git config --global user.email "${GITHUB_ACTOR_ID}+${GITHUB_ACTOR}@users.noreply.github.com"
           poetry run pytest
+      - name: Setup tmate session
+        if: ${{ failure() }}
+        uses: mxschmitt/action-tmate@v3
 

.lib/git-fleximod/CODE_OF_CONDUCT.md

@@ -0,0 +1,107 @@
+# Contributor Code of Conduct
+_The Contributor Code of Conduct is for participants in our software projects and community._
+
+## Our Pledge
+We, as contributors, creators, stewards, and maintainers (participants), of **git-fleximod** pledge to make participation in
+our software, system or hardware project and community a safe, productive, welcoming and inclusive experience for everyone.
+All participants are required to abide by this Code of Conduct.
+This includes respectful treatment of everyone regardless of age, body size, disability, ethnicity, gender identity or expression,
+level of experience, nationality, political affiliation, veteran status, pregnancy, genetic information, physical appearance, race,
+religion, or sexual orientation, as well as any other characteristic protected under applicable US federal or state law.
+
+## Our Standards
+Examples of behaviors that contribute to a positive environment include:
+
+* All participants are treated with respect and consideration, valuing a diversity of views and opinions
+* Be considerate, respectful, and collaborative
+* Communicate openly with respect for others, critiquing ideas rather than individuals and gracefully accepting criticism
+* Acknowledging the contributions of others
+* Avoid personal attacks directed toward other participants
+* Be mindful of your surroundings and of your fellow participants 
+* Alert UCAR staff and suppliers/vendors if you notice a dangerous situation or someone in distress
+* Respect the rules and policies of the project and venue
+
+Examples of unacceptable behavior include, but are not limited to:
+
+* Harassment, intimidation, or discrimination in any form
+* Physical, verbal, or written abuse by anyone to anyone, including repeated use of pronouns other than those requested
+* Unwelcome sexual attention or advances
+* Personal attacks directed at other guests, members, participants, etc.
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Alarming, intimidating, threatening, or hostile comments or conduct
+* Inappropriate use of nudity and/or sexual images 
+* Threatening or stalking anyone, including a participant
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Scope
+This Code of Conduct applies to all spaces managed by the Project whether they be physical, online or face-to-face.
+This includes project code, code repository, associated web pages, documentation, mailing lists, project websites and wiki pages,
+issue tracker, meetings, telecons, events, project social media accounts, and any other forums created by the project team which the
+community uses for communication.
+In addition, violations of this Code of Conduct outside these spaces may affect a person's ability to participate within them.
+Representation of a project may be further defined and clarified by project maintainers.
+
+## Community Responsibilities
+Everyone in the community is empowered to respond to people who are showing unacceptable behavior.
+They can talk to them privately or publicly.
+Anyone requested to stop unacceptable behavior is expected to comply immediately.
+If the behavior continues concerns may be brought to the project administrators or to any other party listed in the
+[Reporting](#reporting) section below.
+
+## Project Administrator Responsibilities
+Project administrators are responsible for clarifying the standards of acceptable behavior and are encouraged to model appropriate
+behavior and provide support when people in the community point out inappropriate behavior.
+Project administrator(s) are normally the ones that would be tasked to carry out the actions in the [Consequences](#consequences)
+section below.
+
+Project administrators are also expected to keep this Code of Conduct updated with the main one housed at UCAR, as listed below in
+the [Attribution](#attribution) section.
+
+## Reporting
+Instances of unacceptable behavior can be brought to the attention of the project administrator(s) who may take any action as
+outlined in the [Consequences](#consequences) section below.
+However, making a report to a project administrator is not considered an 'official report' to UCAR. 
+
+Instances of unacceptable behavior may also be reported directly to UCAR pursuant to [UCAR's Harassment Reporting and Complaint
+Procedure](https://www2.fin.ucar.edu/procedures/hr/harassment-reporting-and-complaint-procedure), or anonymously through [UCAR's
+EthicsPoint Hotline](https://www2.fin.ucar.edu/ethics/anonymous-reporting).
+
+Complaints received by UCAR will be handled pursuant to the procedures outlined in UCAR's Harassment Reporting and Complaint
+Procedure.
+Complaints to UCAR will be held as confidential as practicable under the circumstances, and retaliation against a person who
+initiates a complaint or an inquiry about inappropriate behavior will not be tolerated.
+
+Any Contributor can use these reporting methods even if they are not directly affiliated with UCAR.
+The Frequently Asked Questions (FAQ) page for reporting is [here](https://www2.fin.ucar.edu/procedures/hr/reporting-faqs).
+
+## Consequences
+Upon receipt of a complaint, the project administrator(s) may take any action deemed necessary and appropriate under the
+circumstances.
+Such action can include things such as: removing, editing, or rejecting comments, commits, code, wiki edits, email, issues, and
+other contributions that are not aligned to this Code of Conduct, or banning temporarily or permanently any contributor for other
+behaviors that are deemed inappropriate, threatening, offensive, or harmful.
+Project administrators also have the right to report violations to UCAR HR and/or UCAR's Office of Diversity, Equity and Inclusion
+(ODEI), as well as a participant's home institution and/or law enforcement.
+In the event an incident is reported to UCAR, UCAR will follow its Harassment Reporting and Complaint Procedure.
+
+## Process for Changes
+All UCAR managed projects are required to adopt this Contributor Code of Conduct.
+Adoption is assumed even if not expressly stated in the repository.
+Projects should fill in sections where prompted with project-specific information, including, project name and adoption date.
+
+Projects that adopt this Code of Conduct need to stay up to date with UCAR's Contributor Code of Conduct, linked with a DOI in the
+[Attribution](#attribution) section below.
+Projects can make limited substantive changes to the Code of Conduct, however, the changes must be limited in scope and may not
+contradict the UCAR Contributor Code of Conduct.
+
+## Attribution
+This Code of Conduct was originally adapted from the [Contributor Covenant](http://contributor-covenant.org/version/1/4), version
+1.4.
+We then aligned it with the UCAR Participant Code of Conduct, which also borrows from the American Geophysical Union (AGU) Code of
+Conduct.
+The UCAR Participant Code of Conduct applies to both UCAR employees as well as participants in activities run by UCAR.
+The original version of this for all software projects that have strong management from UCAR or UCAR staff is available on the UCAR
+website at https://doi.org/10.5065/6w2c-a132.
+The date that it was adopted by this project was **Feb/13/2018**.
+When responding to complaints, UCAR HR and ODEI will do so based on the latest published version.
+Therefore, any project-specific changes should follow the [Process for Changes](#process-for-changes) section above.

.lib/git-fleximod/git_fleximod/cli.py

@@ -2,7 +2,7 @@
 import argparse
 from git_fleximod import utils
 
-__version__ = "0.7.8"
+__version__ = "0.9.2"
 
 def find_root_dir(filename=".gitmodules"):
     """ finds the highest directory in tree