Add a uw rocoto iterate action (#766)

Author: maddenp-cu

docs/index.rst

@@ -30,24 +30,24 @@ Configuration Management
 
 The config tool suite helps you compare, transform, modify, and even validate your configuration. The package supports YAML, shell, Fortran namelist, and INI file formats. Configuration in any of these formats may use :jinja2:`Jinja2 syntax<templates>` to express values. These values can reference others, or compute new values by evaluating mathematical expressions, building paths, manipulating strings, etc.
 
-Compare Mode
-""""""""""""
+Compare Action
+""""""""""""""
 
 When the Linux diff tool just doesn't work for comparing unordered namelists with mixed-case keys, this is your go-to! The Fortran namelists are the *real* catalyst behind this gem, but it also works on the other configuration formats.
 
 | :any:`CLI documentation with examples<cli_config_compare_examples>`
 
-Realize Mode
-""""""""""""
+Realize Action
+""""""""""""""
 
-This mode renders values created by :jinja2:`Jinja2 templates<templates>`, and lets you override values in one file or object with those from others, not necessarily with the same configuration format. With ``uwtools``, you can even reference the contents of other files to build up a configuration from its pieces.
+To realize a config is to render values encoded in :jinja2:`Jinja2 expressions<templates/#expressions>`, potentially overriding values in one file or object with those from others, not necessarily with the same configuration format. With ``uwtools``, you can even reference the contents of other files to build up a configuration from its pieces.
 
 | :any:`CLI documentation with examples<cli_config_realize_examples>`
 
-Validate Mode
-"""""""""""""
+Validate Action
+"""""""""""""""
 
-In this mode, you can provide a :json-schema:`JSON Schema<>` file alongside your configuration to validate that it meets the requirements set by the schema. We've enabled robust logging to make it easier to repair your configs when problems arise.
+Provide a :json-schema:`JSON Schema<>` file alongside your configuration to validate that it meets the requirements set by the schema. We've enabled robust logging to make it easier to repair your configs when problems arise.
 
 | :any:`CLI documentation with examples<cli_config_validate_examples>`
 
@@ -57,15 +57,15 @@ Templating
 | **CLI**: ``uw template -h``
 | **API**: ``import uwtools.api.template``
 
-Render Mode
-"""""""""""
+Render Action
+"""""""""""""
 
-The ``render`` mode that gives you the full power of rendering a :jinja2:`Jinja2 template<templates>` in the same easy-to-use interface as your other workflow tools.
+This gives you the full power of rendering a :jinja2:`Jinja2 template<templates>` in the same easy-to-use interface as your other workflow tools.
 
 | :any:`CLI documentation with examples<cli_template_render_examples>`
 
-Translate Mode
-""""""""""""""
+Translate Action
+""""""""""""""""
 
 This tool helps transform legacy configuration files templated with the atparse tool (common at :noaa:`NOAA<>`) into :jinja2:`Jinja2 templates<templates>` for use with the ``uw config realize`` and ``uw template render`` tools, or their API equivalents.
 
@@ -87,25 +87,32 @@ There is a video demonstration of the use of the ``uw fs`` tool (formerly ``uw f
 
    <iframe src="https://www.youtube.com/embed/b2HXOlt-Ulw" allowfullscreen frameborder="0" height="315" width="560"></iframe>
 
-Rocoto Configurability
-^^^^^^^^^^^^^^^^^^^^^^
+Rocoto Support
+^^^^^^^^^^^^^^
 
 | **CLI**: ``uw rocoto -h``
 | **API**: ``import uwtools.api.rocoto``
 
 This tool is all about creating a configurable interface to the :rocoto:`Rocoto<>` workflow manager tool that produces the Rocoto XML for a totally arbitrary set of tasks. The ``uwtools`` package defines a structured YAML interface that relies on tasks you define to run. Paired with the uw config tool suite, this interface becomes highly configurable and requires no XML syntax!
 
-Realize Mode
-""""""""""""
+Iterate Action
+""""""""""""""
+
+Given a Rocoto XML workflow document, invoke Rocoto in a loop, monitoring its progress, until a specified task is complete.
+
+| :any:`CLI documentation with examples<cli_rocoto_iterate_examples>`
+
+Realize Action
+""""""""""""""
 
 This is where you put in your structured YAML that defines your workflow of choice, and it pops out a verified Rocoto XML.
 
 | :any:`CLI documentation with examples<cli_rocoto_realize_examples>`
 
-Validate Mode
-"""""""""""""
+Validate Action
+"""""""""""""""
 
-Do you already have a Rocoto XML but don't want to run Rocoto to make sure it works? Use the validate mode to check to see if Rocoto will be happy.
+Do you already have a Rocoto XML but don't want to run Rocoto to make sure it works? Use ``rocoto validate`` to check to see if Rocoto will be happy.
 
 | :any:`CLI documentation with examples<cli_rocoto_validate_examples>`
 

docs/sections/contributor_guide/developer_setup.rst

@@ -63,7 +63,7 @@ As an alternative to installing the :anaconda-condev:`pre-built package<>`, the
 .. code-block:: text
 
    # Activate your conda. Optionally, activate a non-'base' environment.
-   conda install -y conda-build conda-verify
+   conda install -y conda-build
    git clone https://github.com/maddenp/condev.git
    make -C condev package
    conda install -y -c $CONDA_PREFIX/conda-bld -c conda-forge --override-channels condev

docs/sections/user_guide/cli/Makefile.outputs

@@ -10,6 +10,12 @@ all: $(OUTPUTS)
 $(OUTPUTS):
 	@bash $(basename $@).cmd >$@ 2>&1 | true
 
+# The following targets support semi-automated output generation: They will not run automatically,
+# but can be manually invoked (e.g. "make foo.out" given a "foo.txt" command file) to update .out
+# files. They must be invoked in a context where all commands in the .txt file are available, e.g.
+# on an HPC where the "hsi" or "rocotorun" commands are on PATH, if those are ultimately called by
+# the recipe.
+
 %.out: %.txt %.yaml
 	@bash $< >$@ 2>&1 | true
 

docs/sections/user_guide/cli/drivers/chgres_cube/run-help.out

@@ -19,7 +19,7 @@ Optional arguments:
   --config-file PATH, -c PATH
       Path to UW YAML config file (default: read from stdin)
   --batch
-      Submit run to batch scheduler
+      Submit job to batch scheduler
   --dry-run
       Only log info, making no changes
   --graph-file PATH

docs/sections/user_guide/cli/drivers/esg_grid/run-help.out

@@ -13,7 +13,7 @@ Optional arguments:
   --config-file PATH, -c PATH
       Path to UW YAML config file (default: read from stdin)
   --batch
-      Submit run to batch scheduler
+      Submit job to batch scheduler
   --dry-run
       Only log info, making no changes
   --graph-file PATH

docs/sections/user_guide/cli/drivers/filter_topo/run-help.out

@@ -13,7 +13,7 @@ Optional arguments:
   --config-file PATH, -c PATH
       Path to UW YAML config file (default: read from stdin)
   --batch
-      Submit run to batch scheduler
+      Submit job to batch scheduler
   --dry-run
       Only log info, making no changes
   --graph-file PATH

docs/sections/user_guide/cli/drivers/fv3/run-help.out

@@ -17,7 +17,7 @@ Optional arguments:
   --config-file PATH, -c PATH
       Path to UW YAML config file (default: read from stdin)
   --batch
-      Submit run to batch scheduler
+      Submit job to batch scheduler
   --dry-run
       Only log info, making no changes
   --graph-file PATH

docs/sections/user_guide/cli/drivers/global_equiv_resol/run-help.out

@@ -13,7 +13,7 @@ Optional arguments:
   --config-file PATH, -c PATH
       Path to UW YAML config file (default: read from stdin)
   --batch
-      Submit run to batch scheduler
+      Submit job to batch scheduler
   --dry-run
       Only log info, making no changes
   --graph-file PATH

docs/sections/user_guide/cli/drivers/ioda/run-help.out

@@ -17,7 +17,7 @@ Optional arguments:
   --config-file PATH, -c PATH
       Path to UW YAML config file (default: read from stdin)
   --batch
-      Submit run to batch scheduler
+      Submit job to batch scheduler
   --dry-run
       Only log info, making no changes
   --graph-file PATH

docs/sections/user_guide/cli/drivers/jedi/run-help.out

@@ -17,7 +17,7 @@ Optional arguments:
   --config-file PATH, -c PATH
       Path to UW YAML config file (default: read from stdin)
   --batch
-      Submit run to batch scheduler
+      Submit job to batch scheduler
   --dry-run
       Only log info, making no changes
   --graph-file PATH