UW-491 Automate injection of CLI commands/inputs/outputs into RST docs (

ufs-community#495)
maddenp-noaa · May 23, 2024 · d8588e8 · d8588e8
1 parent 5cce6b4
commit d8588e8
Show file tree

Hide file tree

Showing 264 changed files with 2,222 additions and 1,976 deletions.
diff --git a/Makefile b/Makefile
@@ -21,6 +21,7 @@ devshell:
 	condev-shell || true
 
 docs:
+	$(MAKE) -C docs examples
 	$(MAKE) -C docs docs
 
 env: package

diff --git a/docs/Makefile b/docs/Makefile
@@ -4,7 +4,7 @@ SOURCEDIR    = .
 SPHINXBUILD  = sphinx-build
 SPHINXOPTS   = -a -n -W
 
-.PHONY: help clean docs linkcheck
+.PHONY: help clean docs examples linkcheck
 
 help:
 	$(SPHINXBUILD) -M help $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS)
@@ -16,6 +16,9 @@ docs:
 	$(MAKE) linkcheck
 	$(MAKE) html
 
+examples:
+	$(MAKE) -C sections
+
 linkcheck:
 	$(SPHINXBUILD) -b linkcheck $(SPHINXOPTS) -c $(CURDIR) $(CURDIR) build/linkcheck
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -52,6 +52,7 @@
     "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"),
+    "shell-redirection": ("https://www.gnu.org/software/bash/manual/html_node/Redirections.html%s", "%s"),
     "ufs": ("https://ufs.epic.noaa.gov/%s", "%s"),
     "ufs-utils": ("https://noaa-emcufs-utils.readthedocs.io/en/latest/ufs_utils.html#%s", "%s"),
     "ufs-weather-model": ("https://github.com/ufs-community/ufs-weather-model/%s", "%s"),

diff --git a/docs/environment.yml b/docs/environment.yml
@@ -4,3 +4,4 @@ channels:
 dependencies:
   - sphinx_rtd_theme=1.3.0
   - sphinxcontrib-bibtex=2.6.1
+  - tree
diff --git a/docs/index.rst b/docs/index.rst
@@ -40,7 +40,7 @@ When the Linux diff tool just doesn't work for comparing unordered namelists wit
 Realize Mode
 """"""""""""
 
-This mode renders values created by :jinja2:`Jinja2 templates<templates>`, and lets you override values in one file or object with those from others, not necessarily with the same configuration format. With ``uwtools``, you can even reference the content of other files to build up a configuration from its pieces.
+This mode renders values created by :jinja2:`Jinja2 templates<templates>`, and lets you override values in one file or object with those from others, not necessarily with the same configuration format. With ``uwtools``, you can even reference the contents of other files to build up a configuration from its pieces.
 
 | :any:`CLI documentation with examples<cli_config_realize_examples>`
 

diff --git a/docs/sections/Makefile b/docs/sections/Makefile
@@ -0,0 +1,8 @@
+SUBDIRS = user_guide
+
+.PHONY: all $(SUBDIRS)
+
+all: $(SUBDIRS)
+
+$(SUBDIRS):
+	$(MAKE) -C $@
diff --git a/docs/sections/contributor_guide/documentation.rst b/docs/sections/contributor_guide/documentation.rst
@@ -7,8 +7,7 @@ Locally Building and Previewing Documentation
 To locally build the docs:
 
 #. Obtain a development shell as described in the :doc:`Developer Setup <developer_setup>` section.
-#. From the root of your clone: ``cd docs``
-#. Install the required doc packages: ``source install-deps``
+#. From the clone root, install the required doc packages: ``source docs/install-deps``
 #. Build the docs: ``make docs``
 
 The ``make docs`` command will build the docs under ``docs/build/html``, after which you can preview them in your web browser at the URL
@@ -17,7 +16,7 @@ The ``make docs`` command will build the docs under ``docs/build/html``, after w
 
    file://<filesystem-path-to-your-clone>/docs/build/html/index.html
 
-Rerun ``make docs`` and refresh your browser after making and saving changes.
+Re-run ``make docs`` and refresh your browser after making and saving changes. Note that some documentation content is dynamically generated: Timestamps shown in e.g. log messages are expected and are ok to commit.
 
 If, at some point, you remove and recreate the conda development environment underlying your development shell, you will need to rerun the ``source install-deps`` command in the new environment/shell. Until then, the installed doc packages will persist and support docs generation.
 

diff --git a/docs/sections/user_guide/Makefile b/docs/sections/user_guide/Makefile
@@ -0,0 +1,8 @@
+SUBDIRS = cli
+
+.PHONY: all $(SUBDIRS)
+
+all: $(SUBDIRS)
+
+$(SUBDIRS):
+	$(MAKE) -C $@
diff --git a/docs/sections/user_guide/cli/Makefile b/docs/sections/user_guide/cli/Makefile
@@ -0,0 +1,8 @@
+SUBDIRS = $(shell find . -maxdepth 1 -mindepth 1 -type d)
+
+.PHONY: all $(SUBDIRS)
+
+all: $(SUBDIRS)
+
+$(SUBDIRS):
+	$(MAKE) -C $@ -j
diff --git a/docs/sections/user_guide/cli/Makefile.outputs b/docs/sections/user_guide/cli/Makefile.outputs
@@ -0,0 +1,9 @@
+COMMANDS = $(wildcard *.cmd)
+OUTPUTS  = $(COMMANDS:cmd=out)
+
+.PHONY: all $(OUTPUTS)
+
+all: $(OUTPUTS)
+
+$(OUTPUTS):
+	bash $(basename $@).cmd >$@ 2>&1 | true
diff --git a/docs/sections/user_guide/cli/drivers/Makefile b/docs/sections/user_guide/cli/drivers/Makefile
@@ -0,0 +1 @@
+../Makefile
diff --git a/docs/sections/user_guide/cli/drivers/chgres_cube.rst b/docs/sections/user_guide/cli/drivers/chgres_cube.rst
@@ -3,63 +3,19 @@
 
 The ``uw`` mode for configuring and running the :ufs-utils:`chgres_cube<chgres-cube>` component.
 
-.. code-block:: text
-
-   $ uw chgres_cube --help
-   usage: uw chgres_cube [-h] [--version] TASK ...
-
-   Execute chgres_cube tasks
-
-   Optional arguments:
-     -h, --help
-         Show help and exit
-     --version
-         Show version info and exit
-
-   Positional arguments:
-     TASK
-       namelist_file
-         The namelist file
-       provisioned_run_directory
-         Run directory provisioned with all required content
-       run
-         A run
-       runscript
-         The runscript
-       validate
-         Validate the UW driver config
+.. 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:
 
-.. code-block:: text
-
-   $ uw chgres_cube run --help
-   usage: uw chgres_cube 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 (e.g. 2024-05-08T18)
-
-   Optional arguments:
-     -h, --help
-         Show help and exit
-     --version
-         Show version info and exit
-     --config-file PATH, -c PATH
-         Path to UW YAML 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
+.. literalinclude:: chgres_cube/run-help.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: chgres_cube/run-help.out
+   :language: text
 
 Examples
 ^^^^^^^^
@@ -101,4 +57,3 @@ Its contents are described in depth in section :ref:`chgres_cube_yaml`. Each of
   .. code-block:: text
 
      $ uw chgres_cube provisioned_run_directory --config-file config.yaml --cycle 2023-12-15T18 --batch
-
diff --git a/docs/sections/user_guide/cli/drivers/chgres_cube/Makefile b/docs/sections/user_guide/cli/drivers/chgres_cube/Makefile
@@ -0,0 +1 @@
+../../Makefile.outputs
diff --git a/docs/sections/user_guide/cli/drivers/chgres_cube/help.cmd b/docs/sections/user_guide/cli/drivers/chgres_cube/help.cmd
@@ -0,0 +1 @@
+uw chgres_cube --help
diff --git a/docs/sections/user_guide/cli/drivers/chgres_cube/help.out b/docs/sections/user_guide/cli/drivers/chgres_cube/help.out
@@ -0,0 +1,22 @@
+usage: uw chgres_cube [-h] [--version] TASK ...
+
+Execute chgres_cube tasks
+
+Optional arguments:
+  -h, --help
+      Show help and exit
+  --version
+      Show version info and exit
+
+Positional arguments:
+  TASK
+    namelist_file
+      The namelist file
+    provisioned_run_directory
+      Run directory provisioned with all required content
+    run
+      A run
+    runscript
+      The runscript
+    validate
+      Validate the UW driver config
diff --git a/docs/sections/user_guide/cli/drivers/chgres_cube/run-help.cmd b/docs/sections/user_guide/cli/drivers/chgres_cube/run-help.cmd
@@ -0,0 +1 @@
+uw chgres_cube run --help
diff --git a/docs/sections/user_guide/cli/drivers/chgres_cube/run-help.out b/docs/sections/user_guide/cli/drivers/chgres_cube/run-help.out
@@ -0,0 +1,30 @@
+usage: uw chgres_cube run --cycle CYCLE [-h] [--version] [--config-file PATH]
+                          [--batch] [--dry-run] [--graph-file PATH]
+                          [--key-path KEY[.KEY...]] [--quiet] [--verbose]
+
+A run
+
+Required arguments:
+  --cycle CYCLE
+      The cycle in ISO8601 format (e.g. 2024-05-23T18)
+
+Optional arguments:
+  -h, --help
+      Show help and exit
+  --version
+      Show version info and exit
+  --config-file PATH, -c PATH
+      Path to UW YAML 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]
+  --key-path KEY[.KEY...]
+      Dot-separated path of keys leading through the config to the driver's
+      configuration block
+  --quiet, -q
+      Print no logging messages
+  --verbose, -v
+      Print all logging messages
diff --git a/docs/sections/user_guide/cli/drivers/esg_grid.rst b/docs/sections/user_guide/cli/drivers/esg_grid.rst
@@ -3,64 +3,24 @@
 
 The ``uw`` mode for configuring and running the :ufs-utils:`regional_esg_grid<regional-esg-grid>` component.
 
-.. code-block:: text
-
-   $ uw esg_grid --help
-   usage: uw esg_grid [-h] [--version] TASK ...
-
-   Execute esg_grid tasks
-
-   Optional arguments:
-     -h, --help
-         Show help and exit
-     --version
-         Show version info and exit
-
-   Positional arguments:
-     TASK
-       namelist_file
-         The namelist file
-       provisioned_run_directory
-         Run directory provisioned with all required content
-       run
-         A run
-       runscript
-         The runscript
-       validate
-         Validate the UW driver config
+.. 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:
 
-.. code-block:: text
-
-   $ uw esg_grid run --help
-   usage: uw esg_grid run [-h] [--version] [--config-file PATH] [--batch] [--dry-run]
-                          [--graph-file PATH] [--quiet] [--verbose]
-
-   A run
-
-   Optional arguments:
-     -h, --help
-         Show help and exit
-     --version
-         Show version info and exit
-     --config-file PATH, -c PATH
-         Path to UW YAML 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
+.. literalinclude:: esg_grid/run-help.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: esg_grid/run-help.out
+   :language: text
 
 Examples
 ^^^^^^^^
 
-The examples use a configuration file named ``config.yaml`` with content similar to:
+The examples use a configuration file named ``config.yaml`` with contents similar to:
 
 .. highlight:: yaml
 .. literalinclude:: ../../../../shared/esg_grid.yaml

diff --git a/docs/sections/user_guide/cli/drivers/esg_grid/Makefile b/docs/sections/user_guide/cli/drivers/esg_grid/Makefile
@@ -0,0 +1 @@
+../../Makefile.outputs
diff --git a/docs/sections/user_guide/cli/drivers/esg_grid/help.cmd b/docs/sections/user_guide/cli/drivers/esg_grid/help.cmd
@@ -0,0 +1 @@
+uw esg_grid --help
diff --git a/docs/sections/user_guide/cli/drivers/esg_grid/help.out b/docs/sections/user_guide/cli/drivers/esg_grid/help.out
@@ -0,0 +1,22 @@
+usage: uw esg_grid [-h] [--version] TASK ...
+
+Execute esg_grid tasks
+
+Optional arguments:
+  -h, --help
+      Show help and exit
+  --version
+      Show version info and exit
+
+Positional arguments:
+  TASK
+    namelist_file
+      The namelist file
+    provisioned_run_directory
+      Run directory provisioned with all required content
+    run
+      A run
+    runscript
+      The runscript
+    validate
+      Validate the UW driver config
diff --git a/docs/sections/user_guide/cli/drivers/esg_grid/run-help.cmd b/docs/sections/user_guide/cli/drivers/esg_grid/run-help.cmd
@@ -0,0 +1 @@
+uw esg_grid run --help
diff --git a/docs/sections/user_guide/cli/drivers/esg_grid/run-help.out b/docs/sections/user_guide/cli/drivers/esg_grid/run-help.out
@@ -0,0 +1,26 @@
+usage: uw esg_grid run [-h] [--version] [--config-file PATH] [--batch]
+                       [--dry-run] [--graph-file PATH]
+                       [--key-path KEY[.KEY...]] [--quiet] [--verbose]
+
+A run
+
+Optional arguments:
+  -h, --help
+      Show help and exit
+  --version
+      Show version info and exit
+  --config-file PATH, -c PATH
+      Path to UW YAML 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]
+  --key-path KEY[.KEY...]
+      Dot-separated path of keys leading through the config to the driver's
+      configuration block
+  --quiet, -q
+      Print no logging messages
+  --verbose, -v
+      Print all logging messages