Document the generate_workflows.sh script (#3028)

This adds readthedocs documentation for the new generate_workflows.sh
script to the testing section. It also fixes a few small existing issues
in the documentation.

docs/source/clone.rst

@@ -9,7 +9,7 @@ Quick Instructions
 Quick clone/build/link instructions (more detailed instructions below).
 
 .. note::
-   Here we are making the assumption that you are using the workflow to run an experiment and so are working from the authoritative repository. If you are using a development branch then follow the instructions in :doc:`development.rst`. Once you do that you can follow the instructions here with the only difference being the repository/fork you are cloning from.
+   Here we are making the assumption that you are using the workflow to run an experiment and so are working from the authoritative repository. If you are using a development branch then follow the instructions in :doc:`development`. Once you do that you can follow the instructions here with the only difference being the repository/fork you are cloning from.
 
 Clone the `global-workflow` and `cd` into the `sorc` directory:
 

docs/source/development.rst

@@ -12,6 +12,7 @@ Code managers
 
  * Kate Friedman - @KateFriedman-NOAA / [email protected]
  * Walter Kolczynski - @WalterKolczynski-NOAA / [email protected]
+ * David Huber - @DavidHuber-NOAA / [email protected]
 
 .. _development:
 
@@ -70,7 +71,29 @@ The following steps should be followed in order to make changes to the develop b
 Development Tools
 =================
 
-See the ``/test`` folder in global-workflow for available development and testing tools.
+Two sets of testing are available for use by developers.  The first is the capability to run continuous integration tests locally and the second are a set of comparison tools.
+
+---------------------------
+Continuous Integration (CI)
+---------------------------
+
+The global workflow comes fitted with a suite of system tests that run various types of workflow.  These tests are commonly run for pull requests before they may be merged into the develop branch.  At a minimum, developers are expected to run the CI test(s) that will be impacted by their changes on at least one platform.
+
+The commonly run tests are written in YAML format and can be found in the ``ci/cases/pr`` directory.  The ``workflow/generate_workflows.sh`` tool is available to aid running these cases.  See the help documentation by running ``./generate_workflows.sh -h``.  The script has the capability to prepare the EXPDIR and COMROOT directories for a specified or implied suite of CI tests (see :doc:`setup` for details on these directories).  The script also has options to automatically build and run all tests for a given system (i.e. GFS or GEFS and a placeholder for SFS).  For instance, to build the workflow and run all of the GFS tests, one would execute
+
+::
+
+    cd workflow
+    ./generate_workflows.sh -A "your_hpc_account" -b -G -c /path/to/root/directory
+
+where:
+
+    * ``-A`` is used to specify the HPC (slurm or PBS) account to use
+    * ``-b`` indicates that the workflow should be built fresh
+    * ``-G`` specifies that all of the GFS cases should be run (this also influences the build flags to use)
+    * ``-c`` tells the tool to append the rocotorun commands for each experiment to your crontab
+
+More details on how to use the tool are provided by running ``generate_workflows.sh -h``.
 
 ----------------
 Comparison Tools

docs/source/hpc.rst

@@ -90,9 +90,9 @@ Optimizing the global workflow on S4
 
 The S4 cluster is relatively small and so optimizations are recommended to improve cycled runtimes. Please contact Innocent Souopgui ([email protected]) if you are planning on running a cycled experiment on this system to obtain optimized configuration files.
 
-========================================
+==================================================
 Stacksize on R&Ds (Hera, Orion, Hercules, Jet, S4)
-========================================
+==================================================
 
 Some GFS components, like the UPP, need an unlimited stacksize. Add the following setting into your appropriate .*rc file to support these components:
 

docs/source/init.rst

@@ -301,7 +301,7 @@ Operations/production output location on HPSS: /NCEPPROD/hpssprod/runhistory/rh
 |                |                                 |                                                                             |                                |
 |                |   gfs.t. ``hh`` z.sfcanl.nc     |                                                                             |                                |
 +----------------+---------------------------------+-----------------------------------------------------------------------------+--------------------------------+
-| v16.2[3]+ ops  |   gfs.t. ``hh`` z.atmanl.nc     | com_gfs_ ``gfs_ver`` _gfs. ``yyyymmdd`` _ ``hh`` .gfs_nca.tar               | gfs. ``yyyymmdd`` /``hh``/atmos|
+| v16.2[3]+ ops  |   gfs.t. ``hh`` z.atmanl.nc     | com_gfs\_ ``gfs_ver`` _gfs. ``yyyymmdd`` _ ``hh`` .gfs_nca.tar              | gfs. ``yyyymmdd`` /``hh``/atmos|
 |                |                                 |                                                                             |                                |
 |                |   gfs.t. ``hh`` z.sfcanl.nc     |                                                                             |                                |
 +----------------+---------------------------------+-----------------------------------------------------------------------------+--------------------------------+

docs/source/setup.rst

@@ -1,3 +1,5 @@
+.. _experiment-setup:
+
 ================
 Experiment Setup
 ================
@@ -179,8 +181,6 @@ where:
    * ``$EXPDIR`` is the path to your experiment directory where your configs will be placed and where you will find your workflow monitoring files (i.e. rocoto database and xml file). DO NOT include PSLOT folder at end of path, it will be built for you. [default: $HOME]
    * ``$ICSDIR`` is the path to the ICs for your run if generated separately. [default: None]
 
-.. [#]  More Coupled configurations in cycled mode are currently under development and not yet available
-
 Example:
 
 ::

docs/source/wave.rst

@@ -79,16 +79,16 @@ While the creation of these files are generally considered out of scope of this
 * Instructions for creating mesh.${WAVEGRID}.nc can be found at https://ufs-weather-model.readthedocs.io/en/latest/InputsOutputs.html#ww3 
 * The ww3_gint.WHTGRIDINT.bin.${WAVEGRID} can be created by running the ww3_gint routine as desired and then saved. 
 
-Once the new fix files have been created, :ref:`open an issue to have the master fix file directory updated<https://github.com/NOAA-EMC/global-workflow/issues/new?assignees=KateFriedman-NOAA%2CWalterKolczynski-NOAA&labels=Fix+Files&projects=&template=fix_file.md>`. This is a separate step than the process to update the workflow below.
+Once the new fix files have been created, `open an issue to have the master fix file directory updated <https://github.com/NOAA-EMC/global-workflow/issues/new?assignees=KateFriedman-NOAA%2CWalterKolczynski-NOAA&labels=Fix+Files&projects=&template=fix_file.md>`. This is a separate step than the process to update the workflow below.
 
 ********************************
 Updating Config and Script Files  
 ******************************** 
 
 You will need to update the following files: 
 
-* parm/config/*/config.ufs
-* parm/config/*/config.wave
+* parm/config/\*/config.ufs
+* parm/config/\*/config.wave
 * scripts/exgfs_wave_post_gridded_sbs.sh
 
 You will need to add the following files: