UW-556 XML tooling for MPAS streams files (#501)

ufs-community · Jun 6, 2024 · 6e1eff5 · 6e1eff5
1 parent 737675c
commit 6e1eff5
Show file tree

Hide file tree

Showing 40 changed files with 551 additions and 196 deletions.
diff --git a/docs/sections/contributor_guide/developer_setup.rst b/docs/sections/contributor_guide/developer_setup.rst
@@ -6,7 +6,7 @@ Creating a ``bash`` Development Shell
 
 If an existing conda (:miniforge:`Miniforge<>`, :miniconda:`Miniconda<>`, :anaconda:`Anaconda<>`, etc.) installation is available and writable, step 1 may be skipped.
 
-.. include:: ../../shared/miniforge_instructions.rst
+.. include:: /shared/miniforge_instructions.rst
 
 #. Install the :anaconda-condev:`condev package<>` into the ``base`` environment.
 

diff --git a/docs/sections/user_guide/cli/drivers/chgres_cube.rst b/docs/sections/user_guide/cli/drivers/chgres_cube.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with content similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/chgres_cube.yaml
+.. literalinclude:: /shared/chgres_cube.yaml
 
 Its contents are described in depth in section :ref:`chgres_cube_yaml`. Each of the values in the ``chgres_cube`` YAML may contain Jinja2 variables/expressions using a ``cycle`` variable, which is a Python ``datetime`` object corresponding to the FV3 cycle being run.
 
@@ -49,7 +49,7 @@ Its contents are described in depth in section :ref:`chgres_cube_yaml`. Each of
 
      $ uw chgres_cube run --config-file config.yaml --cycle 2023-12-15T18 --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
 
 * 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 a ``chgres_cube`` run directory provisioned with all the files, directories, symlinks, etc. required per the configuration file:
 

diff --git a/docs/sections/user_guide/cli/drivers/esg_grid.rst b/docs/sections/user_guide/cli/drivers/esg_grid.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/esg_grid.yaml
+.. literalinclude:: /shared/esg_grid.yaml
 
 Its contents are described in depth in section :ref:`esg_grid_yaml`.
 
@@ -49,7 +49,7 @@ The driver creates a ``runscript.esg_grid`` file in the directory specified by `
 
      $ uw esg_grid run --config-file config.yaml --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
 
 * 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 ``esg_grid`` run directory provisioned with all the files, directories, symlinks, etc. required per the configuration file:
 

diff --git a/docs/sections/user_guide/cli/drivers/fv3.rst b/docs/sections/user_guide/cli/drivers/fv3.rst
@@ -44,7 +44,7 @@ The examples use a configuration file named ``config.yaml``. Its contents are de
 
      $ uw fv3 run --config-file config.yaml --cycle 2024-02-11T12 --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
 
 * 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:
 

diff --git a/docs/sections/user_guide/cli/drivers/global_equiv_resol.rst b/docs/sections/user_guide/cli/drivers/global_equiv_resol.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/global_equiv_resol.yaml
+.. literalinclude:: /shared/global_equiv_resol.yaml
 
 Its contents are described in section :ref:`global_equiv_resol_yaml`.
 
@@ -49,4 +49,4 @@ Its contents are described in section :ref:`global_equiv_resol_yaml`.
 
      $ uw global_equiv_resol run --config-file config.yaml --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
diff --git a/docs/sections/user_guide/cli/drivers/jedi.rst b/docs/sections/user_guide/cli/drivers/jedi.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/jedi.yaml
+.. literalinclude:: /shared/jedi.yaml
 
 Its contents are described in section :ref:`jedi_yaml`.
 
@@ -49,4 +49,4 @@ The driver creates a ``runscript.jedi`` file in the directory specified by ``run
 
      $ uw jedi run --config-file config.yaml --cycle 2024-05-22T12 --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
diff --git a/docs/sections/user_guide/cli/drivers/make_hgrid.rst b/docs/sections/user_guide/cli/drivers/make_hgrid.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/make_hgrid.yaml
+.. literalinclude:: /shared/make_hgrid.yaml
 
 Its contents are described in section :ref:`make_hgrid_yaml`.
 
@@ -55,4 +55,4 @@ Its contents are described in section :ref:`make_hgrid_yaml`.
 
      $ uw make_hgrid run --config-file config.yaml --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic.rst b/docs/sections/user_guide/cli/drivers/make_solo_mosaic.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/make_solo_mosaic.yaml
+.. literalinclude:: /shared/make_solo_mosaic.yaml
 
 Its contents are described in section :ref:`make_solo_mosaic_yaml`.
 
@@ -55,4 +55,4 @@ Its contents are described in section :ref:`make_solo_mosaic_yaml`.
 
      $ uw make_solo_mosaic run --config-file config.yaml --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
diff --git a/docs/sections/user_guide/cli/drivers/mpas.rst b/docs/sections/user_guide/cli/drivers/mpas.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/mpas.yaml
+.. literalinclude:: /shared/mpas.yaml
 
 Its contents are described in depth in section :ref:`mpas_yaml`.
 
@@ -49,7 +49,7 @@ Its contents are described in depth in section :ref:`mpas_yaml`.
 
      $ uw mpas run --config-file config.yaml --cycle 2025-02-12T12 --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
 
 * 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 ``mpas`` run directory provisioned with all the files, directories, symlinks, etc. required per the configuration file:
 

diff --git a/docs/sections/user_guide/cli/drivers/mpas_init.rst b/docs/sections/user_guide/cli/drivers/mpas_init.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/mpas_init.yaml
+.. literalinclude:: /shared/mpas_init.yaml
 
 Its contents are described in depth in section :ref:`mpas_init_yaml`.
 
@@ -49,7 +49,7 @@ Its contents are described in depth in section :ref:`mpas_init_yaml`.
 
      $ uw mpas_init run --config-file config.yaml --cycle 2023-12-18T00 --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
 
 * 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 ``mpas_init`` run directory provisioned with all the files, directories, symlinks, etc. required per the configuration file:
 

diff --git a/docs/sections/user_guide/cli/drivers/sfc_climo_gen.rst b/docs/sections/user_guide/cli/drivers/sfc_climo_gen.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/sfc_climo_gen.yaml
+.. literalinclude:: /shared/sfc_climo_gen.yaml
 
 Its contents are described in depth in section :ref:`sfc_climo_gen_yaml`.
 
@@ -49,7 +49,7 @@ Its contents are described in depth in section :ref:`sfc_climo_gen_yaml`.
 
      $ uw sfc_climo_gen run --config-file config.yaml --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
 
 * 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:
 

diff --git a/docs/sections/user_guide/cli/drivers/shave.rst b/docs/sections/user_guide/cli/drivers/shave.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/shave.yaml
+.. literalinclude:: /shared/shave.yaml
 
 Its contents are described in section :ref:`shave_yaml`.
 
@@ -49,4 +49,4 @@ Its contents are described in section :ref:`shave_yaml`.
 
      $ uw shave run --config-file config.yaml --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
diff --git a/docs/sections/user_guide/cli/drivers/ungrib.rst b/docs/sections/user_guide/cli/drivers/ungrib.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/ungrib.yaml
+.. literalinclude:: /shared/ungrib.yaml
 
 Its contents are described in depth in section :ref:`ungrib_yaml`.
 
@@ -49,7 +49,7 @@ Its contents are described in depth in section :ref:`ungrib_yaml`.
 
      $ uw ungrib run --config-file config.yaml --cycle 2021-04-01T12 --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
 
 * 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:
 

diff --git a/docs/sections/user_guide/cli/drivers/upp.rst b/docs/sections/user_guide/cli/drivers/upp.rst
@@ -23,7 +23,7 @@ Examples
 The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/upp.yaml
+.. literalinclude:: /shared/upp.yaml
 
 Its contents are described in depth in section :ref:`upp_yaml`.
 
@@ -49,7 +49,7 @@ Its contents are described in depth in section :ref:`upp_yaml`.
 
      $ uw upp run --config-file config.yaml --cycle 2024-05-06T12 --leadtime 6 --batch --dry-run
 
-.. include:: ../../../../shared/key_path.rst
+.. include:: /shared/key_path.rst
 
 * 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 ``upp`` run directory provisioned with all the files, directories, symlinks, etc. required per the configuration file:
 

diff --git a/docs/sections/user_guide/cli/tools/config/realize-help.out b/docs/sections/user_guide/cli/tools/config/realize-help.out
@@ -29,7 +29,7 @@ Optional arguments:
   --key-path KEY[.KEY...]
       Dot-separated path of keys to the block to be output
   --values-needed
-      Print report of values needed to render template
+      Print report of values needed to realize config
   --total
       Require rendering of all Jinja2 variables/expressions
   --dry-run

diff --git a/docs/sections/user_guide/installation.rst b/docs/sections/user_guide/installation.rst
@@ -38,7 +38,7 @@ To create a standalone conda environment providing ``uwtools``:
 Use a Fresh Miniforge Installation
 ----------------------------------
 
-.. include:: ../../shared/miniforge_instructions.rst
+.. include:: /shared/miniforge_instructions.rst
 
 #. Continue with the `Use an Existing conda Installation`_ instructions.
 

diff --git a/docs/sections/user_guide/yaml/components/chgres_cube.rst b/docs/sections/user_guide/yaml/components/chgres_cube.rst
@@ -5,12 +5,12 @@ chgres_cube
 
 Structured YAML to run :ufs-utils:`chgres_cube<chgres-cube>` is validated by JSON Schema and requires the ``chgres_cube:`` block, described below. If ``chgres_cube`` is to be run via a batch system, the ``platform:`` block, described :ref:`here <platform_yaml>`, is also required.
 
-.. include:: ../../../../shared/injected_cycle.rst
+.. include:: /shared/injected_cycle.rst
 
 Here is a prototype UW YAML ``chgres_cube:`` block, explained in detail below:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/chgres_cube.yaml
+.. literalinclude:: /shared/chgres_cube.yaml
 
 UW YAML for the ``chgres_cube:`` Block
 --------------------------------------
@@ -25,7 +25,7 @@ namelist
 
 Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details). Namelist options are described :ufs-utils:`here<global-chgres-cube-namelist-options>`.
 
-.. include:: ../../../../shared/validate_namelist.rst
+.. include:: /shared/validate_namelist.rst
 
 run_dir
 ^^^^^^^

diff --git a/docs/sections/user_guide/yaml/components/esg_grid.rst b/docs/sections/user_guide/yaml/components/esg_grid.rst
@@ -8,7 +8,7 @@ Structured YAML to run :ufs-utils:`regional_esg_grid<regional-esg-grid>` is vali
 Here is a prototype UW YAML ``esg_grid:`` block, explained in detail below:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/esg_grid.yaml
+.. literalinclude:: /shared/esg_grid.yaml
 
 UW YAML for the ``esg_grid:`` Block
 ------------------------------------
@@ -22,7 +22,7 @@ namelist:
 ^^^^^^^^^
 Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details). Namelist options are described :ufs-utils:`regional_esg_grid<regional-esg-grid>`.
 
-.. include:: ../../../../shared/validate_namelist.rst
+.. include:: /shared/validate_namelist.rst
 
 run_dir:
 ^^^^^^^^

diff --git a/docs/sections/user_guide/yaml/components/fv3.rst b/docs/sections/user_guide/yaml/components/fv3.rst
@@ -5,12 +5,12 @@ fv3
 
 Structured YAML to run FV3 is validated by JSON Schema and requires the ``fv3:`` block, described below. If FV3 is to be run via a batch system, the ``platform:`` block, described :ref:`here <platform_yaml>`, is also required. The configuration files required by the UFS Weather Model are documented :weather-model-io:`here<model-configuration-files>`.
 
-.. include:: ../../../../shared/injected_cycle.rst
+.. include:: /shared/injected_cycle.rst
 
 Here is a prototype UW YAML ``fv3:`` block, explained in detail below:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/fv3.yaml
+.. literalinclude:: /shared/fv3.yaml
 
 UW YAML for the ``fv3:`` Block
 ------------------------------
@@ -77,7 +77,7 @@ namelist:
 
 Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details). See FV3 ``model_configure`` documentation :weather-model-io:`here<namelist-file-input-nml>`.
 
-.. include:: ../../../../shared/validate_namelist.rst
+.. include:: /shared/validate_namelist.rst
 
 run_dir:
 ^^^^^^^^

diff --git a/docs/sections/user_guide/yaml/components/global_equiv_resol.rst b/docs/sections/user_guide/yaml/components/global_equiv_resol.rst
@@ -10,7 +10,7 @@ Documentation for the UFS Utils ``global_equiv_resol`` program is :ufs-utils:`he
 Here is a prototype UW YAML ``global_equiv_resol:`` block, explained in detail below:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/global_equiv_resol.yaml
+.. literalinclude:: /shared/global_equiv_resol.yaml
 
 UW YAML for the ``global_equiv_resol:`` Block
 ---------------------------------------------

diff --git a/docs/sections/user_guide/yaml/components/jedi.rst b/docs/sections/user_guide/yaml/components/jedi.rst
@@ -5,12 +5,12 @@ jedi
 
 Structured YAML to run JEDI is validated by JSON Schema and requires the ``jedi:`` block, described below. If ``jedi`` is to be run via a batch system, the ``platform:`` block, described :ref:`here <platform_yaml>`, is also required.
 
-.. include:: ../../../../shared/injected_cycle.rst
+.. include:: /shared/injected_cycle.rst
 
 Here is a prototype UW YAML jedi: block, explained in detail below:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/jedi.yaml
+.. literalinclude:: /shared/jedi.yaml
 
 UW YAML for the ``jedi:`` Block
 -------------------------------

diff --git a/docs/sections/user_guide/yaml/components/make_hgrid.rst b/docs/sections/user_guide/yaml/components/make_hgrid.rst
@@ -11,7 +11,7 @@ Structured YAML to run :ufs-utils:`make_hgrid<make-hgrid>` is validated by JSON
 Here is a prototype UW YAML ``make_hgrid:`` block, explained in detail below:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/make_hgrid.yaml
+.. literalinclude:: /shared/make_hgrid.yaml
 
 UW YAML for the ``make_hgrid:`` Block
 -------------------------------------

diff --git a/docs/sections/user_guide/yaml/components/make_solo_mosaic.rst b/docs/sections/user_guide/yaml/components/make_solo_mosaic.rst
@@ -10,7 +10,7 @@ Documentation for the UFS Utils ``make_solo_mosaic`` program is :ufs-utils:`here
 Here is a prototype UW YAML ``make_solo_mosaic:`` block, explained in detail below:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/make_solo_mosaic.yaml
+.. literalinclude:: /shared/make_solo_mosaic.yaml
 
 UW YAML for the ``make_solo_mosaic:`` Block
 -------------------------------------------

diff --git a/docs/sections/user_guide/yaml/components/mpas.rst b/docs/sections/user_guide/yaml/components/mpas.rst
@@ -5,12 +5,12 @@ mpas
 
 Structured YAML to run MPAS is validated by JSON Schema and requires the ``mpas:`` block, described below. If ``mpas`` is to be run via a batch system, the ``platform:`` block, described :ref:`here <platform_yaml>`, is also required.
 
-.. include:: ../../../../shared/injected_cycle.rst
+.. include:: /shared/injected_cycle.rst
 
 Here is a prototype UW YAML ``mpas:`` block, explained in detail below:
 
 .. highlight:: yaml
-.. literalinclude:: ../../../../shared/mpas.yaml
+.. literalinclude:: /shared/mpas.yaml
 
 An MPAS build provides prototype versions of certain required runtime files. Here, an arbitrarily named ``user:`` block defines an ``mpas_app`` variable, pointing to the directory where MPAS was installed, to reduce duplication in references to those files.
 
@@ -75,20 +75,11 @@ namelist:
 
 Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details).
 
-.. include:: ../../../../shared/validate_namelist.rst
+.. include:: /shared/validate_namelist.rst
 
 run_dir:
 ^^^^^^^^
 
 The path to the run directory.
 
-streams:
-^^^^^^^^
-
-  **path:**
-
-  The path to the base ``streams.atmosphere`` file that comes from the MPAS build.
-
-  **values:**
-
-  The set of key-value pairs that will render the appropriate XML entries in the streams input file.
+.. include:: /shared/mpas_streams.rst