Merge branch 'develop' into text/us-157

.github/workflows/test.yaml

@@ -3,12 +3,15 @@ on:
   pull_request:
     branches:
       - develop
+      - main
   push:
     branches:
       - develop
+      - main
   workflow_dispatch:
     branches:
       - develop
+      - main
 jobs:
   test:
     name: Test

docs/conf.py

@@ -29,6 +29,7 @@
     "anaconda": ("https://www.anaconda.com/%s", "%s"),
     "anaconda-condev": ("https://anaconda.org/maddenp/condev/%s", "%s"),
     "black": ("https://black.readthedocs.io/en/stable/%s", "%s"),
+    "cmeps": ("https://escomp.github.io/CMEPS/versions/master/html/esmflds.html#%s", "%s"),
     "conda": ("https://docs.conda.io/en/latest/%s", "%s"),
     "conda-forge": ("https://conda-forge.org/%s", "%s"),
     "condev": ("https://github.com/maddenp/condev/%s", "%s"),
@@ -50,7 +51,9 @@
     "rst": ("https://www.sphinx-doc.org/en/master/usage/restructuredtext/%s", "%s"),
     "rtd": ("https://readthedocs.org/projects/uwtools/%s", "%s"),
     "ufs": ("https://ufscommunity.org/%s", "%s"),
+    "ufs-weather-model": ("https://github.com/ufs-community/ufs-weather-model/%s", "%s"),
     "uwtools": ("https://github.com/ufs-community/uwtools/%s", "%s"),
+    "weather-model-io": ("https://ufs-weather-model.readthedocs.io/en/latest/InputsOutputs.html#%s", "%s"),
 }
 
 def setup(app):

docs/sections/contributor_guide/documentation.rst

@@ -40,10 +40,12 @@ Please follow these guidelines when contributing to the documentation:
 * Use one blank line between documentation elements (headers, paragraphs, code blocks, etc.) unless additional lines are necessary to achieve correctly formatted HTML.
 * Remove all trailing whitespace.
 * In general, avoid pronouns like "we" and "you". (Using "we" may be appropriate when synonymous with "The UW Team", "The UFS Community", etc., when the context is clear.) Prefer direct, factual statements about what the code does, requires, etc.
-* The synopsis information printed by ``uw [mode [submode]] --help`` is automatically wrapped and indented based on current terminal size. For visual consistency, please set your terminal width to 100 columns when running such commands to produce output to copy into the docs.
+* Use the `Oxford Comma <https://en.wikipedia.org/wiki/Serial_comma>`_.
+* The synopsis information printed by ``uw [mode [action]] --help`` is automatically wrapped and indented based on current terminal size. For visual consistency, please set your terminal width to 100 columns when running such commands to produce output to copy into the docs.
 * Follow the :rst:`RST Sections<basics.html#sections>` guidelines, underlining section headings with = characters, subsections with - characters, and subsubsections with ^ characters. If a further level of refinement is needed, use " to underline paragraph headers.
 * In [[sub]sub]section titles, capitalize all "principal" words. In practice this usually means all words but articles (a, an, the), logicals (and, etc.), and prepositions (for, of, etc.). Always fully capitalize acronyms (e.g., YAML).
 * Never capitalize proper names when their owners do not (e.g., write `"pandas" <https://pandas.pydata.org/>`_, not "Pandas", even at the start of a sentence) or when referring to a software artifact (e.g., write ``numpy`` when referring to the library, and "NumPy" when referring to the project).
+* When referring to YAML constructs, `block` refers to an entry whose values is a nested collection of key/value pairs, while `entry` is a single key/value pair.
 * When using the ``.. code-block::`` directive, align the actual code with the word ``code``. Also, when ``.. code-block::`` directives appear in bulleted or numberd lists, align them with the text following the space to the right of the bullet/number. For example:
 
   .. code-block:: text

docs/sections/user_guide/cli/mode_forecast.rst

@@ -45,6 +45,8 @@ The ``uw`` mode for configuring and running forecasts.
          Path to output batch file (defaults to stdout)
      --dry-run
          Only log info, making no changes
+     --debug
+         Print all log messages, plus any unhandled exception's stack trace (implies --verbose)
      --quiet, -q
          Print no logging messages
      --verbose, -v
@@ -55,4 +57,32 @@ The ``uw`` mode for configuring and running forecasts.
 Examples
 ^^^^^^^^
 
-TBD
+The examples use a configuration file named ``config.yaml``. Its contents are described in depth in Section :ref:`forecast_yaml`.
+
+* Run an FV3 forecast on an interactive node
+
+  .. code-block:: sh
+
+    $ uw forecast run -c config.yaml --cycle 2024-01-09T12 --model FV3
+
+  The forecast will run on the node where you have invoked this command. Optionally, capture the output in a log file using shell redirection.
+
+* Run an FV3 forecast using a batch system
+
+  .. code-block:: sh
+
+    $ uw forecast run -c config.yaml --cycle 2024-01-09T12 --model FV3 --batch-script submit_fv3.sh
+
+  This command writes a file named ``submit_fv3.sh`` and submits it to the batch system.
+
+* With the ``--dry-run`` flag specified, nothing is written to ``stdout``, but a report of all the directories, files, symlinks, etc., that would have been created are logged to ``stderr``. None of these artifacts will actually be created and no jobs will be executed or submitted to the batch system.
+
+  .. code-block:: sh
+
+    $ uw forecast run -c config.yaml --cycle 2024-01-09T12 --model FV3 --batch-script --dry-run
+
+* Request verbose log output
+
+  .. code-block:: sh
+
+    $ uw forecast run -c config.yaml --cycle 2024-01-09T12 --model FV3 -v

docs/sections/user_guide/cli/mode_rocoto.rst

@@ -44,6 +44,8 @@ More information about the structured UW YAML file for Rocoto can be found :any:
          Path to input file (defaults to stdin)
      --output-file PATH, -o PATH
          Path to output file (defaults to stdout)
+     --debug
+         Print all log messages, plus any unhandled exception's stack trace (implies --verbose)
      --quiet, -q
          Print no logging messages
      --verbose, -v
@@ -216,6 +218,8 @@ The examples in this section use a UW YAML file called ``rocoto.yaml`` with the
          Show help and exit
      --input-file PATH, -i PATH
          Path to input file (defaults to stdin)
+     --debug
+         Print all log messages, plus any unhandled exception's stack trace (implies --verbose)
      --quiet, -q
          Print no logging messages
      --verbose, -v

docs/sections/user_guide/cli/mode_template.rst

@@ -51,6 +51,8 @@ The ``uw`` mode for handling :jinja2:`Jinja2 templates<templates>`.
          Print report of values needed to render template
      --dry-run
          Only log info, making no changes
+     --debug
+         Print all log messages, plus any unhandled exception's stack trace (implies --verbose)
      --quiet, -q
          Print no logging messages
      --verbose, -v
@@ -173,6 +175,8 @@ and a YAML file called ``values.yaml`` with the following contents:
      [2023-12-18T23:25:01]    DEBUG Read initial values from values.yaml
      Hello, World!
 
+  If additional information is needed, ``--debug`` can be used which will return the stack trace from any unhandled exception as well.
+
   Note that ``uw`` logs to ``stderr`` and writes non-log output to ``stdout``, so the streams can be redirected separately:
 
   .. code-block:: text
@@ -248,6 +252,8 @@ and a YAML file called ``values.yaml`` with the following contents:
          Path to output file (defaults to stdout)
      --dry-run
          Only log info, making no changes
+     --debug
+         Print all log messages, plus any unhandled exception's stack trace (implies --verbose)
      --quiet, -q
          Print no logging messages
      --verbose, -v

docs/sections/user_guide/uw_yaml/field_table_yaml.rst

@@ -0,0 +1,52 @@
+.. _defining_a_field_table:
+
+Defining a ``field_table``
+==========================
+
+The :ufs-weather-model:`UFS Weather Model<>` requires as one of its inputs (:weather-model-io:`documented here<model-configuration-files>`) a ``field_table`` file in a :weather-model-io:`custom format<field-table-file>`. Its contents can be defined in a UW YAML, then created with ``uwtools``.
+
+To generate a given ``field_table`` entry with the form:
+
+.. code-block:: text
+
+   "TRACER", "atmos_mod", "sphum"
+             "longname",     "specific humidity"
+             "units",        "kg/kg"
+             "profile_type", "fixed", "surface_value=3.e-6" /
+
+Entries can be represented in YAML with the form:
+
+.. code-block:: text
+
+   sphum:
+     longname: specific humidity
+     units: kg/kg
+     profile_type:
+       name: fixed
+       surface_value: 3.e-6
+
+
+Additional tracers may be added at the same level of YAML indentation as ``sphum:`` in the above example.
+
+UW YAML Keys
+------------
+
+``sphum:``
+^^^^^^^^^^
+
+The short name of the tracer, to create the corresponding ``field_table`` entry's first line.
+
+``longname:``
+^^^^^^^^^^^^^
+
+The descriptive name of the tracer.
+
+``units:``
+^^^^^^^^^^
+
+The units of the tracer, to create the corresponding ``field_table`` entry's ``"units"`` line.
+
+``profile_type:``
+^^^^^^^^^^^^^^^^^
+
+This block requires a ``name:`` entry that describes the profile type. Acceptable values (per the ``field_table`` spec) are ``fixed`` or ``profile``. The ``surface_value:`` is required in both cases, while the ``top_value:`` is required for only the ``profile`` option.