UW-509 docs for sfc_climo_gen driver (#412)

docs/conf.py

@@ -10,7 +10,7 @@
 with open("../recipe/meta.json", "r", encoding="utf-8") as f:
     _metadata = json.loads(f.read())
 
-autodoc_mock_imports = ["f90nml", "iotaa", "jsonschema", "lxml"]
+autodoc_mock_imports = ["f90nml", "iotaa", "jsonschema", "lxml", "referencing"]
 copyright = str(dt.datetime.now().year)
 extensions = ["sphinx.ext.autodoc", "sphinx.ext.extlinks", "sphinx.ext.intersphinx"]
 extlinks_detect_hardcoded_links = True
@@ -51,6 +51,7 @@
     "rocoto": ("https://christopherwharrop.github.io/rocoto/%s", "%s"),
     "rst": ("https://www.sphinx-doc.org/en/master/usage/restructuredtext/%s", "%s"),
     "rtd": ("https://readthedocs.org/projects/uwtools/%s", "%s"),
+    "sfc-climo-gen": ("https://ufs-community.github.io/UFS_UTILS/sfc_climo_gen/%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"),

docs/index.rst

@@ -104,7 +104,13 @@ FV3
 | **CLI**: ``uw fv3 -h``
 | **API**: ``import uwtools.api.drivers.fv3``
 
-Provided with a valid UW YAML configuration file and a forecast-cycle value, ``uw fv3`` can prepare a fully provisioned FV3 run directory, execute FV3 directly, or can submit an FV3 batch job to an HPC scheduler.
+sfc_climo_gen
+^^^^^^^^^^^^^
+
+| **CLI**: ``uw sfc_climo_gen -h``
+| **API**: ``import uwtools.api.drivers.sfc_climo_gen``
+
+Provided with a valid UW YAML configuration file, and CLI arguments when required, ``uw`` can prepare a fully provisioned run directory and execute a component either directly on the current system, or via a batch job submitted to an HPC scheduler.
 
 Over time, we'll add many other drivers to support a variety of UFS components from pre-processing to post-processing, along with many data assimilation components.
 

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

@@ -0,0 +1,8 @@
+Drivers
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   mode_fv3
+   mode_sfc_climo_gen

docs/sections/user_guide/cli/mode_fv3.rst → docs/sections/user_guide/cli/drivers/mode_fv3.rst

@@ -17,27 +17,27 @@ The ``uw`` mode for configuring and running FV3.
    Positional arguments:
      TASK
        boundary_files
-         The FV3 lateral boundary-condition files
+         Lateral boundary-condition files
        diag_table
-         The FV3 diag_table file
+         The diag_table file
        field_table
-         The FV3 field_table file
+         The field_table file
        files_copied
-         Files copied for FV3 run
+         Files copied for run
        files_linked
-         Files linked for FV3 run
+         Files linked for run
        model_configure
-         The FV3 model_configure file
+         The model_configure file
        namelist_file
-         The FV3 namelist file
+         The namelist file
        provisioned_run_directory
-         The run directory provisioned with all required content
+         Run directory provisioned with all required content
        restart_directory
-         The FV3 RESTART directory
+         The RESTART directory
        run
-         FV3 run execution
+         A run
        runscript
-         A runscript suitable for submission to the scheduler
+         The runscript
 
 All tasks take the same arguments. For example:
 
@@ -47,7 +47,7 @@ All tasks take the same arguments. For example:
    usage: uw fv3 run --config-file PATH --cycle CYCLE [-h] [--batch] [--dry-run] [--debug] [--quiet]
                      [--verbose]
 
-   FV3 run execution
+   A run
 
    Required arguments:
      --config-file PATH, -c PATH
@@ -80,15 +80,15 @@ The examples use a configuration file named ``config.yaml``. Its contents are de
 
      $ uw fv3 run --config-file config.yaml --cycle 2024-02-11T12
 
-  The driver creates a ``runscript`` file in the directory specified by ``run_dir`` in the config and runs it, executing FV3.
+  The driver creates a ``runscript`` file in the directory specified by ``run_dir:`` in the config and runs it, executing FV3.
 
 * Run FV3 via a batch job
 
   .. code-block:: text
 
      $ uw fv3 run --config-file config.yaml --cycle 2024-02-11T12 --batch
 
-  The driver creates a ``runscript`` 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 ``fv3``.
+  The driver creates a ``runscript`` 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 ``fv3:``.
 
 * Specifying the ``--dry-run`` flag results in the driver logging messages about actions it would have taken, without actually taking any.
 
@@ -98,6 +98,6 @@ The examples use a configuration file named ``config.yaml``. Its contents are de
 
 * 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 FV3 run directory provisioned with all the files, directories, symlinks, etc. required per the configuration file:
 
-  .. code-block: text
+  .. code-block:: text
 
      $ uw fv3 provisioned_run_directory --config-file config.yaml --cycle 2024-02-11T12 --batch

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

@@ -0,0 +1,93 @@
+Mode ``sfc_climo_gen``
+======================
+
+The ``uw`` mode for configuring and running the :sfc-climo-gen:`sfc_climo_gen<>` component.
+
+.. code-block:: text
+
+   $ uw sfc_climo_gen --help
+   usage: uw sfc_climo_gen [-h] TASK ...
+
+   Execute sfc_climo_gen tasks
+
+   Optional arguments:
+     -h, --help
+         Show help and exit
+
+   Positional arguments:
+     TASK
+       namelist_file
+         The namelist file
+       provisioned_run_directory
+         Run directory provisioned with all required content
+       run
+         Run execution
+       runscript
+         The runscript
+
+All tasks take the same arguments. For example:
+
+.. code-block:: text
+
+   $ uw sfc_climo_gen run --help
+   usage: uw sfc_climo_gen run --config-file PATH [-h] [--batch] [--dry-run] [--debug] [--quiet]
+                               [--verbose]
+
+   Run execution
+
+   Required arguments:
+     --config-file PATH, -c PATH
+         Path to config file
+
+   Optional arguments:
+     -h, --help
+         Show help and exit
+     --batch
+         Submit run to batch scheduler
+     --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
+         Print all logging messages
+
+
+Examples
+^^^^^^^^
+
+The examples use a configuration file named ``config.yaml`` with content similar to:
+
+.. highlight:: yaml
+.. literalinclude:: ../../../../shared/sfc_climo_gen.yaml
+
+Its contents are described in depth in section :ref:`sfc_climo_gen_yaml`.
+
+* Run ``sfc_climo_gen`` on an interactive node
+
+  .. code-block:: text
+
+     $ uw sfc_climo_gen run --config-file config.yaml
+
+  The driver creates a ``runscript`` file in the directory specified by ``run_dir:`` in the config and runs it, executing ``sfc_climo_gen``.
+
+* Run ``sfc_climo_gen`` via a batch job
+
+  .. code-block:: text
+
+     $ uw sfc_climo_gen run --config-file config.yaml --batch
+
+  The driver creates a ``runscript`` 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 ``sfc_climo_gen:``.
+
+* 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 sfc_climo_gen 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 ``sfc_climo_gen`` run directory provisioned with all the files, directories, symlinks, etc. required per the configuration file:
+
+  .. code-block:: text
+
+     $ uw sfc_climo_gen provisioned_run_directory --config-file config.yaml --batch

docs/sections/user_guide/cli/index.rst

@@ -2,9 +2,7 @@ CLI
 ===
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   mode_config
-   mode_fv3
-   mode_rocoto
-   mode_template
+   drivers/index
+   tools/index

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

@@ -0,0 +1,9 @@
+Tools
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   mode_config
+   mode_rocoto
+   mode_template