wee cleanup

docs/atmospheric_physics/Tagging-Instructions.md

@@ -3,7 +3,7 @@
 This page lists instructions for how to create a new atmospheric_physics tag.  A few rules:
 
 1.  Tags should always be annotated (no lightweight tags).
-2.  Tags should follow the naming convention listed below.
+2.  Tags should follow the naming convention listed [below](#tag-naming-conventions).
 3.  Tags should point to merge commits into the main branch.
 4.  Tags can only be created by people who have write access.
 
@@ -14,7 +14,7 @@ You can create a new atmospheric_physics tag, assuming you have git installed on
 **1.  Download the latest version of the repo:**
 
 ```
-git clone https://github.com/NCAR/atmospheric_physics.git
+git clone https://github.com/ESCOMP/atmospheric_physics.git
 cd atmospheric_physics
 ```
 
@@ -44,15 +44,15 @@ Where `<tag>` is the new tag name (which should follow the naming convention sho
 
 `git push origin <tag>`
 
-After which the new tag should now exist in the NCAR/atmospheric_physics repo.
+After which the new tag should now exist in the ESCOMP/atmospheric_physics repo.
 
 ## Tag naming conventions
 
-All NCAR/atmospheric_physics tags for the main branch should look like the following:
+All ESCOMP/atmospheric_physics tags for the main branch should look like the following:
 
 `atmos_physX_YY_ZZZ`
 
-While all tags for the development tag should be:
+While all tags for the development branch should be:
 
 `dev_atmos_physX_YY_ZZZ`
 

docs/atmospheric_physics/development_workflow.md

@@ -1,18 +1,18 @@
 # Development workflow for atmospheric_physics
 
-This page describes the general workflow for adding new developments to the [atmospheric_physics](https://github.com/ESCOMP/atmospheric_physics) repo, which is the location of all CGD developed CCPP-ized physics schemes and Suite Definition Files (SDFs).
+This page describes the general workflow for adding new developments to the [atmospheric_physics](https://github.com/ESCOMP/atmospheric_physics) repo, which is the location of all CGD-developed CCPP-ized physics schemes and Suite Definition Files (SDFs).
 
 ## Workflow summary
 
 The general workflow for adding a feature, bug-fix, or modification to atmospheric_physics is as follows:
 
-  1.  **Open an issue.**
-  2.  **Add your code modifications to a branch on your fork.**
-  3.  **Open a PR from your branch to the `development` branch.**
+  1.  [**Open an issue.**](#1-open-an-issue)
+  2.  **[Add your code modifications](#3-update-your-code-with-changes-from-the-official-repo) to a branch on your [fork](#2-create-a-fork-if-you-havent-already).**
+  3.  **[Open a PR](#5-creating-a-pull-request-pr) from your branch to the `development` branch.**
   4.  **Respond to any reviewer requests.**
   5.  **Fix any failing tests.**
-  6.  **Update `doc/NamesNotInDictionary.txt` file.**
-  7.  **If you know that this PR will need an official tag, then also add the tag name to the PR description.**
+  6.  **[Update `doc/NamesNotInDictionary.txt` file.](#updating-namesnotindictionarytxt-file)**
+  7.  **If you know that this PR will need an official tag, then also add the [tag name](Tagging-Instructions.md/#tag-naming-conventions) to the PR description.**
   8.  **Squash the commits and merge the PR (e.g. the "squash and merge" option).**
 
 If you need an official tag for your new additions, then once your `development` PR has been merged you will need to do the following:
@@ -32,7 +32,7 @@ It is generally recommended to [open an issue](https://github.com/ESCOMP/atmosph
 
 ### 2.  Create a fork (if you haven't already).
 
-We generally recommend creating a fork of the atmospheric_physics repo, and doing all of the development there.  Instructions for how to setup a fork, and how to configure git in general, can be [found here](https://escomp.github.io/CAM-SIMA-docs/development/git-basics/).
+We recommend creating a fork of the atmospheric_physics repo, and doing all of the development there.  Instructions for how to set up a fork, and how to configure git in general, can be [found here](../../development/git-basics/).
 
 ### 3. Update your code with changes from the official repo.
 
@@ -41,16 +41,16 @@ We generally recommend creating a fork of the atmospheric_physics repo, and doin
 ```
    git clone https://github.com/<GitHub userid>/atmospheric_physics
    cd atmospheric_physics
-   git remote add upstream https://github.com/NCAR/atmospheric_physics.git
+   git remote add upstream https://github.com/ESCOMP/atmospheric_physics.git
 ```
 
-**2.  Fetch the latest version of the NCAR repo:**
+**2.  Fetch the latest version of the ESCOMP repo:**
 
 ```
    git fetch upstream
 ```
 
-**3.  Rebase your local forked branch to the NCAR version.  For example, assuming you are working on a local branch called `feature`:**
+**3.  Rebase your local forked branch to the ESCOMP version.  For example, assuming you are working on a local branch called `feature`:**
 
 ```
    git checkout feature
@@ -75,10 +75,10 @@ Of course, if you run into any problems with either method then please create a
 
 ### 4. Committing code
 
-**1. Create a new branch:**
+**1. Create a new branch off of the ESCOMP development branch:**
 
 ```
-   git checkout -b cool_new_feature
+   git checkout -b cool_new_feature upstream/development
 ```
 
 where `cool_new_feature` is an example branch name (you can use any name you want).  Next, push that new branch to your fork on Github:
@@ -87,7 +87,7 @@ where `cool_new_feature` is an example branch name (you can use any name you wan
    git push -u origin cool_new_feature
 ```
 
-**2.  Apply your code modifications and/or script additions, and perform at least one test making sure that your modifications works as expected.**
+**2.  Apply your code modifications and/or script additions, and perform at least one test making sure that your modifications work as expected.**
 
 **3.  Add all the files that you want to commit.  There are multiple ways to do this, but one of the safer ways is to first check your status:**
 
@@ -125,7 +125,7 @@ where `<message>` is a short descriptor or sentence stating what the commits are
 
 ### 5. Creating a Pull Request (PR)
 
-**1.  Go to the NCAR atmospheric_physics repo, and click on the "Pull requests" tab.**
+**1.  Go to the [ESCOMP atmospheric_physics repo](https://github.com/ESCOMP/atmospheric_physics), and click on the "Pull requests" tab.**
 
 ![text](figures/atm_phys_PR_tab_circle.png "Pull requests tab")
 
@@ -137,7 +137,7 @@ where `<message>` is a short descriptor or sentence stating what the commits are
 
  ![text](figures/compare_forks_link.png "Compare forks")
 
-**4.  You should now see two new pull down boxes (to the right of an arrow).  Using those pull down boxes, select your fork (which should be `<username>/atmospheric_physics`):**
+**4.  You should now see two new pull down boxes (to the right of an arrow).  Using those pull down boxes, select the "development" branch of the ESCOMP repo and select your fork (which should be `<username>/atmospheric_physics`):**
 
  ![text](figures/fork_repo_dropdown.png "fork select list")
 
@@ -157,9 +157,9 @@ where `<message>` is a short descriptor or sentence stating what the commits are
 
 **9.  Fix any failing tests that show up on Github.**
 
-**10.  If you get any change requests during code review, then simply apply those changes in the same way you applied your original modifications.  Please note that once you `push` your changes then the PR will automatically be updated.**
+**10.  If you get any change requests during code review, then simply apply those changes in the same way you applied your original modifications.  Please note that once you `push` your changes then the PR will automatically be updated and the GitHub tests will be automatically run.**
 
-**11.  Update the `NamesNotInDictionary.txt` file using the instructions below.**
+**11.  Update the `NamesNotInDictionary.txt` file using the instructions [below](#updating-namesnotindictionarytxt-file).**
 
 **12.  Once all reviewers sign off on your modifications, then the PR will be squashed and merged.  Congratulations!  Your code is now in atmospheric_physics!**
 
@@ -196,5 +196,5 @@ Once your modifications have been merged into the official CAM repo, you may hav
 **3.   Finally, remove branch from personal fork repo:**
 ```
     git push --delete <origin> <branch_name>
-````
+```
    You can also remove the branch via GitHub's [user interface](https://help.github.com/en/articles/creating-and-deleting-branches-within-your-repository#deleting-a-branch).

docs/atmospheric_physics/directory-structure.md

@@ -4,23 +4,23 @@ This page lists out the directory structure for the [atmospheric_physics](https:
 
 ## Top-level directories
 
-These directories represent code and tools that is solely contained within the atmospheric_physics repository.  If there is a sub-directory that is also an external submodule or repository it will be marked with the "(external)" label.
+These directories represent code and tools that are contained within the atmospheric_physics repository.
 
 ### **doc/**
 
-Contains files used to document the current state of the atmospheric_physics repository, such as a `ChangeLog` and the `NamesNotInDictionary.txt` file which lists all standard names that are currently  not in the official [CCPP Standard Names repo](https://github.com/ESCOMP/CCPPStandardNames).
+Contains files used to document the current state of the atmospheric_physics repository, such as a `ChangeLog` and the `NamesNotInDictionary.txt` file which lists all standard names that are currently not in the official [CCPP Standard Names repo](https://github.com/ESCOMP/CCPPStandardNames). More on the NamesNotInDictionary.txt file [here](development_workflow.md/#updating-namesnotindictionarytxt-file).
 
 ### **schemes/**
 
 Contains subdirectories for all of the CCPP-ized physics schemes, with the subdirectories containing the core physics scheme source code,
-the associated CCPP metadata files, namelist XML files, and any relevant depdendency files.
+the associated CCPP metadata files, namelist XML files, and any relevant dependency files.
 
 Note that there is a special `to_be_ccppized` subdirectory which contains source code that is needed by certain CCPP physics schemes, but which is not
-yet fully CCPP compliant (e.g. may have code that is host-model specific).
+yet fully CCPP compliant (e.g. may have code that is host-model-specific).
 
 ### **suites/**
 
-Contains CCPP Suite Definition Files (SDFs) for official scientific and production configurations of the CAM-SIMA host model.
+Contains [CCPP Suite Definition Files (SDFs)](https://ccpp-techdoc.readthedocs.io/en/v6.0.0/ConstructingSuite.html?highlight=sdf#constructing-suites) for official scientific and production configurations of the CAM-SIMA host model.
 
 ### **test/**
 
@@ -29,7 +29,7 @@ Contains code and tools used to run tests on the CCPP-ized physics schemes.
 **Subdirectories**:
 
 - cmake   - Contains cmake files needed to configure and build  unit tests.
-- docker  - Contains dockerfiles needed to configure, butild, and run unit tests.
+- docker  - Contains dockerfiles needed to configure, build, and run unit tests.
 - include - Contains utility source code needed to build and run unit tests.
-- musica  - Contains test code for the CCPP-ized [Multie-Scale Infrastructure for Chemistry Modeling (MUSICA)](https://github.com/NCAR/musica) components.
+- musica  - Contains test code for the CCPP-ized [Multi-Scale Infrastructure for Chemistry Modeling (MUSICA)](https://github.com/NCAR/musica) components.
 - test_suites - Contains test SDFs for use in CAM-SIMA snapshot regression testing.

docs/design/directory-structure.md

@@ -10,7 +10,7 @@ Please note that any modifications to the source code in these directories shoul
 
 ### **bin/**
 
-Contains the `git-fleximmod` tool for downloading needed source code and software from external repositories.  More information on `git-fleximod` can be found [here](https://github.com/ESMCI/git-fleximod).
+Contains the `git-fleximod` tool for downloading needed source code and software from external repositories.  More information on `git-fleximod` can be found [here](https://github.com/ESMCI/git-fleximod).
 
 ### **ccpp_framework/**
 
@@ -22,18 +22,18 @@ Contains the configuration files used by CIME to properly configure and build a
 
 ### **cime/**
 
-Contains the [Common Infrastructure for Modeling the Earth (CIME)](https://github.com/ESMCI/cime) tools and associated libraries.  Used by CAM-SIMA and CESM for the general configuration and building of a simulation (or "case").
+Contains the [Common Infrastructure for Modeling the Earth (CIME)](https://github.com/ESMCI/cime) tools and associated libraries.  Used by CAM-SIMA and CESM for the general configuration and building of a simulation (or "case"). See more on CIME usage in the [Creating, configuring, and running a case](../usage/creating-a-case.md) section.
 
 ### **components/**
 
 Contains the following other CESM components:
 
 - [Community Data Models for Earth Prediction Systems (CDEPS)](https://github.com/ESCOMP/CDEPS)
-- [CICE sea ice model](https://github.com/ESCOMP/CESM_CICE)
+- [Community Ice CodE sea ice model (CICE)](https://github.com/ESCOMP/CESM_CICE)
 - [Community Ice Sheet Model (CISM)](https://github.com/ESCOMP/CISM-wrapper)
 - [Community Terrestrial Systems Model (CTSM/CLM)](https://github.com/ESCOMP/CTSM)
 - [Community Mediator for Earth Prediction Systems (CMEPS)](https://github.com/ESCOMP/CMEPS)
-- [mizuRoute](https://github.com/ESCOMP/mizuRoute)
+- [Reach-based river routing model (mizuRoute)](https://github.com/ESCOMP/mizuRoute)
 - [MOdel for Scale Adaptive River Transport (MOSART)](https://github.com/ESCOMP/MOSART)
 - [River Transport Model (RTM)](https://github.com/ESCOMP/RTM)
 
@@ -68,7 +68,7 @@ Contains files needed to run certain CAM-SIMA configurations in a docker contain
 
 ### **src/**
 
-Contains all of the SIMA-specific source code needed to run the model. Additional details can be found below in the "Source directories" section.
+Contains all of the SIMA-specific source code needed to run the model. Additional details can be found below in the [Source directories](#source-src-directories) section.
 
 ### **test/**
 
@@ -110,7 +110,7 @@ Contains all of the dynamical core (dycore) source code.
 
 **Subdirectories**:
 
-- mpas/ - Contains all of the source code needed for SIMA to properly couple to the [MPAS dynamical core](https://github.com/MPAS-Dev/MPAS-Model).
+- mpas/ - Contains all of the source code needed for SIMA to properly couple to the [Model for Prediction Across Scales (MPAS) dynamical core](https://github.com/MPAS-Dev/MPAS-Model).
     - dycore/ (external) - External submodule that contains the MPAS dycore code.
 - none/ - Contains the "null" dycore source code, which allows physics and chemistry routines to be forced with atmospheric data coming directly from input files as opposed to dycore calculations.
 - se/ - Contains all of the source code needed for SIMA to properly couple to the [Spectral Element dynamical core](https://ncar.github.io/CAM/doc/build/html/cam5_scientific_guide/dynamics.html#spectral-element-dynamical-core).
@@ -126,6 +126,7 @@ Contains all of the SIMA physics and chemistry source code.
 **Subdirectories**:
 
 - ncar_ccpp/ (external) - External submodule that contains all of the code in the [atmospheric_physics](https://github.com/ESCOMP/atmospheric_physics) repo.
+    - The directory structure for atmospheric_physics can be found in the [atmospheric_physics directory structure](../atmospheric_physics/directory-structure.md) section.
 - utils/ - Contains SIMA-specific utility routines for working with the CCPP-framework and CCPP-ized physics routines.
 
 ### **utils/**