UW-536: Document ungrib driver (ufs-community#442)

* add contents of ungrib.rst

* text of ungrib yaml rst

* fix missing index updates

* removed link error and fixed text & index issues

* remove yaml/ungrib.rst link

* fixed underlines

* add missing --help text

* ungrib format updated for upcoming PR changes

* underline length fix

docs/sections/user_guide/api/index.rst

@@ -10,3 +10,4 @@ API
    rocoto
    sfc_climo_gen
    template
+   ungrib

docs/sections/user_guide/api/ungrib.rst

@@ -0,0 +1,5 @@
+``uwtools.api.ungrib``
+=============================
+
+.. automodule:: uwtools.api.ungrib
+    :members:

docs/sections/user_guide/cli/drivers/index.rst

@@ -7,3 +7,4 @@ Drivers
    chgres_cube
    fv3
    sfc_climo_gen
+   ungrib

docs/sections/user_guide/cli/drivers/ungrib.rst

@@ -0,0 +1,103 @@
+``ungrib``
+==========
+
+The ``uw`` mode for configuring and running the WRF preprocessing component ``ungrib``.
+
+.. code-block:: text
+
+   $ uw ungrib --help
+   usage: uw ungrib [-h] [--version] TASK ...
+
+   Execute Ungrib tasks
+
+   Optional arguments:
+     -h, --help
+         Show help and exit
+     --version
+         Show version info and exit
+
+   Positional arguments:
+     TASK
+       gribfile
+         A symlink to the input GRIB file
+       namelist_file
+         The namelist file
+       provisioned_run_directory
+         Run directory provisioned with all required content
+       run
+         A run
+       runscript
+         The runscript
+       vtable
+         A symlink to the Vtable file
+
+All tasks take the same arguments. For example:
+
+.. code-block:: text
+
+   $ uw ungrib run --help
+   usage: uw ungrib run --cycle CYCLE [-h] [--version] [--config-file PATH] [--batch] [--dry-run] [--graph-file PATH]
+                        [--quiet] [--verbose]
+
+   A run
+
+   Required arguments:
+     --cycle CYCLE
+         The cycle in ISO8601 format
+
+   Optional arguments:
+     -h, --help
+         Show help and exit
+     --version
+         Show version info and exit
+     --config-file PATH, -c PATH
+         Path to config file (default: read from stdin)
+     --batch
+         Submit run to batch scheduler
+     --dry-run
+         Only log info, making no changes
+     --graph-file PATH
+         Path to Graphviz DOT output [experimental]
+     --quiet, -q
+         Print no logging messages
+     --verbose, -v
+         Print all logging messages
+
+Examples
+^^^^^^^^
+
+The examples use a configuration file named ``config.yaml`` with content similar to:
+
+.. highlight:: yaml
+.. literalinclude:: ../../../../shared/ungrib.yaml
+
+
+Its contents are described in depth in section :ref:`ungrib_yaml`.
+
+* Run ``ungrib`` on an interactive node
+
+  .. code-block:: text
+
+     $ uw ungrib run --config-file config.yaml
+
+  The driver creates a ``runscript.ungrib`` file in the directory specified by ``run_dir:`` in the config and runs it, executing ``ungrib``.
+
+* Run ``ungrib`` via a batch job
+
+  .. code-block:: text
+
+     $ uw ungrib run --config-file config.yaml --batch
+
+  The driver creates a ``runscript.ungrib`` file in the directory specified by ``run_dir:`` in the config and submits it to the batch system. Running with ``--batch`` requires a correctly configured ``platform:`` block in ``config.yaml``, as well as appropriate settings in the ``execution:`` block under ``ungrib:``.
+
+* Specifying the ``--dry-run`` flag results in the driver logging messages about actions it would have taken, without actually taking any.
+
+  .. code-block:: text
+
+     $ uw ungrib run --config-file config.yaml --batch --dry-run
+
+* The ``run`` task depends on the other available tasks and executes them as prerequisites. It is possible to execute any task directly, which entails execution of any of *its* dependencies. For example, to create an ``ungrib`` run directory provisioned with all the files, directories, symlinks, etc. required per the configuration file:
+
+  .. code-block:: text
+
+     $ uw ungrib provisioned_run_directory --config-file config.yaml --batch

docs/sections/user_guide/yaml/components/index.rst

@@ -7,3 +7,4 @@ UW YAML for Components
    chgres_cube
    fv3
    sfc_climo_gen
+   ungrib

docs/sections/user_guide/yaml/components/ungrib.rst

@@ -0,0 +1,57 @@
+.. _ungrib_yaml:
+
+ungrib
+======
+
+Structured YAML to run the WRF preprocessing component ``ungrib`` is validated by JSON Schema and requires the ``ungrib:`` block, described below. If ``ungrib`` is to be run via a batch system, the ``platform:`` block, described :ref:`here <platform_yaml>`, is also required.
+
+Here is a prototype UW YAML ``ungrib:`` block, explained in detail below:
+
+.. highlight:: yaml
+.. literalinclude:: ../../../../shared/ungrib.yaml
+
+
+UW YAML for the ``ungrib:`` Block
+----------------------------------------
+
+execution:
+^^^^^^^^^^
+
+See :ref:`here <execution_yaml>` for details.
+
+
+gfs_files:
+^^^^^^^^^^
+
+Describes the GRIB-formatted files to be processed by ``ungrib``.
+
+forecast_length:
+""""""""""""""""
+
+The length of the forecast in integer hours.
+
+offset:
+"""""""
+
+How many hours earlier the external model used for boundary conditions started compared to the desired forecast cycle, in integer hours.
+
+interval_hours:
+"""""""""""""""
+
+Frequency interval of the given files, in integer hours.
+
+path:
+"""""
+
+An absolute-path template to the GRIB-formatted files to be processed by ``ungrib``. The Python ``int`` variables ``cycle_hour`` and ``forecast_hour`` will be interpolated into, e.g., ``/path/to/gfs.t{cycle_hour:02d}z.pgrb2.0p25.f{forecast_hour:03d}``. Note that this is a Python string template rather than a Jinja2 template.
+
+run_dir:
+^^^^^^^^
+
+The path to the directory where ``ungrib`` will find its namelist and write its outputs.
+
+
+vtable:
+^^^^^^^
+
+The path to the correct variable table for the file to be processed by ``ungrib``.