Add --schema-file option to internal drivers (#592)

docs/conf.py

@@ -14,6 +14,7 @@
 autodoc_mock_imports = ["f90nml", "iotaa", "jsonschema", "lxml", "referencing"]
 autodoc_typehints = "description"
 copyright = str(dt.datetime.now().year)
+exclude_patterns = ["**/shared/*.rst"]
 extensions = ["sphinx.ext.autodoc", "sphinx.ext.extlinks", "sphinx.ext.intersphinx"]
 extlinks_detect_hardcoded_links = True
 html_logo = os.path.join("static", "ufs.png")

docs/sections/user_guide/cli/Makefile

@@ -1,4 +1,4 @@
-SUBDIRS = $(shell find . -maxdepth 1 -mindepth 1 -type d)
+SUBDIRS = $(shell find . -maxdepth 1 -mindepth 1 -type d | sort)
 
 .PHONY: all $(SUBDIRS)
 

docs/sections/user_guide/cli/drivers/Makefile

@@ -0,0 +1,8 @@
+SUBDIRS = $(filter-out ./shared,$(shell find . -maxdepth 1 -mindepth 1 -type d | sort))
+
+.PHONY: all $(SUBDIRS)
+
+all: $(SUBDIRS)
+
+$(SUBDIRS):
+	$(MAKE) -C $@ -j

docs/sections/user_guide/cli/drivers/cdeps/help.rst

@@ -0,0 +1 @@
+../shared/help.rst

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

@@ -1,23 +1,11 @@
 ``cdeps``
 =========
 
-.. include:: /shared/idempotent.rst
+.. include:: ../shared/idempotent.rst
 
 The ``uw`` mode for configuring and running the :CDEPS:`cdeps<>` component.
 
-.. literalinclude:: cdeps/help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: cdeps/help.out
-   :language: text
-
-All tasks take the same arguments. For example:
-
-.. literalinclude:: cdeps/run-help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: cdeps/run-help.out
-   :language: text
+.. include:: help.rst
 
 Examples
 ^^^^^^^^
@@ -45,10 +33,4 @@ Its contents are described in depth in section :ref:`cdeps_yaml`. Each of the va
 
 .. include:: /shared/key_path.rst
 
-* Specifying the ``--show-schema`` flag, with no other options, prints the driver's schema:
-
-.. literalinclude:: cdeps/show-schema.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: cdeps/show-schema.out
-   :language: text
+.. include:: schema-options.rst

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

@@ -1,6 +1,6 @@
 usage: uw cdeps atm --cycle CYCLE [-h] [--version] [--config-file PATH]
                     [--dry-run] [--graph-file PATH] [--key-path KEY[.KEY...]]
-                    [--quiet] [--verbose]
+                    [--schema-file PATH] [--quiet] [--verbose]
 
 The data atmosphere configuration with all required content
 
@@ -22,6 +22,8 @@ Optional arguments:
   --key-path KEY[.KEY...]
       Dot-separated path of keys leading through the config to the driver's
       configuration block
+  --schema-file PATH
+      Path to schema file to use for validation
   --quiet, -q
       Print no logging messages
   --verbose, -v

docs/sections/user_guide/cli/drivers/cdeps/schema-options.rst

@@ -0,0 +1 @@
+../shared/schema-options.rst

docs/sections/user_guide/cli/drivers/chgres_cube/help.rst

@@ -0,0 +1 @@
+../shared/help.rst

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

@@ -1,23 +1,11 @@
 ``chgres_cube``
 ===============
 
-.. include:: /shared/idempotent.rst
+.. include:: ../shared/idempotent.rst
 
 The ``uw`` mode for configuring and running the :ufs-utils:`chgres_cube<chgres-cube>` component.
 
-.. literalinclude:: chgres_cube/help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: chgres_cube/help.out
-   :language: text
-
-All tasks take the same arguments. For example:
-
-.. literalinclude:: chgres_cube/run-help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: chgres_cube/run-help.out
-   :language: text
+.. include:: help.rst
 
 Examples
 ^^^^^^^^
@@ -59,10 +47,4 @@ Its contents are described in depth in section :ref:`chgres_cube_yaml`. Each of
 
      $ uw chgres_cube provisioned_rundir --config-file config.yaml --cycle 2023-12-15T18 --batch
 
-* Specifying the ``--show-schema`` flag, with no other options, prints the driver's schema:
-
-.. literalinclude:: chgres_cube/show-schema.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: chgres_cube/show-schema.out
-   :language: text
+.. include:: schema-options.rst

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

@@ -1,6 +1,7 @@
 usage: uw chgres_cube run --cycle CYCLE [-h] [--version] [--config-file PATH]
                           [--batch] [--dry-run] [--graph-file PATH]
-                          [--key-path KEY[.KEY...]] [--quiet] [--verbose]
+                          [--key-path KEY[.KEY...]] [--schema-file PATH]
+                          [--quiet] [--verbose]
 
 A run
 
@@ -24,6 +25,8 @@ Optional arguments:
   --key-path KEY[.KEY...]
       Dot-separated path of keys leading through the config to the driver's
       configuration block
+  --schema-file PATH
+      Path to schema file to use for validation
   --quiet, -q
       Print no logging messages
   --verbose, -v

docs/sections/user_guide/cli/drivers/chgres_cube/schema-options.rst

@@ -0,0 +1 @@
+../shared/schema-options.rst

docs/sections/user_guide/cli/drivers/esg_grid/help.rst

@@ -0,0 +1 @@
+../shared/help.rst

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

@@ -1,23 +1,11 @@
 ``esg_grid``
 ============
 
-.. include:: /shared/idempotent.rst
+.. include:: ../shared/idempotent.rst
 
 The ``uw`` mode for configuring and running the :ufs-utils:`regional_esg_grid<regional-esg-grid>` component.
 
-.. literalinclude:: esg_grid/help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: esg_grid/help.out
-   :language: text
-
-All tasks take the same arguments. For example:
-
-.. literalinclude:: esg_grid/run-help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: esg_grid/run-help.out
-   :language: text
+.. include:: help.rst
 
 Examples
 ^^^^^^^^
@@ -59,10 +47,4 @@ The driver creates a ``runscript.esg_grid`` file in the directory specified by `
 
      $ uw esg_grid provisioned_rundir --config-file config.yaml --batch
 
-* Specifying the ``--show-schema`` flag, with no other options, prints the driver's schema:
-
-.. literalinclude:: esg_grid/show-schema.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: esg_grid/show-schema.out
-   :language: text
+.. include:: schema-options.rst

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

@@ -1,6 +1,7 @@
 usage: uw esg_grid run [-h] [--version] [--config-file PATH] [--batch]
                        [--dry-run] [--graph-file PATH]
-                       [--key-path KEY[.KEY...]] [--quiet] [--verbose]
+                       [--key-path KEY[.KEY...]] [--schema-file PATH]
+                       [--quiet] [--verbose]
 
 A run
 
@@ -20,6 +21,8 @@ Optional arguments:
   --key-path KEY[.KEY...]
       Dot-separated path of keys leading through the config to the driver's
       configuration block
+  --schema-file PATH
+      Path to schema file to use for validation
   --quiet, -q
       Print no logging messages
   --verbose, -v

docs/sections/user_guide/cli/drivers/esg_grid/schema-options.rst

@@ -0,0 +1 @@
+../shared/schema-options.rst

docs/sections/user_guide/cli/drivers/filter_topo/help.rst

@@ -0,0 +1 @@
+../shared/help.rst

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

@@ -1,23 +1,11 @@
 ``filter_topo``
 ===============
 
-.. include:: /shared/idempotent.rst
+.. include:: ../shared/idempotent.rst
 
 The ``uw`` mode for configuring and running the UFS Utils preprocessing component ``filter_topo``. Documentation for this UFS Utils component is :ufs-utils:`here <filter-topo>`.
 
-.. literalinclude:: filter_topo/help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: filter_topo/help.out
-   :language: text
-
-All tasks take the same arguments. For example:
-
-.. literalinclude:: filter_topo/run-help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: filter_topo/run-help.out
-   :language: text
+.. include:: help.rst
 
 Examples
 ^^^^^^^^
@@ -53,10 +41,4 @@ Its contents are described in section :ref:`filter_topo_yaml`.
 
 .. include:: /shared/key_path.rst
 
-* Specifying the ``--show-schema`` flag, with no other options, prints the driver's schema:
-
-.. literalinclude:: filter_topo/show-schema.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: filter_topo/show-schema.out
-   :language: text
+.. include:: schema-options.rst

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

@@ -1,6 +1,7 @@
 usage: uw filter_topo run [-h] [--version] [--config-file PATH] [--batch]
                           [--dry-run] [--graph-file PATH]
-                          [--key-path KEY[.KEY...]] [--quiet] [--verbose]
+                          [--key-path KEY[.KEY...]] [--schema-file PATH]
+                          [--quiet] [--verbose]
 
 A run
 
@@ -20,6 +21,8 @@ Optional arguments:
   --key-path KEY[.KEY...]
       Dot-separated path of keys leading through the config to the driver's
       configuration block
+  --schema-file PATH
+      Path to schema file to use for validation
   --quiet, -q
       Print no logging messages
   --verbose, -v

docs/sections/user_guide/cli/drivers/filter_topo/schema-options.rst

@@ -0,0 +1 @@
+../shared/schema-options.rst

docs/sections/user_guide/cli/drivers/fv3/help.rst

@@ -0,0 +1 @@
+../shared/help.rst

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

@@ -1,23 +1,11 @@
 ``fv3``
 =======
 
-.. include:: /shared/idempotent.rst
+.. include:: ../shared/idempotent.rst
 
 The ``uw`` mode for configuring and running FV3.
 
-.. literalinclude:: fv3/help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: fv3/help.out
-   :language: text
-
-All tasks take the same arguments. For example:
-
-.. literalinclude:: fv3/run-help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: fv3/run-help.out
-   :language: text
+.. include:: help.rst
 
 Examples
 ^^^^^^^^
@@ -54,10 +42,4 @@ The examples use a configuration file named ``config.yaml``. Its contents are de
 
      $ uw fv3 provisioned_rundir --config-file config.yaml --cycle 2024-02-11T12 --batch
 
-* Specifying the ``--show-schema`` flag, with no other options, prints the driver's schema:
-
-.. literalinclude:: fv3/show-schema.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: fv3/show-schema.out
-   :language: text
+.. include:: schema-options.rst

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

@@ -1,6 +1,7 @@
 usage: uw fv3 run --cycle CYCLE [-h] [--version] [--config-file PATH]
                   [--batch] [--dry-run] [--graph-file PATH]
-                  [--key-path KEY[.KEY...]] [--quiet] [--verbose]
+                  [--key-path KEY[.KEY...]] [--schema-file PATH] [--quiet]
+                  [--verbose]
 
 A run
 
@@ -24,6 +25,8 @@ Optional arguments:
   --key-path KEY[.KEY...]
       Dot-separated path of keys leading through the config to the driver's
       configuration block
+  --schema-file PATH
+      Path to schema file to use for validation
   --quiet, -q
       Print no logging messages
   --verbose, -v

docs/sections/user_guide/cli/drivers/fv3/schema-options.rst

@@ -0,0 +1 @@
+../shared/schema-options.rst

docs/sections/user_guide/cli/drivers/global_equiv_resol/help.rst

@@ -0,0 +1 @@
+../shared/help.rst

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

@@ -1,23 +1,11 @@
 ``global_equiv_resol``
 ======================
 
-.. include:: /shared/idempotent.rst
+.. include:: ../shared/idempotent.rst
 
 The ``uw`` mode for configuring and running the UFS Utils preprocessing component ``global_equiv_resol``. Documentation for this UFS Utils component is :ufs-utils:`here <global-equiv-resol>`.
 
-.. literalinclude:: global_equiv_resol/help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: global_equiv_resol/help.out
-   :language: text
-
-All tasks take the same arguments. For example:
-
-.. literalinclude:: global_equiv_resol/run-help.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: global_equiv_resol/run-help.out
-   :language: text
+.. include:: help.rst
 
 Examples
 ^^^^^^^^
@@ -53,10 +41,4 @@ Its contents are described in section :ref:`global_equiv_resol_yaml`.
 
 .. include:: /shared/key_path.rst
 
-* Specifying the ``--show-schema`` flag, with no other options, prints the driver's schema:
-
-.. literalinclude:: global_equiv_resol/show-schema.cmd
-   :language: text
-   :emphasize-lines: 1
-.. literalinclude:: global_equiv_resol/show-schema.out
-   :language: text
+.. include:: schema-options.rst

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

@@ -1,7 +1,7 @@
 usage: uw global_equiv_resol run [-h] [--version] [--config-file PATH]
                                  [--batch] [--dry-run] [--graph-file PATH]
-                                 [--key-path KEY[.KEY...]] [--quiet]
-                                 [--verbose]
+                                 [--key-path KEY[.KEY...]]
+                                 [--schema-file PATH] [--quiet] [--verbose]
 
 A run
 
@@ -21,6 +21,8 @@ Optional arguments:
   --key-path KEY[.KEY...]
       Dot-separated path of keys leading through the config to the driver's
       configuration block
+  --schema-file PATH
+      Path to schema file to use for validation
   --quiet, -q
       Print no logging messages
   --verbose, -v

docs/sections/user_guide/cli/drivers/global_equiv_resol/schema-options.rst

@@ -0,0 +1 @@
+../shared/schema-options.rst