From d8588e85f554808c4a1ddf295cfc71eae30aa23f Mon Sep 17 00:00:00 2001 From: Paul Madden <136389411+maddenp-noaa@users.noreply.github.com> Date: Thu, 23 May 2024 13:59:50 -0600 Subject: [PATCH] UW-491 Automate injection of CLI commands/inputs/outputs into RST docs (#495) --- Makefile | 1 + docs/Makefile | 5 +- docs/conf.py | 1 + docs/environment.yml | 1 + docs/index.rst | 2 +- docs/sections/Makefile | 8 + .../contributor_guide/documentation.rst | 5 +- docs/sections/user_guide/Makefile | 8 + docs/sections/user_guide/cli/Makefile | 8 + docs/sections/user_guide/cli/Makefile.outputs | 9 + docs/sections/user_guide/cli/drivers/Makefile | 1 + .../user_guide/cli/drivers/chgres_cube.rst | 65 +- .../cli/drivers/chgres_cube/Makefile | 1 + .../cli/drivers/chgres_cube/help.cmd | 1 + .../cli/drivers/chgres_cube/help.out | 22 + .../cli/drivers/chgres_cube/run-help.cmd | 1 + .../cli/drivers/chgres_cube/run-help.out | 30 + .../user_guide/cli/drivers/esg_grid.rst | 62 +- .../user_guide/cli/drivers/esg_grid/Makefile | 1 + .../user_guide/cli/drivers/esg_grid/help.cmd | 1 + .../user_guide/cli/drivers/esg_grid/help.out | 22 + .../cli/drivers/esg_grid/run-help.cmd | 1 + .../cli/drivers/esg_grid/run-help.out | 26 + docs/sections/user_guide/cli/drivers/fv3.rst | 78 +- .../user_guide/cli/drivers/fv3/Makefile | 1 + .../user_guide/cli/drivers/fv3/help.cmd | 1 + .../user_guide/cli/drivers/fv3/help.out | 36 + .../user_guide/cli/drivers/fv3/run-help.cmd | 1 + .../user_guide/cli/drivers/fv3/run-help.out | 30 + .../cli/drivers/global_equiv_resol.rst | 62 +- .../cli/drivers/global_equiv_resol/Makefile | 1 + .../cli/drivers/global_equiv_resol/help.cmd | 1 + .../cli/drivers/global_equiv_resol/help.out | 22 + .../drivers/global_equiv_resol/run-help.cmd | 1 + .../drivers/global_equiv_resol/run-help.out | 27 + docs/sections/user_guide/cli/drivers/jedi.rst | 72 +- .../user_guide/cli/drivers/jedi/Makefile | 1 + .../user_guide/cli/drivers/jedi/help.cmd | 1 + .../user_guide/cli/drivers/jedi/help.out | 28 + .../user_guide/cli/drivers/jedi/run-help.cmd | 1 + .../user_guide/cli/drivers/jedi/run-help.out | 30 + .../user_guide/cli/drivers/make_hgrid.rst | 59 +- .../cli/drivers/make_hgrid/Makefile | 1 + .../cli/drivers/make_hgrid/help.cmd | 1 + .../cli/drivers/make_hgrid/help.out | 20 + .../cli/drivers/make_hgrid/run-help.cmd | 1 + .../cli/drivers/make_hgrid/run-help.out | 26 + .../cli/drivers/make_solo_mosaic.rst | 60 +- .../cli/drivers/make_solo_mosaic/Makefile | 1 + .../cli/drivers/make_solo_mosaic/help.cmd | 1 + .../cli/drivers/make_solo_mosaic/help.out | 20 + .../cli/drivers/make_solo_mosaic/run-help.cmd | 1 + .../cli/drivers/make_solo_mosaic/run-help.out | 26 + docs/sections/user_guide/cli/drivers/mpas.rst | 74 +- .../user_guide/cli/drivers/mpas/Makefile | 1 + .../user_guide/cli/drivers/mpas/help.cmd | 1 + .../user_guide/cli/drivers/mpas/help.out | 30 + .../user_guide/cli/drivers/mpas/run-help.cmd | 1 + .../user_guide/cli/drivers/mpas/run-help.out | 30 + .../user_guide/cli/drivers/mpas_init.rst | 74 +- .../user_guide/cli/drivers/mpas_init/Makefile | 1 + .../user_guide/cli/drivers/mpas_init/help.cmd | 1 + .../user_guide/cli/drivers/mpas_init/help.out | 30 + .../cli/drivers/mpas_init/run-help.cmd | 1 + .../cli/drivers/mpas_init/run-help.out | 30 + .../user_guide/cli/drivers/sfc_climo_gen.rst | 62 +- .../cli/drivers/sfc_climo_gen/Makefile | 1 + .../cli/drivers/sfc_climo_gen/help.cmd | 1 + .../cli/drivers/sfc_climo_gen/help.out | 22 + .../cli/drivers/sfc_climo_gen/run-help.cmd | 1 + .../cli/drivers/sfc_climo_gen/run-help.out | 26 + .../sections/user_guide/cli/drivers/shave.rst | 60 +- .../user_guide/cli/drivers/shave/Makefile | 1 + .../user_guide/cli/drivers/shave/help.cmd | 1 + .../user_guide/cli/drivers/shave/help.out | 20 + .../user_guide/cli/drivers/shave/run-help.cmd | 1 + .../user_guide/cli/drivers/shave/run-help.out | 26 + .../user_guide/cli/drivers/ungrib.rst | 70 +- .../user_guide/cli/drivers/ungrib/Makefile | 1 + .../user_guide/cli/drivers/ungrib/help.cmd | 1 + .../user_guide/cli/drivers/ungrib/help.out | 26 + .../cli/drivers/ungrib/run-help.cmd | 1 + .../cli/drivers/ungrib/run-help.out | 30 + docs/sections/user_guide/cli/drivers/upp.rst | 72 +- .../user_guide/cli/drivers/upp/Makefile | 1 + .../user_guide/cli/drivers/upp/help.cmd | 1 + .../user_guide/cli/drivers/upp/help.out | 26 + .../user_guide/cli/drivers/upp/run-help.cmd | 1 + .../user_guide/cli/drivers/upp/run-help.out | 33 + docs/sections/user_guide/cli/tools/Makefile | 1 + docs/sections/user_guide/cli/tools/config.rst | 700 +++++------------- .../user_guide/cli/tools/config/.gitignore | 1 + .../user_guide/cli/tools/config/Makefile | 1 + .../user_guide/cli/tools/config/a.nml | 4 + .../user_guide/cli/tools/config/a.txt | 1 + .../user_guide/cli/tools/config/b.nml | 1 + .../user_guide/cli/tools/config/c.nml | 3 + .../config/compare-bad-extension-fix.cmd | 1 + .../config/compare-bad-extension-fix.out | 4 + .../tools/config/compare-bad-extension.cmd | 1 + .../tools/config/compare-bad-extension.out | 1 + .../cli/tools/config/compare-diff.cmd | 1 + .../cli/tools/config/compare-diff.out | 4 + .../tools/config/compare-format-mismatch.cmd | 1 + .../tools/config/compare-format-mismatch.out | 1 + .../cli/tools/config/compare-help.cmd | 1 + .../cli/tools/config/compare-help.out | 26 + .../cli/tools/config/compare-match.cmd | 1 + .../cli/tools/config/compare-match.out | 3 + .../cli/tools/config/compare-verbose.cmd | 1 + .../cli/tools/config/compare-verbose.out | 5 + .../user_guide/cli/tools/config/config.txt | 1 + .../user_guide/cli/tools/config/config.yaml | 7 + .../user_guide/cli/tools/config/flowers.yaml | 3 + .../user_guide/cli/tools/config/help.cmd | 1 + .../user_guide/cli/tools/config/help.out | 18 + .../cli/tools/config/realize-combo.cmd | 1 + .../cli/tools/config/realize-combo.out | 6 + .../tools/config/realize-depth-mismatch.cmd | 1 + .../tools/config/realize-depth-mismatch.out | 1 + .../cli/tools/config/realize-dry-run.cmd | 1 + .../cli/tools/config/realize-dry-run.out | 7 + .../config/realize-extension-file-bad.cmd | 1 + .../config/realize-extension-file-bad.out | 1 + .../config/realize-extension-file-fix.cmd | 1 + .../config/realize-extension-file-fix.out | 7 + .../config/realize-extension-stdin-bad.cmd | 1 + .../config/realize-extension-stdin-bad.out | 1 + .../config/realize-extension-stdin-fix.cmd | 1 + .../config/realize-extension-stdin-fix.out | 7 + .../cli/tools/config/realize-flowers-noop.cmd | 2 + .../cli/tools/config/realize-flowers-noop.out | 5 + .../tools/config/realize-flowers-total.cmd | 2 + .../tools/config/realize-flowers-total.out | 3 + .../cli/tools/config/realize-help.cmd | 1 + .../cli/tools/config/realize-help.out | 40 + .../cli/tools/config/realize-roses-noop.cmd | 1 + .../cli/tools/config/realize-roses-noop.out | 2 + .../cli/tools/config/realize-stdout.cmd | 1 + .../cli/tools/config/realize-stdout.out | 7 + .../config/realize-update-file-outfile.cmd | 3 + .../config/realize-update-file-outfile.out | 7 + .../cli/tools/config/realize-update-file.cmd | 1 + .../cli/tools/config/realize-update-file.out | 7 + .../cli/tools/config/realize-update-stdin.cmd | 1 + .../cli/tools/config/realize-update-stdin.out | 8 + .../tools/config/realize-values-needed.cmd | 1 + .../tools/config/realize-values-needed.out | 12 + .../cli/tools/config/realize-verbose.cmd | 1 + .../cli/tools/config/realize-verbose.out | 30 + .../user_guide/cli/tools/config/roses.yaml | 2 + .../cli/tools/config/schema.jsonschema | 21 + .../user_guide/cli/tools/config/update.yaml | 5 + .../cli/tools/config/validate-fail.cmd | 1 + .../cli/tools/config/validate-fail.out | 3 + .../cli/tools/config/validate-help.cmd | 1 + .../cli/tools/config/validate-help.out | 20 + .../cli/tools/config/validate-pass-stdin.cmd | 1 + .../cli/tools/config/validate-pass-stdin.out | 1 + .../cli/tools/config/validate-pass.cmd | 1 + .../cli/tools/config/validate-pass.out | 1 + .../cli/tools/config/validate-verbose.cmd | 1 + .../cli/tools/config/validate-verbose.out | 20 + .../cli/tools/config/values-bad.yaml | 2 + .../user_guide/cli/tools/config/values.yaml | 3 + docs/sections/user_guide/cli/tools/file.rst | 175 +---- .../user_guide/cli/tools/file/.gitignore | 2 + .../user_guide/cli/tools/file/Makefile | 1 + .../cli/tools/file/copy-config.yaml | 4 + .../user_guide/cli/tools/file/copy-exec.cmd | 4 + .../user_guide/cli/tools/file/copy-exec.out | 22 + .../user_guide/cli/tools/file/copy-help.cmd | 1 + .../user_guide/cli/tools/file/copy-help.out | 25 + .../user_guide/cli/tools/file/help.cmd | 1 + .../user_guide/cli/tools/file/help.out | 16 + .../cli/tools/file/link-config.yaml | 4 + .../user_guide/cli/tools/file/link-exec.cmd | 4 + .../user_guide/cli/tools/file/link-exec.out | 22 + .../user_guide/cli/tools/file/link-help.cmd | 1 + .../user_guide/cli/tools/file/link-help.out | 25 + .../user_guide/cli/tools/file/src/bar | 1 + .../user_guide/cli/tools/file/src/foo | 1 + docs/sections/user_guide/cli/tools/rocoto.rst | 393 ++-------- .../user_guide/cli/tools/rocoto/.gitignore | 2 + .../user_guide/cli/tools/rocoto/Makefile | 1 + .../user_guide/cli/tools/rocoto/help.cmd | 1 + .../user_guide/cli/tools/rocoto/help.out | 16 + .../cli/tools/rocoto/realize-exec-file.cmd | 4 + .../cli/tools/rocoto/realize-exec-file.out | 23 + .../rocoto/realize-exec-stdin-stdout.cmd | 1 + .../rocoto/realize-exec-stdin-stdout.out | 22 + .../rocoto/realize-exec-stdout-verbose.cmd | 5 + .../rocoto/realize-exec-stdout-verbose.out | 21 + .../cli/tools/rocoto/realize-exec-stdout.cmd | 1 + .../cli/tools/rocoto/realize-exec-stdout.out | 22 + .../cli/tools/rocoto/realize-help.cmd | 1 + .../cli/tools/rocoto/realize-help.out | 18 + .../cli/tools/rocoto/rocoto-bad.xml | 19 + .../cli/tools/rocoto/rocoto-good.xml | 20 + .../user_guide/cli/tools/rocoto/rocoto.yaml | 23 + .../cli/tools/rocoto/validate-bad-file.cmd | 1 + .../cli/tools/rocoto/validate-bad-file.out | 24 + .../cli/tools/rocoto/validate-good-file.cmd | 1 + .../cli/tools/rocoto/validate-good-file.out | 1 + .../cli/tools/rocoto/validate-good-stdin.cmd | 1 + .../cli/tools/rocoto/validate-good-stdin.out | 1 + .../cli/tools/rocoto/validate-help.cmd | 1 + .../cli/tools/rocoto/validate-help.out | 16 + .../user_guide/cli/tools/template.rst | 387 ++++------ .../user_guide/cli/tools/template/.gitignore | 2 + .../user_guide/cli/tools/template/Makefile | 1 + .../user_guide/cli/tools/template/atparse.txt | 1 + .../cli/tools/template/greeting.yaml | 1 + .../user_guide/cli/tools/template/help.cmd | 1 + .../user_guide/cli/tools/template/help.out | 16 + .../user_guide/cli/tools/template/macros | 3 + .../cli/tools/template/macros-dir/macros | 1 + .../template/render-exec-bad-extension.cmd | 1 + .../template/render-exec-bad-extension.out | 1 + .../tools/template/render-exec-cli-value.cmd | 1 + .../tools/template/render-exec-cli-value.out | 1 + .../template/render-exec-combo-value.cmd | 1 + .../template/render-exec-combo-value.out | 1 + .../tools/template/render-exec-dry-run.cmd | 1 + .../tools/template/render-exec-dry-run.out | 1 + .../tools/template/render-exec-env-value.cmd | 1 + .../tools/template/render-exec-env-value.out | 1 + .../render-exec-explicit-extension.cmd | 1 + .../render-exec-explicit-extension.out | 1 + .../cli/tools/template/render-exec-file.cmd | 3 + .../cli/tools/template/render-exec-file.out | 1 + .../tools/template/render-exec-macros-dir.cmd | 1 + .../tools/template/render-exec-macros-dir.out | 1 + .../cli/tools/template/render-exec-macros.cmd | 1 + .../cli/tools/template/render-exec-macros.out | 1 + .../template/render-exec-missing-value.cmd | 1 + .../template/render-exec-missing-value.out | 3 + .../tools/template/render-exec-read-stdin.cmd | 1 + .../tools/template/render-exec-read-stdin.out | 1 + .../cli/tools/template/render-exec-sh.cmd | 1 + .../cli/tools/template/render-exec-sh.out | 1 + .../cli/tools/template/render-exec-stdout.cmd | 1 + .../cli/tools/template/render-exec-stdout.out | 1 + .../template/render-exec-values-needed.cmd | 1 + .../template/render-exec-values-needed.out | 3 + .../tools/template/render-exec-verbose.cmd | 1 + .../tools/template/render-exec-verbose.out | 15 + .../cli/tools/template/render-help.cmd | 1 + .../cli/tools/template/render-help.out | 36 + .../user_guide/cli/tools/template/template | 1 + .../cli/tools/template/template-with-macros | 2 + .../tools/template/translate-exec-dry-run.cmd | 1 + .../tools/template/translate-exec-dry-run.out | 1 + .../tools/template/translate-exec-file.cmd | 3 + .../tools/template/translate-exec-file.out | 1 + .../tools/template/translate-exec-stdout.cmd | 1 + .../tools/template/translate-exec-stdout.out | 1 + .../cli/tools/template/translate-help.cmd | 1 + .../cli/tools/template/translate-help.out | 21 + .../user_guide/cli/tools/template/values.sh | 2 + .../user_guide/cli/tools/template/values.txt | 1 + .../user_guide/cli/tools/template/values.yaml | 2 + src/uwtools/cli.py | 7 +- src/uwtools/utils/tasks.py | 5 +- 264 files changed, 2222 insertions(+), 1976 deletions(-) create mode 100644 docs/sections/Makefile create mode 100644 docs/sections/user_guide/Makefile create mode 100644 docs/sections/user_guide/cli/Makefile create mode 100644 docs/sections/user_guide/cli/Makefile.outputs create mode 120000 docs/sections/user_guide/cli/drivers/Makefile create mode 120000 docs/sections/user_guide/cli/drivers/chgres_cube/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/chgres_cube/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/chgres_cube/help.out create mode 100644 docs/sections/user_guide/cli/drivers/chgres_cube/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/chgres_cube/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/esg_grid/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/esg_grid/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/esg_grid/help.out create mode 100644 docs/sections/user_guide/cli/drivers/esg_grid/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/esg_grid/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/fv3/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/fv3/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/fv3/help.out create mode 100644 docs/sections/user_guide/cli/drivers/fv3/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/fv3/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/global_equiv_resol/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/global_equiv_resol/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/global_equiv_resol/help.out create mode 100644 docs/sections/user_guide/cli/drivers/global_equiv_resol/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/global_equiv_resol/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/jedi/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/jedi/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/jedi/help.out create mode 100644 docs/sections/user_guide/cli/drivers/jedi/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/jedi/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/make_hgrid/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/make_hgrid/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/make_hgrid/help.out create mode 100644 docs/sections/user_guide/cli/drivers/make_hgrid/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/make_hgrid/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/make_solo_mosaic/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/make_solo_mosaic/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/make_solo_mosaic/help.out create mode 100644 docs/sections/user_guide/cli/drivers/make_solo_mosaic/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/make_solo_mosaic/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/mpas/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/mpas/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/mpas/help.out create mode 100644 docs/sections/user_guide/cli/drivers/mpas/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/mpas/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/mpas_init/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/mpas_init/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/mpas_init/help.out create mode 100644 docs/sections/user_guide/cli/drivers/mpas_init/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/mpas_init/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/sfc_climo_gen/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/sfc_climo_gen/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/sfc_climo_gen/help.out create mode 100644 docs/sections/user_guide/cli/drivers/sfc_climo_gen/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/sfc_climo_gen/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/shave/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/shave/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/shave/help.out create mode 100644 docs/sections/user_guide/cli/drivers/shave/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/shave/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/ungrib/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/ungrib/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/ungrib/help.out create mode 100644 docs/sections/user_guide/cli/drivers/ungrib/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/ungrib/run-help.out create mode 120000 docs/sections/user_guide/cli/drivers/upp/Makefile create mode 100644 docs/sections/user_guide/cli/drivers/upp/help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/upp/help.out create mode 100644 docs/sections/user_guide/cli/drivers/upp/run-help.cmd create mode 100644 docs/sections/user_guide/cli/drivers/upp/run-help.out create mode 120000 docs/sections/user_guide/cli/tools/Makefile create mode 100644 docs/sections/user_guide/cli/tools/config/.gitignore create mode 120000 docs/sections/user_guide/cli/tools/config/Makefile create mode 100644 docs/sections/user_guide/cli/tools/config/a.nml create mode 120000 docs/sections/user_guide/cli/tools/config/a.txt create mode 120000 docs/sections/user_guide/cli/tools/config/b.nml create mode 100644 docs/sections/user_guide/cli/tools/config/c.nml create mode 100644 docs/sections/user_guide/cli/tools/config/compare-bad-extension-fix.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/compare-bad-extension-fix.out create mode 100644 docs/sections/user_guide/cli/tools/config/compare-bad-extension.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/compare-bad-extension.out create mode 100644 docs/sections/user_guide/cli/tools/config/compare-diff.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/compare-diff.out create mode 100644 docs/sections/user_guide/cli/tools/config/compare-format-mismatch.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/compare-format-mismatch.out create mode 100644 docs/sections/user_guide/cli/tools/config/compare-help.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/compare-help.out create mode 100644 docs/sections/user_guide/cli/tools/config/compare-match.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/compare-match.out create mode 100644 docs/sections/user_guide/cli/tools/config/compare-verbose.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/compare-verbose.out create mode 120000 docs/sections/user_guide/cli/tools/config/config.txt create mode 100644 docs/sections/user_guide/cli/tools/config/config.yaml create mode 100644 docs/sections/user_guide/cli/tools/config/flowers.yaml create mode 100644 docs/sections/user_guide/cli/tools/config/help.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/help.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-combo.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-combo.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-depth-mismatch.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-depth-mismatch.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-dry-run.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-dry-run.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-extension-file-bad.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-extension-file-bad.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-extension-file-fix.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-extension-file-fix.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-extension-stdin-bad.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-extension-stdin-bad.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-extension-stdin-fix.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-extension-stdin-fix.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-flowers-noop.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-flowers-noop.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-flowers-total.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-flowers-total.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-help.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-help.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-roses-noop.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-roses-noop.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-stdout.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-stdout.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-update-file-outfile.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-update-file-outfile.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-update-file.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-update-file.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-update-stdin.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-update-stdin.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-values-needed.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-values-needed.out create mode 100644 docs/sections/user_guide/cli/tools/config/realize-verbose.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/realize-verbose.out create mode 100644 docs/sections/user_guide/cli/tools/config/roses.yaml create mode 100644 docs/sections/user_guide/cli/tools/config/schema.jsonschema create mode 100644 docs/sections/user_guide/cli/tools/config/update.yaml create mode 100644 docs/sections/user_guide/cli/tools/config/validate-fail.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/validate-fail.out create mode 100644 docs/sections/user_guide/cli/tools/config/validate-help.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/validate-help.out create mode 100644 docs/sections/user_guide/cli/tools/config/validate-pass-stdin.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/validate-pass-stdin.out create mode 100644 docs/sections/user_guide/cli/tools/config/validate-pass.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/validate-pass.out create mode 100644 docs/sections/user_guide/cli/tools/config/validate-verbose.cmd create mode 100644 docs/sections/user_guide/cli/tools/config/validate-verbose.out create mode 100644 docs/sections/user_guide/cli/tools/config/values-bad.yaml create mode 100644 docs/sections/user_guide/cli/tools/config/values.yaml create mode 100644 docs/sections/user_guide/cli/tools/file/.gitignore create mode 120000 docs/sections/user_guide/cli/tools/file/Makefile create mode 100644 docs/sections/user_guide/cli/tools/file/copy-config.yaml create mode 100644 docs/sections/user_guide/cli/tools/file/copy-exec.cmd create mode 100644 docs/sections/user_guide/cli/tools/file/copy-exec.out create mode 100644 docs/sections/user_guide/cli/tools/file/copy-help.cmd create mode 100644 docs/sections/user_guide/cli/tools/file/copy-help.out create mode 100644 docs/sections/user_guide/cli/tools/file/help.cmd create mode 100644 docs/sections/user_guide/cli/tools/file/help.out create mode 100644 docs/sections/user_guide/cli/tools/file/link-config.yaml create mode 100644 docs/sections/user_guide/cli/tools/file/link-exec.cmd create mode 100644 docs/sections/user_guide/cli/tools/file/link-exec.out create mode 100644 docs/sections/user_guide/cli/tools/file/link-help.cmd create mode 100644 docs/sections/user_guide/cli/tools/file/link-help.out create mode 100644 docs/sections/user_guide/cli/tools/file/src/bar create mode 100644 docs/sections/user_guide/cli/tools/file/src/foo create mode 100644 docs/sections/user_guide/cli/tools/rocoto/.gitignore create mode 120000 docs/sections/user_guide/cli/tools/rocoto/Makefile create mode 100644 docs/sections/user_guide/cli/tools/rocoto/help.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/help.out create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-exec-file.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-exec-file.out create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdin-stdout.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdin-stdout.out create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout-verbose.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout-verbose.out create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout.out create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-help.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/realize-help.out create mode 100644 docs/sections/user_guide/cli/tools/rocoto/rocoto-bad.xml create mode 100644 docs/sections/user_guide/cli/tools/rocoto/rocoto-good.xml create mode 100644 docs/sections/user_guide/cli/tools/rocoto/rocoto.yaml create mode 100644 docs/sections/user_guide/cli/tools/rocoto/validate-bad-file.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/validate-bad-file.out create mode 100644 docs/sections/user_guide/cli/tools/rocoto/validate-good-file.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/validate-good-file.out create mode 100644 docs/sections/user_guide/cli/tools/rocoto/validate-good-stdin.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/validate-good-stdin.out create mode 100644 docs/sections/user_guide/cli/tools/rocoto/validate-help.cmd create mode 100644 docs/sections/user_guide/cli/tools/rocoto/validate-help.out create mode 100644 docs/sections/user_guide/cli/tools/template/.gitignore create mode 120000 docs/sections/user_guide/cli/tools/template/Makefile create mode 100644 docs/sections/user_guide/cli/tools/template/atparse.txt create mode 100644 docs/sections/user_guide/cli/tools/template/greeting.yaml create mode 100644 docs/sections/user_guide/cli/tools/template/help.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/help.out create mode 100644 docs/sections/user_guide/cli/tools/template/macros create mode 120000 docs/sections/user_guide/cli/tools/template/macros-dir/macros create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-bad-extension.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-bad-extension.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-cli-value.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-cli-value.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-combo-value.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-combo-value.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-dry-run.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-dry-run.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-env-value.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-env-value.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-explicit-extension.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-explicit-extension.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-file.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-file.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-macros-dir.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-macros-dir.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-macros.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-macros.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-missing-value.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-missing-value.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-read-stdin.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-read-stdin.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-sh.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-sh.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-stdout.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-stdout.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-values-needed.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-values-needed.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-verbose.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-exec-verbose.out create mode 100644 docs/sections/user_guide/cli/tools/template/render-help.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/render-help.out create mode 100644 docs/sections/user_guide/cli/tools/template/template create mode 100644 docs/sections/user_guide/cli/tools/template/template-with-macros create mode 100644 docs/sections/user_guide/cli/tools/template/translate-exec-dry-run.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/translate-exec-dry-run.out create mode 100644 docs/sections/user_guide/cli/tools/template/translate-exec-file.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/translate-exec-file.out create mode 100644 docs/sections/user_guide/cli/tools/template/translate-exec-stdout.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/translate-exec-stdout.out create mode 100644 docs/sections/user_guide/cli/tools/template/translate-help.cmd create mode 100644 docs/sections/user_guide/cli/tools/template/translate-help.out create mode 100644 docs/sections/user_guide/cli/tools/template/values.sh create mode 120000 docs/sections/user_guide/cli/tools/template/values.txt create mode 100644 docs/sections/user_guide/cli/tools/template/values.yaml diff --git a/Makefile b/Makefile index d03f1f437..f42433637 100644 --- 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 index 1aceb03fe..fcbe5c56f 100644 --- 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 index 8acf14eb1..9919fa750 100644 --- 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 index e67c98420..c02aea6c3 100644 --- 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 index 53ebffc5b..bdfc5515d 100644 --- 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`, 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`, 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` diff --git a/docs/sections/Makefile b/docs/sections/Makefile new file mode 100644 index 000000000..18df392b4 --- /dev/null +++ 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 index f018d6e79..7fd350b7b 100644 --- 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 ` 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:///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 new file mode 100644 index 000000000..5f252ac32 --- /dev/null +++ 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 new file mode 100644 index 000000000..0e58d33d6 --- /dev/null +++ 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 new file mode 100644 index 000000000..48f78253b --- /dev/null +++ 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 new file mode 120000 index 000000000..d0b0e8e00 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/Makefile @@ -0,0 +1 @@ +../Makefile \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/chgres_cube.rst b/docs/sections/user_guide/cli/drivers/chgres_cube.rst index 9f461f237..a54749a70 100644 --- 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` 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 new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/chgres_cube/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/chgres_cube/help.cmd b/docs/sections/user_guide/cli/drivers/chgres_cube/help.cmd new file mode 100644 index 000000000..1dfd7e37a --- /dev/null +++ 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 new file mode 100644 index 000000000..672f0db44 --- /dev/null +++ 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 new file mode 100644 index 000000000..979f9a816 --- /dev/null +++ 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 new file mode 100644 index 000000000..e4a817eb0 --- /dev/null +++ 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 index e36ed9647..0f560ce3a 100644 --- 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` 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 new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/esg_grid/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/esg_grid/help.cmd b/docs/sections/user_guide/cli/drivers/esg_grid/help.cmd new file mode 100644 index 000000000..ce72c5d9b --- /dev/null +++ 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 new file mode 100644 index 000000000..109b84115 --- /dev/null +++ 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 new file mode 100644 index 000000000..76a3e6ab5 --- /dev/null +++ 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 new file mode 100644 index 000000000..27163b2ff --- /dev/null +++ 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 diff --git a/docs/sections/user_guide/cli/drivers/fv3.rst b/docs/sections/user_guide/cli/drivers/fv3.rst index a4cdd4620..5004c5be6 100644 --- a/docs/sections/user_guide/cli/drivers/fv3.rst +++ b/docs/sections/user_guide/cli/drivers/fv3.rst @@ -3,77 +3,19 @@ The ``uw`` mode for configuring and running FV3. -.. code-block:: text - - $ uw fv3 --help - usage: uw fv3 [-h] [--version] TASK ... - - Execute fv3 tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - boundary_files - Lateral boundary-condition files - diag_table - The diag_table file - field_table - The field_table file - files_copied - Files copied for run - files_linked - Files linked for run - model_configure - The model_configure file - namelist_file - The namelist file - provisioned_run_directory - Run directory provisioned with all required content - restart_directory - The RESTART directory - run - A run - runscript - The runscript - validate - Validate the UW driver config +.. literalinclude:: fv3/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: fv3/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw fv3 run --help - usage: uw fv3 run --config-file PATH --cycle CYCLE [-h] [--version] [--batch] [--dry-run] - [--graph-file PATH] [--quiet] [--verbose] - - A run - - Required arguments: - --config-file PATH, -c PATH - Path to UW YAML config file - --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 - --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:: fv3/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: fv3/run-help.out + :language: text Examples ^^^^^^^^ diff --git a/docs/sections/user_guide/cli/drivers/fv3/Makefile b/docs/sections/user_guide/cli/drivers/fv3/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/fv3/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/fv3/help.cmd b/docs/sections/user_guide/cli/drivers/fv3/help.cmd new file mode 100644 index 000000000..cc6623c31 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/fv3/help.cmd @@ -0,0 +1 @@ +uw fv3 --help diff --git a/docs/sections/user_guide/cli/drivers/fv3/help.out b/docs/sections/user_guide/cli/drivers/fv3/help.out new file mode 100644 index 000000000..6d04aac6f --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/fv3/help.out @@ -0,0 +1,36 @@ +usage: uw fv3 [-h] [--version] TASK ... + +Execute fv3 tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + boundary_files + Lateral boundary-condition files + diag_table + The diag_table file + field_table + The field_table file + files_copied + Files copied for run + files_linked + Files linked for run + model_configure + The model_configure file + namelist_file + The namelist file + provisioned_run_directory + Run directory provisioned with all required content + restart_directory + The RESTART directory + run + A run + runscript + The runscript + validate + Validate the UW driver config diff --git a/docs/sections/user_guide/cli/drivers/fv3/run-help.cmd b/docs/sections/user_guide/cli/drivers/fv3/run-help.cmd new file mode 100644 index 000000000..ac3a1e8ff --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/fv3/run-help.cmd @@ -0,0 +1 @@ +uw fv3 run --help diff --git a/docs/sections/user_guide/cli/drivers/fv3/run-help.out b/docs/sections/user_guide/cli/drivers/fv3/run-help.out new file mode 100644 index 000000000..cb1c1d124 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/fv3/run-help.out @@ -0,0 +1,30 @@ +usage: uw fv3 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/global_equiv_resol.rst b/docs/sections/user_guide/cli/drivers/global_equiv_resol.rst index b7dd7b84f..f849764d1 100644 --- a/docs/sections/user_guide/cli/drivers/global_equiv_resol.rst +++ b/docs/sections/user_guide/cli/drivers/global_equiv_resol.rst @@ -3,64 +3,24 @@ 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 `. -.. code-block:: text - - $ uw global_equiv_resol --help - usage: uw global_equiv_resol [-h] [--version] TASK ... - - Execute global_equiv_resol tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - input_file - Ensure the specified input grid file exists - provisioned_run_directory - Run directory provisioned with all required content - run - A run - runscript - The runscript - validate - Validate the UW driver config +.. 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: -.. code-block:: text - - $ uw global_equiv_resol run --help - usage: uw global_equiv_resol 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:: global_equiv_resol/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: global_equiv_resol/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/global_equiv_resol.yaml diff --git a/docs/sections/user_guide/cli/drivers/global_equiv_resol/Makefile b/docs/sections/user_guide/cli/drivers/global_equiv_resol/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/global_equiv_resol/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/global_equiv_resol/help.cmd b/docs/sections/user_guide/cli/drivers/global_equiv_resol/help.cmd new file mode 100644 index 000000000..1fe4d9d04 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/global_equiv_resol/help.cmd @@ -0,0 +1 @@ +uw global_equiv_resol --help diff --git a/docs/sections/user_guide/cli/drivers/global_equiv_resol/help.out b/docs/sections/user_guide/cli/drivers/global_equiv_resol/help.out new file mode 100644 index 000000000..853dfa5eb --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/global_equiv_resol/help.out @@ -0,0 +1,22 @@ +usage: uw global_equiv_resol [-h] [--version] TASK ... + +Execute global_equiv_resol tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + input_file + Ensure the specified input grid file exists + 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/global_equiv_resol/run-help.cmd b/docs/sections/user_guide/cli/drivers/global_equiv_resol/run-help.cmd new file mode 100644 index 000000000..116d1d279 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/global_equiv_resol/run-help.cmd @@ -0,0 +1 @@ +uw global_equiv_resol run --help diff --git a/docs/sections/user_guide/cli/drivers/global_equiv_resol/run-help.out b/docs/sections/user_guide/cli/drivers/global_equiv_resol/run-help.out new file mode 100644 index 000000000..497807855 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/global_equiv_resol/run-help.out @@ -0,0 +1,27 @@ +usage: uw global_equiv_resol 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 diff --git a/docs/sections/user_guide/cli/drivers/jedi.rst b/docs/sections/user_guide/cli/drivers/jedi.rst index 811b22024..7c8716c7b 100644 --- a/docs/sections/user_guide/cli/drivers/jedi.rst +++ b/docs/sections/user_guide/cli/drivers/jedi.rst @@ -3,74 +3,24 @@ The ``uw`` mode for configuring and running the JEDI framework. -.. code-block:: text - - $ uw jedi --help - usage: uw jedi [-h] [--version] TASK ... - - Execute jedi tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - configuration_file - The JEDI YAML configuration file - files_copied - Files copied for run - files_linked - Files linked for run - provisioned_run_directory - Run directory provisioned with all required content - run - A run - runscript - The runscript - validate - Validate the UW driver config - validate_only - Validate JEDI config YAML +.. literalinclude:: jedi/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: jedi/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw jedi run --help - usage: uw jedi 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:: jedi/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: jedi/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/jedi.yaml diff --git a/docs/sections/user_guide/cli/drivers/jedi/Makefile b/docs/sections/user_guide/cli/drivers/jedi/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/jedi/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/jedi/help.cmd b/docs/sections/user_guide/cli/drivers/jedi/help.cmd new file mode 100644 index 000000000..2702aa0ac --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/jedi/help.cmd @@ -0,0 +1 @@ +uw jedi --help diff --git a/docs/sections/user_guide/cli/drivers/jedi/help.out b/docs/sections/user_guide/cli/drivers/jedi/help.out new file mode 100644 index 000000000..ba762a87c --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/jedi/help.out @@ -0,0 +1,28 @@ +usage: uw jedi [-h] [--version] TASK ... + +Execute jedi tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + configuration_file + The JEDI YAML configuration file + files_copied + Files copied for run + files_linked + Files linked for run + provisioned_run_directory + Run directory provisioned with all required content + run + A run + runscript + The runscript + validate + Validate the UW driver config + validate_only + Validate JEDI config YAML diff --git a/docs/sections/user_guide/cli/drivers/jedi/run-help.cmd b/docs/sections/user_guide/cli/drivers/jedi/run-help.cmd new file mode 100644 index 000000000..c5fe99918 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/jedi/run-help.cmd @@ -0,0 +1 @@ +uw jedi run --help diff --git a/docs/sections/user_guide/cli/drivers/jedi/run-help.out b/docs/sections/user_guide/cli/drivers/jedi/run-help.out new file mode 100644 index 000000000..242e6185c --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/jedi/run-help.out @@ -0,0 +1,30 @@ +usage: uw jedi 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/make_hgrid.rst b/docs/sections/user_guide/cli/drivers/make_hgrid.rst index 7937c02ab..55ee33271 100644 --- a/docs/sections/user_guide/cli/drivers/make_hgrid.rst +++ b/docs/sections/user_guide/cli/drivers/make_hgrid.rst @@ -3,61 +3,24 @@ The ``uw`` mode for configuring and running the UFS Utils preprocessing component ``make_hgrid``. Documentation for this UFS Utils component is :ufs-utils:`here `. -.. code-block:: text - - $ uw make_hgrid --help - usage: uw make_hgrid [-h] [--version] TASK ... - - Execute make_hgrid tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - provisioned_run_directory - Run directory provisioned with all required content - run - A run - runscript - The runscript - validate - Validate the UW driver config +.. literalinclude:: make_hgrid/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: make_hgrid/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw make_hgrid run --help - usage: uw make_hgrid 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 +.. literalinclude:: make_hgrid/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: make_hgrid/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/make_hgrid.yaml diff --git a/docs/sections/user_guide/cli/drivers/make_hgrid/Makefile b/docs/sections/user_guide/cli/drivers/make_hgrid/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_hgrid/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/make_hgrid/help.cmd b/docs/sections/user_guide/cli/drivers/make_hgrid/help.cmd new file mode 100644 index 000000000..2a2c25f00 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_hgrid/help.cmd @@ -0,0 +1 @@ +uw make_hgrid --help diff --git a/docs/sections/user_guide/cli/drivers/make_hgrid/help.out b/docs/sections/user_guide/cli/drivers/make_hgrid/help.out new file mode 100644 index 000000000..36f6313c6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_hgrid/help.out @@ -0,0 +1,20 @@ +usage: uw make_hgrid [-h] [--version] TASK ... + +Execute make_hgrid tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + 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/make_hgrid/run-help.cmd b/docs/sections/user_guide/cli/drivers/make_hgrid/run-help.cmd new file mode 100644 index 000000000..e7b50c470 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_hgrid/run-help.cmd @@ -0,0 +1 @@ +uw make_hgrid run --help diff --git a/docs/sections/user_guide/cli/drivers/make_hgrid/run-help.out b/docs/sections/user_guide/cli/drivers/make_hgrid/run-help.out new file mode 100644 index 000000000..bf4c684d9 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_hgrid/run-help.out @@ -0,0 +1,26 @@ +usage: uw make_hgrid 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 diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic.rst b/docs/sections/user_guide/cli/drivers/make_solo_mosaic.rst index 73db39b06..e93d823a9 100644 --- a/docs/sections/user_guide/cli/drivers/make_solo_mosaic.rst +++ b/docs/sections/user_guide/cli/drivers/make_solo_mosaic.rst @@ -3,62 +3,24 @@ The ``uw`` mode for configuring and running the UFS Utils preprocessing component ``make_solo_mosaic``. Documentation for this UFS Utils component is :ufs-utils:`here `. -.. code-block:: text - - $ uw make_solo_mosaic --help - usage: uw make_solo_mosaic [-h] [--version] TASK ... - - Execute make_solo_mosaic tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - provisioned_run_directory - Run directory provisioned with all required content - run - A run - runscript - The runscript - validate - Validate the UW driver config +.. literalinclude:: make_solo_mosaic/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: make_solo_mosaic/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw make_solo_mosaic run --help - usage: uw make_solo_mosaic 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:: make_solo_mosaic/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: make_solo_mosaic/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/make_solo_mosaic.yaml diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic/Makefile b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic/help.cmd b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/help.cmd new file mode 100644 index 000000000..c648b77fe --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/help.cmd @@ -0,0 +1 @@ +uw make_solo_mosaic --help diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic/help.out b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/help.out new file mode 100644 index 000000000..8cb9d0f21 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/help.out @@ -0,0 +1,20 @@ +usage: uw make_solo_mosaic [-h] [--version] TASK ... + +Execute make_solo_mosaic tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + 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/make_solo_mosaic/run-help.cmd b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/run-help.cmd new file mode 100644 index 000000000..969153b94 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/run-help.cmd @@ -0,0 +1 @@ +uw make_solo_mosaic run --help diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic/run-help.out b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/run-help.out new file mode 100644 index 000000000..843caecf8 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/run-help.out @@ -0,0 +1,26 @@ +usage: uw make_solo_mosaic 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 diff --git a/docs/sections/user_guide/cli/drivers/mpas.rst b/docs/sections/user_guide/cli/drivers/mpas.rst index 1fca7d836..845026aa0 100644 --- a/docs/sections/user_guide/cli/drivers/mpas.rst +++ b/docs/sections/user_guide/cli/drivers/mpas.rst @@ -3,76 +3,24 @@ The ``uw`` mode for configuring and running the MPAS forecast model. Each listed ``TASK`` may be called to generate the runtime asset(s) it is responsible for, and will call any task it depends on as needed. A ``provisioned_run_directory`` comprises everything needed for a run, and a ``run`` runs the MPAS executable. -.. code-block:: text - - $ uw mpas --help - usage: uw mpas [-h] [--version] TASK ... - - Execute mpas tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - boundary_files - Boundary files - files_copied - Files copied for run - files_linked - Files linked for run - namelist_file - The namelist file - provisioned_run_directory - Run directory provisioned with all required content - run - A run - runscript - The runscript - streams_file - The streams file - validate - Validate the UW driver config +.. literalinclude:: mpas/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: mpas/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw mpas run --help - usage: uw mpas 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:: mpas/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: mpas/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/mpas.yaml diff --git a/docs/sections/user_guide/cli/drivers/mpas/Makefile b/docs/sections/user_guide/cli/drivers/mpas/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/mpas/help.cmd b/docs/sections/user_guide/cli/drivers/mpas/help.cmd new file mode 100644 index 000000000..af7fa25e5 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas/help.cmd @@ -0,0 +1 @@ +uw mpas --help diff --git a/docs/sections/user_guide/cli/drivers/mpas/help.out b/docs/sections/user_guide/cli/drivers/mpas/help.out new file mode 100644 index 000000000..dfa120147 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas/help.out @@ -0,0 +1,30 @@ +usage: uw mpas [-h] [--version] TASK ... + +Execute mpas tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + boundary_files + Boundary files + files_copied + Files copied for run + files_linked + Files linked for run + namelist_file + The namelist file + provisioned_run_directory + Run directory provisioned with all required content + run + A run + runscript + The runscript + streams_file + The streams file + validate + Validate the UW driver config diff --git a/docs/sections/user_guide/cli/drivers/mpas/run-help.cmd b/docs/sections/user_guide/cli/drivers/mpas/run-help.cmd new file mode 100644 index 000000000..f0d03def5 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas/run-help.cmd @@ -0,0 +1 @@ +uw mpas run --help diff --git a/docs/sections/user_guide/cli/drivers/mpas/run-help.out b/docs/sections/user_guide/cli/drivers/mpas/run-help.out new file mode 100644 index 000000000..5a5ffb83f --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas/run-help.out @@ -0,0 +1,30 @@ +usage: uw mpas 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/mpas_init.rst b/docs/sections/user_guide/cli/drivers/mpas_init.rst index f5f38e8f4..8f1e30e88 100644 --- a/docs/sections/user_guide/cli/drivers/mpas_init.rst +++ b/docs/sections/user_guide/cli/drivers/mpas_init.rst @@ -3,76 +3,24 @@ The ``uw`` mode for configuring and running the MPAS ``init_atmosphere`` tool. Each listed ``TASK`` may be called to generate the runtime asset(s) it is responsible for, and will call any task it depends on as needed. A ``provisioned_run_directory`` comprises everything needed for a run, and a ``run`` runs the ``init_atmosphere`` executable. -.. code-block:: text - - $ uw mpas_init --help - usage: uw mpas_init [-h] [--version] TASK ... - - Execute mpas_init tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - boundary_files - Boundary files - files_copied - Files copied for run - files_linked - Files linked for run - namelist_file - The namelist file - provisioned_run_directory - Run directory provisioned with all required content - run - A run - runscript - The runscript - streams_file - The streams file - validate - Validate the UW driver config +.. literalinclude:: mpas_init/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: mpas_init/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw mpas_init run --help - usage: uw mpas_init 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:: mpas_init/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: mpas_init/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/mpas_init.yaml diff --git a/docs/sections/user_guide/cli/drivers/mpas_init/Makefile b/docs/sections/user_guide/cli/drivers/mpas_init/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas_init/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/mpas_init/help.cmd b/docs/sections/user_guide/cli/drivers/mpas_init/help.cmd new file mode 100644 index 000000000..3ca5b66ab --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas_init/help.cmd @@ -0,0 +1 @@ +uw mpas_init --help diff --git a/docs/sections/user_guide/cli/drivers/mpas_init/help.out b/docs/sections/user_guide/cli/drivers/mpas_init/help.out new file mode 100644 index 000000000..7ca1dec9d --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas_init/help.out @@ -0,0 +1,30 @@ +usage: uw mpas_init [-h] [--version] TASK ... + +Execute mpas_init tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + boundary_files + Boundary files + files_copied + Files copied for run + files_linked + Files linked for run + namelist_file + The namelist file + provisioned_run_directory + Run directory provisioned with all required content + run + A run + runscript + The runscript + streams_file + The streams file + validate + Validate the UW driver config diff --git a/docs/sections/user_guide/cli/drivers/mpas_init/run-help.cmd b/docs/sections/user_guide/cli/drivers/mpas_init/run-help.cmd new file mode 100644 index 000000000..7c6a0612e --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas_init/run-help.cmd @@ -0,0 +1 @@ +uw mpas_init run --help diff --git a/docs/sections/user_guide/cli/drivers/mpas_init/run-help.out b/docs/sections/user_guide/cli/drivers/mpas_init/run-help.out new file mode 100644 index 000000000..53424102b --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/mpas_init/run-help.out @@ -0,0 +1,30 @@ +usage: uw mpas_init 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/sfc_climo_gen.rst b/docs/sections/user_guide/cli/drivers/sfc_climo_gen.rst index c752b7840..fb796a130 100644 --- a/docs/sections/user_guide/cli/drivers/sfc_climo_gen.rst +++ b/docs/sections/user_guide/cli/drivers/sfc_climo_gen.rst @@ -3,64 +3,24 @@ 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] [--version] TASK ... - - Execute sfc_climo_gen 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:: sfc_climo_gen/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: sfc_climo_gen/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw sfc_climo_gen run --help - usage: uw sfc_climo_gen 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:: sfc_climo_gen/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: sfc_climo_gen/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/sfc_climo_gen.yaml diff --git a/docs/sections/user_guide/cli/drivers/sfc_climo_gen/Makefile b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/sfc_climo_gen/help.cmd b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/help.cmd new file mode 100644 index 000000000..7c458c6bd --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/help.cmd @@ -0,0 +1 @@ +uw sfc_climo_gen --help diff --git a/docs/sections/user_guide/cli/drivers/sfc_climo_gen/help.out b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/help.out new file mode 100644 index 000000000..767418fe3 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/help.out @@ -0,0 +1,22 @@ +usage: uw sfc_climo_gen [-h] [--version] TASK ... + +Execute sfc_climo_gen 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/sfc_climo_gen/run-help.cmd b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/run-help.cmd new file mode 100644 index 000000000..c5b281ae4 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/run-help.cmd @@ -0,0 +1 @@ +uw sfc_climo_gen run --help diff --git a/docs/sections/user_guide/cli/drivers/sfc_climo_gen/run-help.out b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/run-help.out new file mode 100644 index 000000000..2e5f865ed --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/sfc_climo_gen/run-help.out @@ -0,0 +1,26 @@ +usage: uw sfc_climo_gen 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 diff --git a/docs/sections/user_guide/cli/drivers/shave.rst b/docs/sections/user_guide/cli/drivers/shave.rst index aa57466a2..54e68be7d 100644 --- a/docs/sections/user_guide/cli/drivers/shave.rst +++ b/docs/sections/user_guide/cli/drivers/shave.rst @@ -3,62 +3,24 @@ The ``uw`` mode for configuring and running the UFS Utils preprocessing component ``shave``. Documentation for this UFS Utils component is :ufs-utils:`here `. -.. code-block:: text - - $ uw shave --help - usage: uw shave [-h] [--version] TASK ... - - Execute shave tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - provisioned_run_directory - Run directory provisioned with all required content - run - A run - runscript - The runscript - validate - Validate the UW driver config +.. literalinclude:: shave/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: shave/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw shave run --help - usage: uw shave 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:: shave/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: shave/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/shave.yaml diff --git a/docs/sections/user_guide/cli/drivers/shave/Makefile b/docs/sections/user_guide/cli/drivers/shave/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/shave/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/shave/help.cmd b/docs/sections/user_guide/cli/drivers/shave/help.cmd new file mode 100644 index 000000000..0589e90cb --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/shave/help.cmd @@ -0,0 +1 @@ +uw shave --help diff --git a/docs/sections/user_guide/cli/drivers/shave/help.out b/docs/sections/user_guide/cli/drivers/shave/help.out new file mode 100644 index 000000000..d878248a8 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/shave/help.out @@ -0,0 +1,20 @@ +usage: uw shave [-h] [--version] TASK ... + +Execute shave tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + 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/shave/run-help.cmd b/docs/sections/user_guide/cli/drivers/shave/run-help.cmd new file mode 100644 index 000000000..d33e83d45 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/shave/run-help.cmd @@ -0,0 +1 @@ +uw shave run --help diff --git a/docs/sections/user_guide/cli/drivers/shave/run-help.out b/docs/sections/user_guide/cli/drivers/shave/run-help.out new file mode 100644 index 000000000..6f1148e6b --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/shave/run-help.out @@ -0,0 +1,26 @@ +usage: uw shave 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 diff --git a/docs/sections/user_guide/cli/drivers/ungrib.rst b/docs/sections/user_guide/cli/drivers/ungrib.rst index 2ee291526..c45c5fcd7 100644 --- a/docs/sections/user_guide/cli/drivers/ungrib.rst +++ b/docs/sections/user_guide/cli/drivers/ungrib.rst @@ -3,72 +3,24 @@ The ``uw`` mode for configuring and running the WRF preprocessing component ``ungrib``. -.. code-block:: text - - $ uw ungrib --help - usage: uw ungrib [-h] [--version] TASK ... - - Execute ungrib tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - gribfiles - Symlinks to all the GRIB files - 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 - vtable - A symlink to the Vtable file +.. literalinclude:: ungrib/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: ungrib/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw ungrib run --help - usage: uw ungrib 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:: ungrib/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: ungrib/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/ungrib.yaml diff --git a/docs/sections/user_guide/cli/drivers/ungrib/Makefile b/docs/sections/user_guide/cli/drivers/ungrib/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/ungrib/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/ungrib/help.cmd b/docs/sections/user_guide/cli/drivers/ungrib/help.cmd new file mode 100644 index 000000000..94df85e48 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/ungrib/help.cmd @@ -0,0 +1 @@ +uw ungrib --help diff --git a/docs/sections/user_guide/cli/drivers/ungrib/help.out b/docs/sections/user_guide/cli/drivers/ungrib/help.out new file mode 100644 index 000000000..bc616a8c3 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/ungrib/help.out @@ -0,0 +1,26 @@ +usage: uw ungrib [-h] [--version] TASK ... + +Execute ungrib tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + gribfiles + Symlinks to all the GRIB files + 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 + vtable + A symlink to the Vtable file diff --git a/docs/sections/user_guide/cli/drivers/ungrib/run-help.cmd b/docs/sections/user_guide/cli/drivers/ungrib/run-help.cmd new file mode 100644 index 000000000..07170a1f0 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/ungrib/run-help.cmd @@ -0,0 +1 @@ +uw ungrib run --help diff --git a/docs/sections/user_guide/cli/drivers/ungrib/run-help.out b/docs/sections/user_guide/cli/drivers/ungrib/run-help.out new file mode 100644 index 000000000..6733f094b --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/ungrib/run-help.out @@ -0,0 +1,30 @@ +usage: uw ungrib 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/upp.rst b/docs/sections/user_guide/cli/drivers/upp.rst index 60d1def21..75e6bc754 100644 --- a/docs/sections/user_guide/cli/drivers/upp.rst +++ b/docs/sections/user_guide/cli/drivers/upp.rst @@ -3,74 +3,24 @@ The ``uw`` mode for configuring and running the `UPP `_ component. -.. code-block:: text - - $ uw upp --help - usage: uw upp [-h] [--version] TASK ... - - Execute upp tasks - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - TASK - files_copied - Files copied for run - files_linked - Files linked for run - 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:: upp/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: upp/help.out + :language: text All tasks take the same arguments. For example: -.. code-block:: text - - $ uw upp run --help - usage: uw upp run --cycle CYCLE --leadtime LEADTIME [-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) - --leadtime LEADTIME - Leadtime as HH[:MM[:SS]] - - 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:: upp/run-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: upp/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/upp.yaml diff --git a/docs/sections/user_guide/cli/drivers/upp/Makefile b/docs/sections/user_guide/cli/drivers/upp/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/upp/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/drivers/upp/help.cmd b/docs/sections/user_guide/cli/drivers/upp/help.cmd new file mode 100644 index 000000000..938578533 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/upp/help.cmd @@ -0,0 +1 @@ +uw upp --help diff --git a/docs/sections/user_guide/cli/drivers/upp/help.out b/docs/sections/user_guide/cli/drivers/upp/help.out new file mode 100644 index 000000000..baceea494 --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/upp/help.out @@ -0,0 +1,26 @@ +usage: uw upp [-h] [--version] TASK ... + +Execute upp tasks + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + TASK + files_copied + Files copied for run + files_linked + Files linked for run + 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/upp/run-help.cmd b/docs/sections/user_guide/cli/drivers/upp/run-help.cmd new file mode 100644 index 000000000..edb08573c --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/upp/run-help.cmd @@ -0,0 +1 @@ +uw upp run --help diff --git a/docs/sections/user_guide/cli/drivers/upp/run-help.out b/docs/sections/user_guide/cli/drivers/upp/run-help.out new file mode 100644 index 000000000..2e0c9206b --- /dev/null +++ b/docs/sections/user_guide/cli/drivers/upp/run-help.out @@ -0,0 +1,33 @@ +usage: uw upp run --cycle CYCLE --leadtime LEADTIME [-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) + --leadtime LEADTIME + The leadtime as HH[:MM[:SS]] + +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/tools/Makefile b/docs/sections/user_guide/cli/tools/Makefile new file mode 120000 index 000000000..d0b0e8e00 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/Makefile @@ -0,0 +1 @@ +../Makefile \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/config.rst b/docs/sections/user_guide/cli/tools/config.rst index b441c78a5..ba4fbee7b 100644 --- a/docs/sections/user_guide/cli/tools/config.rst +++ b/docs/sections/user_guide/cli/tools/config.rst @@ -3,147 +3,84 @@ The ``uw`` mode for handling configuration files (configs). -.. code-block:: text - - $ uw config --help - usage: uw config [-h] [--version] ACTION ... - - Handle configs - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - ACTION - compare - Compare configs - realize - Realize config - validate - Validate config +.. literalinclude:: config/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: config/help.out + :language: text .. _cli_config_compare_examples: ``compare`` ----------- -The ``compare`` action lets users compare two config files. - -.. code-block:: text - - $ uw config compare --help - usage: uw config compare --file-1-path PATH --file-2-path PATH [-h] [--version] - [--file-1-format {ini,nml,sh,yaml}] [--file-2-format {ini,nml,sh,yaml}] - [--quiet] [--verbose] - - Compare configs - - Required arguments: - --file-1-path PATH - Path to file 1 - --file-2-path PATH - Path to file 2 - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - --file-1-format {ini,nml,sh,yaml} - Format of file 1 - --file-2-format {ini,nml,sh,yaml} - Format of file 2 - --quiet, -q - Print no logging messages - --verbose, -v - Print all logging messages +The ``compare`` action compares two config files. + +.. literalinclude:: config/compare-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: config/compare-help.out + :language: text Examples ^^^^^^^^ -The examples that follow use namelist files ``values1.nml`` and ``values2.nml``, both initially with the following contents: - -.. code-block:: fortran +The examples that follow use identical namelist files ``a.nml`` and ``b.nml`` with contents: - &values - greeting = "Hello" - recipient = "World" - / +.. literalinclude:: config/a.nml + :language: fortran * To compare two config files with the same contents: - .. code-block:: text - - $ uw config compare --file-1-path values1.nml --file-2-path values2.nml - [2024-01-08T16:53:04] INFO - values1.nml - [2024-01-08T16:53:04] INFO + values2.nml - [2024-01-08T16:53:04] INFO --------------------------------------------------------------------- - -* If there are differences between the config files, they will be shown below the dashed line. For example, with ``recipient: World`` removed from ``values1.nml``: + .. literalinclude:: config/compare-match.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/compare-match.out + :language: text - .. code-block:: text +* If there are differences between the config files, they will be shown below the dashed line. For example, ``c.nml`` is missing the line ``recipient: World``: - $ uw config compare --file-1-path values1.nml --file-2-path values2.nml - [2024-01-08T16:54:03] INFO - values1.nml - [2024-01-08T16:54:03] INFO + values2.nml - [2024-01-08T16:54:03] INFO --------------------------------------------------------------------- - [2024-01-08T16:54:03] INFO values: recipient: - None + World + .. literalinclude:: config/c.nml + :language: fortran + .. literalinclude:: config/compare-diff.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/compare-diff.out + :language: text * If a config file has an unrecognized (or no) extension, ``uw`` will not know how to parse its contents: - .. code-block:: text + .. literalinclude:: config/compare-bad-extension.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/compare-bad-extension.out + :language: text - $ uw config compare --file-1-path values.txt --file-2-path values1.nml - Cannot deduce format of 'values.txt' from unknown extension 'txt' + The format must be explicitly specified (``a.txt`` is a copy of ``a.nml``): - In this case, the format can be explicitly specified (``values.txt`` is a copy of ``values1.nml``): - - .. code-block:: text - - $ uw config compare --file-1-path values.txt --file-1-format nml --file-2-path values2.nml - [2024-01-08T16:56:54] INFO - values.txt - [2024-01-08T16:56:54] INFO + values2.nml - [2024-01-08T16:56:54] INFO --------------------------------------------------------------------- - [2024-01-08T16:56:54] INFO values: recipient: - None + World + .. literalinclude:: config/compare-bad-extension-fix.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/compare-bad-extension-fix.out + :language: text * To request verbose log output: - .. code-block:: text - - $ uw config compare --file-1-path values1.nml --file-2-path values2.nml --verbose - [2024-01-08T16:57:28] DEBUG Command: uw config compare --file-1-path values1.nml --file-2-path values2.nml --verbose - [2024-01-08T16:57:28] INFO - values1.nml - [2024-01-08T16:57:28] INFO + values2.nml - [2024-01-08T16:57:28] INFO --------------------------------------------------------------------- - [2024-01-08T16:57:28] INFO values: recipient: - None + 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``, so the stream can be redirected: - - .. code-block:: text - - $ uw config compare --file-1-path values1.nml --file-2-path values2.nml --verbose 2>compare.log + .. literalinclude:: config/compare-verbose.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/compare-verbose.out + :language: text - The contents of ``compare.log``: - - .. code-block:: text - - [2024-01-08T16:59:20] DEBUG Command: uw config compare --file-1-path values1.nml --file-2-path values2.nml --verbose - [2024-01-08T16:59:20] INFO - values1.nml - [2024-01-08T16:59:20] INFO + values2.nml - [2024-01-08T16:59:20] INFO --------------------------------------------------------------------- - [2024-01-08T16:59:20] INFO values: recipient: - None + World + Note that ``uw`` logs to ``stderr``. Use :shell-redirection:`shell redirection<>` as needed. .. note:: Comparisons are supported only for configs of the same format, e.g. YAML vs YAML, Fortran namelist vs Fortran namelist, etc. ``uw`` will flag invalid comparisons: - .. code-block:: text - - $ uw config compare --file-1-path a.yaml --file-2-path b.nml - [2024-01-23T23:21:37] ERROR Formats do not match: yaml vs nml + .. literalinclude:: config/compare-format-mismatch.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/compare-format-mismatch.out + :language: text .. _cli_config_realize_examples: @@ -152,209 +89,115 @@ The examples that follow use namelist files ``values1.nml`` and ``values2.nml``, In ``uw`` terminology, to realize a configuration file is to transform it from its raw form into its final, usable state. The ``realize`` action can build a complete config file from two or more separate files. -.. code-block:: text - - $ uw config realize --help - usage: uw config realize [-h] [--version] [--input-file PATH] [--input-format {ini,nml,sh,yaml}] - [--update-file PATH] [--update-format {ini,nml,sh,yaml}] - [--output-file PATH] [--output-format {ini,nml,sh,yaml}] - [--output-block KEY[.KEY[.KEY]...]] [--values-needed] [--total] - [--dry-run] [--quiet] [--verbose] - - Realize config - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - --input-file PATH, -i PATH - Path to input file (defaults to stdin) - --input-format {ini,nml,sh,yaml} - Input format - --update-file PATH, -u PATH - Path to update file (defaults to stdin) - --update-format {ini,nml,sh,yaml} - Input format - --output-file PATH, -o PATH - Path to output file (defaults to stdout) - --output-format {ini,nml,sh,yaml} - Output format - --output-block KEY[.KEY[.KEY]...] - Dot-separated path of keys to the block to be output - --values-needed - Print report of values needed to render template - --total - Require rendering of all Jinja2 variables/expressions - --dry-run - Only log info, making no changes - --quiet, -q - Print no logging messages - --verbose, -v - Print all logging messages +.. literalinclude:: config/realize-help.cmd + :emphasize-lines: 1 +.. literalinclude:: config/realize-help.out + :language: text Examples ^^^^^^^^ -The initial examples in this section use YAML file ``config.yaml`` with the following contents: - -.. code-block:: yaml +The initial examples in this section use YAML file ``config.yaml`` with contents: - values: - date: '{{ yyyymmdd }}' - empty: - greeting: Hello - message: '{{ ((greeting + " " + recipient + " ") * repeat) | trim }}' - recipient: World - repeat: 1 +.. literalinclude:: config/config.yaml + :language: yaml -and YAML file ``update.yaml`` with the following contents: +and YAML file ``update.yaml`` with contents: -.. code-block:: yaml +.. literalinclude:: config/update.yaml + :language: yaml - values: - date: 20240105 - greeting: Good Night - recipient: Moon - repeat: 2 +* For a report of input-config values with unrendered Jinja2 variables/expressions or empty/null keys: -* To show the values in the input config file that have unrendered Jinja2 variables/expressions or empty keys: - - .. code-block:: text - - $ uw config realize --input-file config.yaml --output-format yaml --values-needed - [2024-05-20T18:33:01] INFO Keys that are complete: - [2024-05-20T18:33:01] INFO values - [2024-05-20T18:33:01] INFO values.greeting - [2024-05-20T18:33:01] INFO values.message - [2024-05-20T18:33:01] INFO values.recipient - [2024-05-20T18:33:01] INFO values.repeat - [2024-05-20T18:33:01] INFO - [2024-05-20T18:33:01] INFO Keys with unrendered Jinja2 variables/expressions: - [2024-05-20T18:33:01] INFO values.date: {{ yyyymmdd }} - [2024-05-20T18:33:01] INFO - [2024-05-20T18:33:01] INFO Keys that are set to empty: - [2024-05-20T18:33:01] INFO values.empty + .. literalinclude:: config/realize-values-needed.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-values-needed.out + :language: text * To realize the config to ``stdout``, the output format must be explicitly specified: - .. code-block:: text + .. literalinclude:: config/realize-stdout.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-stdout.out + :language: text - $ uw config realize --input-file config.yaml --output-format yaml - values: - date: '{{ yyyymmdd }}' - empty: null - greeting: Hello - message: Hello World - recipient: World - repeat: 1 - - Shell redirection via ``|``, ``>``, et al. may also be used to stream output to a file, another process, etc. + :shell-redirection:`Shell redirection<>` may also be used to stream output to a file, another process, etc. * Values in the input file can be updated via an optional update file: - .. code-block:: text - - $ uw config realize --input-file config.yaml --update-file update.yaml --output-format yaml - values: - date: 20240105 - empty: null - greeting: Good Night - message: Good Night Moon Good Night Moon - recipient: Moon - repeat: 2 + .. literalinclude:: config/realize-update-file.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-update-file.out + :language: text * To realize the config to a file via command-line argument: - .. code-block:: text - - $ uw config realize --input-file config.yaml --update-file update.yaml --output-file realized.yaml - - The contents of ``realized.yaml``: - - .. code-block:: yaml - - values: - date: 20240105 - empty: null - greeting: Good Night - message: Good Night Moon Good Night Moon - recipient: Moon - repeat: 2 + .. literalinclude:: config/realize-update-file-outfile.cmd + :language: text + :emphasize-lines: 2 + .. literalinclude:: config/realize-update-file-outfile.out + :language: text * With the ``--dry-run`` flag specified, nothing is written to ``stdout`` (or to a file if ``--output-file`` is specified), but a report of what would have been written is logged to ``stderr``: - .. code-block:: text - - $ uw config realize --input-file config.yaml --update-file update.yaml --output-file realized.yaml --dry-run - [2024-05-20T19:05:55] INFO values: - [2024-05-20T19:05:55] INFO date: 20240105 - [2024-05-20T19:05:55] INFO empty: null - [2024-05-20T19:05:55] INFO greeting: Good Night - [2024-05-20T19:05:55] INFO message: Good Night Moon Good Night Moon - [2024-05-20T19:05:55] INFO recipient: Moon - [2024-05-20T19:05:55] INFO repeat: 2 + .. literalinclude:: config/realize-dry-run.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-dry-run.out + :language: text * If the config file has an unrecognized (or no) extension, ``uw`` will not automatically know how to parse its contents: - .. code-block:: text - - $ uw config realize --input-file config.txt --update-file update.yaml --output-format yaml - Cannot deduce format of 'config.txt' from unknown extension 'txt' - - The format must be explicitly specified (``config.txt`` is a copy of ``config.yaml``): + .. literalinclude:: config/realize-extension-file-bad.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-extension-file-bad.out + :language: text - .. code-block:: text + The format must be explicitly specified (here, ``config.txt`` is a copy of ``config.yaml``): - $ uw config realize --input-file config.txt --update-file update.yaml --output-format yaml --input-format yaml - values: - date: 20240105 - empty: null - greeting: Good Night - message: Good Night Moon Good Night Moon - recipient: Moon - repeat: 2 + .. literalinclude:: config/realize-extension-file-fix.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-extension-file-fix.out + :language: text * Similarly, if an input file is read from ``stdin``, ``uw`` will not automatically know how to parse its contents: - .. code-block:: text - - $ cat config.yaml | uw config realize --update-file update.yaml --output-format yaml - Specify --input-format when --input-file is not specified + .. literalinclude:: config/realize-extension-stdin-bad.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-extension-stdin-bad.out + :language: text The format must be explicitly specified: - .. code-block:: text - - $ cat config.yaml | uw config realize --update-file update.yaml --output-format yaml --input-format yaml - values: - date: 20240105 - empty: null - greeting: Good Night - message: Good Night Moon Good Night Moon - recipient: Moon - repeat: 2 + .. literalinclude:: config/realize-extension-stdin-fix.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-extension-stdin-fix.out + :language: text * This example demonstrates: 1. Reading a config from ``stdin``, 2. Extracting a specific subsection with the ``--output-block`` option, and 3. Writing the output in a different format: - .. code-block:: text - - $ cat config.yaml | uw config realize --input-format yaml --update-file update.yaml --output-block values --output-format sh - date=20240105 - empty=None - greeting='Good Night' - message='Good Night Moon Good Night Moon' - recipient=Moon - repeat=2 + .. literalinclude:: config/realize-combo.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-combo.out + :language: text .. note:: Combining configs with incompatible depths is not supported. ``ini`` and ``nml`` configs are depth-2, as they organize their key-value pairs (one level) under top-level sections or namelists (a second level). ``sh`` configs are depth-1, and ``yaml`` configs have arbitrary depth. For example, when attempting to generate a ``sh`` config from the original depth-2 ``config.yaml``: - .. code-block:: text - - $ uw config realize --input-file config.yaml --output-format sh - [2024-05-20T19:17:02] ERROR Cannot realize depth-2 config to type-'sh' config + .. literalinclude:: config/realize-depth-mismatch.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-depth-mismatch.out + :language: text * It is possible to provide the update config, rather than the input config, on ``stdin``. Usage rules are as follows: @@ -364,138 +207,49 @@ and YAML file ``update.yaml`` with the following contents: For example, here the update config is provided on ``stdin`` and the input config is read from a file: - .. code-block:: text - - $ echo "yyyymmdd: 20240520" | uw config realize --input-file config.yaml --update-format yaml --output-format yaml - values: - date: '20240520' - empty: null - greeting: Hello - message: Hello World - recipient: World - repeat: 1 - yyyymmdd: 20240520 + .. literalinclude:: config/realize-update-stdin.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-update-stdin.out + :language: text * By default, variables/expressions that cannot be rendered are passed through unchanged in the output. For example, given config file ``flowers.yaml`` with contents - .. code-block:: yaml - - roses: "{{ color1 }}" - violets: "{{ color2 }}" - color1: red - - .. code-block:: text - - $ uw config realize --input-file flowers.yaml --output-format yaml - roses: red - violets: '{{ color2 }}' - color1: red - $ echo $? - 0 + .. literalinclude:: config/flowers.yaml + :language: yaml + .. literalinclude:: config/realize-flowers-noop.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-flowers-noop.out + :language: text Adding the ``--total`` flag, however, requires ``uw`` to totally realize the config, and to exit with error status if it cannot: - .. code-block:: text + .. literalinclude:: config/realize-flowers-total.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-flowers-total.out + :language: text - $ uw config realize --input-file flowers.yaml --output-format yaml --total - [2024-05-20T18:39:37] ERROR Config could not be realized. Try with --values-needed for details. - $ echo $? - 1 +* Realization of individual values is all-or-nothing. If a single value contains a mix of renderable and unrenderable variables/expressions, then the entire value remains unrealized. For example, given ``roses.yaml`` with contents -* Realization of individual values is all-or-nothing. If a single value contains a mix of renderable and unrenderable variables/expressions, then the entire value remains unrealized. For example, given ``flowers.yaml`` with contents - - .. code-block:: yaml - - roses: "{{ color1 }} or {{ color2 }}" - color1: red - - .. code-block:: text - - $ uw config realize --input-file flowers.yaml --output-format yaml - roses: '{{ color1 }} or {{ color2 }}' - color1: red + .. literalinclude:: config/roses.yaml + :language: yaml + .. literalinclude:: config/realize-roses-noop.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-roses-noop.out + :language: text * To request verbose log output: - .. code-block:: text - - $ echo "{hello: '{{ recipient }}', recipient: world}" | uw config realize --input-format yaml --output-format yaml --verbose - [2024-05-20T19:09:21] DEBUG Command: uw config realize --input-format yaml --output-format yaml --verbose - [2024-05-20T19:09:21] DEBUG Reading input from stdin - [2024-05-20T19:09:21] DEBUG Dereferencing, current value: - [2024-05-20T19:09:21] DEBUG hello: '{{ recipient }}' - [2024-05-20T19:09:21] DEBUG recipient: world - [2024-05-20T19:09:21] DEBUG [dereference] Rendering: {{ recipient }} - [2024-05-20T19:09:21] DEBUG [dereference] Rendered: world - [2024-05-20T19:09:21] DEBUG [dereference] Rendering: hello - [2024-05-20T19:09:21] DEBUG [dereference] Rendered: hello - [2024-05-20T19:09:21] DEBUG [dereference] Rendering: world - [2024-05-20T19:09:21] DEBUG [dereference] Rendered: world - [2024-05-20T19:09:21] DEBUG [dereference] Rendering: recipient - [2024-05-20T19:09:21] DEBUG [dereference] Rendered: recipient - [2024-05-20T19:09:21] DEBUG Dereferencing, current value: - [2024-05-20T19:09:21] DEBUG hello: world - [2024-05-20T19:09:21] DEBUG recipient: world - [2024-05-20T19:09:21] DEBUG [dereference] Rendering: world - [2024-05-20T19:09:21] DEBUG [dereference] Rendered: world - [2024-05-20T19:09:21] DEBUG [dereference] Rendering: hello - [2024-05-20T19:09:21] DEBUG [dereference] Rendered: hello - [2024-05-20T19:09:21] DEBUG [dereference] Rendering: world - [2024-05-20T19:09:21] DEBUG [dereference] Rendered: world - [2024-05-20T19:09:21] DEBUG [dereference] Rendering: recipient - [2024-05-20T19:09:21] DEBUG [dereference] Rendered: recipient - [2024-05-20T19:09:21] DEBUG Dereferencing, final value: - [2024-05-20T19:09:21] DEBUG hello: world - [2024-05-20T19:09:21] DEBUG recipient: world - [2024-05-20T19:09:21] DEBUG Writing output to stdout - hello: world - recipient: world - - Note that ``uw`` logs to ``stderr`` and writes non-log output to ``stdout``, so the streams can be redirected separately: - - .. code-block:: text - - $ echo "{hello: '{{ recipient }}', recipient: world}" | uw config realize --input-format yaml --output-format yaml --verbose >realized.yaml 2>realized.log - - The contents of ``realized.yaml``: - - .. code-block:: yaml - - hello: world - recipient: world - - The contents of ``realized.log``: - - .. code-block:: text - - [2024-05-20T19:10:11] DEBUG Command: uw config realize --input-format yaml --output-format yaml --verbose - [2024-05-20T19:10:11] DEBUG Reading input from stdin - [2024-05-20T19:10:11] DEBUG Dereferencing, current value: - [2024-05-20T19:10:11] DEBUG hello: '{{ recipient }}' - [2024-05-20T19:10:11] DEBUG recipient: world - [2024-05-20T19:10:11] DEBUG [dereference] Rendering: {{ recipient }} - [2024-05-20T19:10:11] DEBUG [dereference] Rendered: world - [2024-05-20T19:10:11] DEBUG [dereference] Rendering: hello - [2024-05-20T19:10:11] DEBUG [dereference] Rendered: hello - [2024-05-20T19:10:11] DEBUG [dereference] Rendering: world - [2024-05-20T19:10:11] DEBUG [dereference] Rendered: world - [2024-05-20T19:10:11] DEBUG [dereference] Rendering: recipient - [2024-05-20T19:10:11] DEBUG [dereference] Rendered: recipient - [2024-05-20T19:10:11] DEBUG Dereferencing, current value: - [2024-05-20T19:10:11] DEBUG hello: world - [2024-05-20T19:10:11] DEBUG recipient: world - [2024-05-20T19:10:11] DEBUG [dereference] Rendering: world - [2024-05-20T19:10:11] DEBUG [dereference] Rendered: world - [2024-05-20T19:10:11] DEBUG [dereference] Rendering: hello - [2024-05-20T19:10:11] DEBUG [dereference] Rendered: hello - [2024-05-20T19:10:11] DEBUG [dereference] Rendering: world - [2024-05-20T19:10:11] DEBUG [dereference] Rendered: world - [2024-05-20T19:10:11] DEBUG [dereference] Rendering: recipient - [2024-05-20T19:10:11] DEBUG [dereference] Rendered: recipient - [2024-05-20T19:10:11] DEBUG Dereferencing, final value: - [2024-05-20T19:10:11] DEBUG hello: world - [2024-05-20T19:10:11] DEBUG recipient: world - [2024-05-20T19:10:11] DEBUG Writing output to stdout + .. literalinclude:: config/realize-verbose.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/realize-verbose.out + :language: text + + Note that ``uw`` logs to ``stderr`` and writes non-log output to ``stdout``, so the streams can be redirected separately via :shell-redirection:`shell redirection<>`. .. _cli_config_validate_examples: @@ -504,137 +258,59 @@ and YAML file ``update.yaml`` with the following contents: The ``validate`` action ensures that a given config file is structured properly. -.. code-block:: text - - $ uw config validate --help - usage: uw config validate --schema-file PATH [-h] [--version] [--input-file PATH] [--quiet] - [--verbose] - - Validate config - - Required arguments: - --schema-file PATH - Path to schema file to use for validation - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - --input-file PATH, -i PATH - Path to input file (defaults to stdin) - --quiet, -q - Print no logging messages - --verbose, -v - Print all logging messages + .. literalinclude:: config/validate-help.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/validate-help.out + :language: text Examples ^^^^^^^^ -The examples that follow use the :json-schema:`JSON Schema` file ``schema.jsonschema`` with the following contents: - -.. code-block:: json - - { - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "properties": { - "values": { - "type": "object", - "properties": { - "greeting": { - "type": "string" - }, - "recipient": { - "type": "string" - } - }, - "required": ["greeting", "recipient"], - "additionalProperties": false - } - }, - "required": ["values"], - "additionalProperties": false - } - -and the YAML file ``values.yaml`` with the following contents: - -.. code-block:: yaml - - values: - greeting: Hello - recipient: World - -* To validate a YAML config against a given JSON schema: - - .. code-block:: text - - $ uw config validate --schema-file schema.jsonschema --input-file values.yaml - [2024-01-03T17:23:07] INFO 0 UW schema-validation errors found +The examples that follow use the :json-schema:`JSON Schema` file ``schema.jsonschema`` with contents: - Shell redirection via ``|``, ``>``, et al. may also be used to stream output to a file, another process, etc. +.. literalinclude:: config/schema.jsonschema + :language: json -* To read the *config* from ``stdin`` and print validation results to ``stdout``: +and the YAML file ``values.yaml`` with contents: - .. code-block:: text +.. literalinclude:: config/values.yaml + :language: yaml - $ cat values.yaml | uw config validate --schema-file schema.jsonschema - [2024-01-03T17:26:29] INFO 0 UW schema-validation errors found +* To validate a YAML config against a given JSON schema: -* However, reading the *schema* from ``stdin`` is **not** supported: + .. literalinclude:: config/validate-pass.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/validate-pass.out + :language: text - .. code-block:: text + :shell-redirection:`Shell redirection<>` may also be used to stream output to a file, another process, etc. - $ cat schema.jsonschema | uw config validate --input-file values.yaml - uw config validate: error: the following arguments are required: --schema-file +* To read the *config* from ``stdin`` and print validation results to ``stdout``: -* If a config fails validation, differences from the schema will be displayed. For example, with ``recipient: World`` removed from ``values.yaml``: + .. literalinclude:: config/validate-pass-stdin.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/validate-pass-stdin.out + :language: text - .. code-block:: text +* If a config fails validation, differences from the schema will be displayed. For example, ``values-bad.yaml``: - $ uw config validate --schema-file schema.jsonschema --input-file values.yaml - [2024-01-03T17:31:19] ERROR 1 UW schema-validation error found - [2024-01-03T17:31:19] ERROR 'recipient' is a required property - [2024-01-03T17:31:19] ERROR - [2024-01-03T17:31:19] ERROR Failed validating 'required' in schema['properties']['values']: - [2024-01-03T17:31:19] ERROR {'additionalProperties': False, - [2024-01-03T17:31:19] ERROR 'properties': {'greeting': {'type': 'string'}, - [2024-01-03T17:31:19] ERROR 'recipient': {'type': 'string'}}, - [2024-01-03T17:31:19] ERROR 'required': ['greeting', 'recipient'], - [2024-01-03T17:31:19] ERROR 'type': 'object'} - [2024-01-03T17:31:19] ERROR - [2024-01-03T17:31:19] ERROR On instance['values']: - [2024-01-03T17:31:19] ERROR {'greeting': 'Hello'} + .. literalinclude:: config/values-bad.yaml + :language: yaml + .. literalinclude:: config/validate-fail.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/validate-fail.out + :language: text * To request verbose log output: - .. code-block:: text - - $ uw config validate --schema-file schema.jsonschema --input-file values.yaml --verbose - [2024-01-03T17:29:46] DEBUG Command: uw config validate --schema-file schema.jsonschema --input-file values.yaml --verbose - [2024-01-03T17:29:46] DEBUG Dereferencing, initial value: {'values': {'greeting': 'Hello', 'recipient': 'World'}} - [2024-01-03T17:29:46] DEBUG Rendering: {'values': {'greeting': 'Hello', 'recipient': 'World'}} - [2024-01-03T17:29:46] DEBUG Rendering: {'greeting': 'Hello', 'recipient': 'World'} - [2024-01-03T17:29:46] DEBUG Rendering: Hello - [2024-01-03T17:29:46] DEBUG Rendering: World - [2024-01-03T17:29:46] DEBUG Dereferencing, final value: {'values': {'greeting': 'Hello', 'recipient': 'World'}} - [2024-01-03T17:29:46] INFO 0 UW schema-validation errors found - - Note that ``uw`` logs to ``stderr``, so the stream can be redirected: - - .. code-block:: text - - $ uw config validate --schema-file schema.jsonschema --input-file values.yaml --verbose 2>validate.log - - The contents of ``validate.log``: - - .. code-block:: text + .. literalinclude:: config/validate-verbose.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: config/validate-verbose.out + :language: text - [2024-01-03T17:30:49] DEBUG Command: uw config validate --schema-file schema.jsonschema --input-file values.yaml --verbose - [2024-01-03T17:30:49] DEBUG Dereferencing, initial value: {'values': {'greeting': 'Hello', 'recipient': 'World'}} - [2024-01-03T17:30:49] DEBUG Rendering: {'values': {'greeting': 'Hello', 'recipient': 'World'}} - [2024-01-03T17:30:49] DEBUG Rendering: {'greeting': 'Hello', 'recipient': 'World'} - [2024-01-03T17:30:49] DEBUG Rendering: Hello - [2024-01-03T17:30:49] DEBUG Rendering: World - [2024-01-03T17:30:49] DEBUG Dereferencing, final value: {'values': {'greeting': 'Hello', 'recipient': 'World'}} - [2024-01-03T17:30:49] INFO 0 UW schema-validation errors found + Note that ``uw`` logs to ``stderr``, so the stream can be :shell-redirection:`redirected<>`. diff --git a/docs/sections/user_guide/cli/tools/config/.gitignore b/docs/sections/user_guide/cli/tools/config/.gitignore new file mode 100644 index 000000000..914d9ad87 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/.gitignore @@ -0,0 +1 @@ +realized.yaml diff --git a/docs/sections/user_guide/cli/tools/config/Makefile b/docs/sections/user_guide/cli/tools/config/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/config/a.nml b/docs/sections/user_guide/cli/tools/config/a.nml new file mode 100644 index 000000000..4cb398a88 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/a.nml @@ -0,0 +1,4 @@ +&values + greeting = "Hello" + recipient = "World" +/ diff --git a/docs/sections/user_guide/cli/tools/config/a.txt b/docs/sections/user_guide/cli/tools/config/a.txt new file mode 120000 index 000000000..830550093 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/a.txt @@ -0,0 +1 @@ +a.nml \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/config/b.nml b/docs/sections/user_guide/cli/tools/config/b.nml new file mode 120000 index 000000000..830550093 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/b.nml @@ -0,0 +1 @@ +a.nml \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/config/c.nml b/docs/sections/user_guide/cli/tools/config/c.nml new file mode 100644 index 000000000..7f1bb5f17 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/c.nml @@ -0,0 +1,3 @@ +&values + greeting = "Hello" +/ diff --git a/docs/sections/user_guide/cli/tools/config/compare-bad-extension-fix.cmd b/docs/sections/user_guide/cli/tools/config/compare-bad-extension-fix.cmd new file mode 100644 index 000000000..704fc84f1 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-bad-extension-fix.cmd @@ -0,0 +1 @@ +uw config compare --file-1-path a.txt --file-1-format nml --file-2-path c.nml diff --git a/docs/sections/user_guide/cli/tools/config/compare-bad-extension-fix.out b/docs/sections/user_guide/cli/tools/config/compare-bad-extension-fix.out new file mode 100644 index 000000000..867c6f0dd --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-bad-extension-fix.out @@ -0,0 +1,4 @@ +[2024-05-23T19:39:15] INFO - a.txt +[2024-05-23T19:39:15] INFO + c.nml +[2024-05-23T19:39:15] INFO --------------------------------------------------------------------- +[2024-05-23T19:39:15] INFO values: recipient: - World + None diff --git a/docs/sections/user_guide/cli/tools/config/compare-bad-extension.cmd b/docs/sections/user_guide/cli/tools/config/compare-bad-extension.cmd new file mode 100644 index 000000000..785b75ba6 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-bad-extension.cmd @@ -0,0 +1 @@ +uw config compare --file-1-path a.txt --file-2-path c.nml diff --git a/docs/sections/user_guide/cli/tools/config/compare-bad-extension.out b/docs/sections/user_guide/cli/tools/config/compare-bad-extension.out new file mode 100644 index 000000000..de658e238 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-bad-extension.out @@ -0,0 +1 @@ +Cannot deduce format of 'a.txt' from unknown extension 'txt' diff --git a/docs/sections/user_guide/cli/tools/config/compare-diff.cmd b/docs/sections/user_guide/cli/tools/config/compare-diff.cmd new file mode 100644 index 000000000..50bc7da1c --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-diff.cmd @@ -0,0 +1 @@ +uw config compare --file-1-path a.nml --file-2-path c.nml diff --git a/docs/sections/user_guide/cli/tools/config/compare-diff.out b/docs/sections/user_guide/cli/tools/config/compare-diff.out new file mode 100644 index 000000000..9c33b4c5b --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-diff.out @@ -0,0 +1,4 @@ +[2024-05-23T19:39:16] INFO - a.nml +[2024-05-23T19:39:16] INFO + c.nml +[2024-05-23T19:39:16] INFO --------------------------------------------------------------------- +[2024-05-23T19:39:16] INFO values: recipient: - World + None diff --git a/docs/sections/user_guide/cli/tools/config/compare-format-mismatch.cmd b/docs/sections/user_guide/cli/tools/config/compare-format-mismatch.cmd new file mode 100644 index 000000000..3338582cc --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-format-mismatch.cmd @@ -0,0 +1 @@ +uw config compare --file-1-path a.nml --file-2-path b.yaml diff --git a/docs/sections/user_guide/cli/tools/config/compare-format-mismatch.out b/docs/sections/user_guide/cli/tools/config/compare-format-mismatch.out new file mode 100644 index 000000000..3cb24b4eb --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-format-mismatch.out @@ -0,0 +1 @@ +[2024-05-23T19:39:15] ERROR Formats do not match: nml vs yaml diff --git a/docs/sections/user_guide/cli/tools/config/compare-help.cmd b/docs/sections/user_guide/cli/tools/config/compare-help.cmd new file mode 100644 index 000000000..fa84d59dd --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-help.cmd @@ -0,0 +1 @@ +uw config compare --help diff --git a/docs/sections/user_guide/cli/tools/config/compare-help.out b/docs/sections/user_guide/cli/tools/config/compare-help.out new file mode 100644 index 000000000..9fa1e0ecd --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-help.out @@ -0,0 +1,26 @@ +usage: uw config compare --file-1-path PATH --file-2-path PATH [-h] + [--version] [--file-1-format {ini,nml,sh,yaml}] + [--file-2-format {ini,nml,sh,yaml}] [--quiet] + [--verbose] + +Compare configs + +Required arguments: + --file-1-path PATH + Path to file 1 + --file-2-path PATH + Path to file 2 + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + --file-1-format {ini,nml,sh,yaml} + Format of file 1 + --file-2-format {ini,nml,sh,yaml} + Format of file 2 + --quiet, -q + Print no logging messages + --verbose, -v + Print all logging messages diff --git a/docs/sections/user_guide/cli/tools/config/compare-match.cmd b/docs/sections/user_guide/cli/tools/config/compare-match.cmd new file mode 100644 index 000000000..d8438642a --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-match.cmd @@ -0,0 +1 @@ +uw config compare --file-1-path a.nml --file-2-path b.nml diff --git a/docs/sections/user_guide/cli/tools/config/compare-match.out b/docs/sections/user_guide/cli/tools/config/compare-match.out new file mode 100644 index 000000000..c10927611 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-match.out @@ -0,0 +1,3 @@ +[2024-05-23T19:39:15] INFO - a.nml +[2024-05-23T19:39:15] INFO + b.nml +[2024-05-23T19:39:15] INFO --------------------------------------------------------------------- diff --git a/docs/sections/user_guide/cli/tools/config/compare-verbose.cmd b/docs/sections/user_guide/cli/tools/config/compare-verbose.cmd new file mode 100644 index 000000000..fd8e4596f --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-verbose.cmd @@ -0,0 +1 @@ +uw config compare --file-1-path a.nml --file-2-path c.nml --verbose diff --git a/docs/sections/user_guide/cli/tools/config/compare-verbose.out b/docs/sections/user_guide/cli/tools/config/compare-verbose.out new file mode 100644 index 000000000..1eab26de4 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/compare-verbose.out @@ -0,0 +1,5 @@ +[2024-05-23T19:39:15] DEBUG Command: uw config compare --file-1-path a.nml --file-2-path c.nml --verbose +[2024-05-23T19:39:15] INFO - a.nml +[2024-05-23T19:39:15] INFO + c.nml +[2024-05-23T19:39:15] INFO --------------------------------------------------------------------- +[2024-05-23T19:39:15] INFO values: recipient: - World + None diff --git a/docs/sections/user_guide/cli/tools/config/config.txt b/docs/sections/user_guide/cli/tools/config/config.txt new file mode 120000 index 000000000..a53947000 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/config.txt @@ -0,0 +1 @@ +config.yaml \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/config/config.yaml b/docs/sections/user_guide/cli/tools/config/config.yaml new file mode 100644 index 000000000..9a988da7c --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/config.yaml @@ -0,0 +1,7 @@ +values: + date: '{{ yyyymmdd }}' + empty: + greeting: Hello + message: '{{ ((greeting + " " + recipient + " ") * repeat) | trim }}' + recipient: World + repeat: 1 diff --git a/docs/sections/user_guide/cli/tools/config/flowers.yaml b/docs/sections/user_guide/cli/tools/config/flowers.yaml new file mode 100644 index 000000000..5f2f09637 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/flowers.yaml @@ -0,0 +1,3 @@ +roses: "{{ color1 }}" +violets: "{{ color2 }}" +color1: red diff --git a/docs/sections/user_guide/cli/tools/config/help.cmd b/docs/sections/user_guide/cli/tools/config/help.cmd new file mode 100644 index 000000000..ae9fbbb90 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/help.cmd @@ -0,0 +1 @@ +uw config --help diff --git a/docs/sections/user_guide/cli/tools/config/help.out b/docs/sections/user_guide/cli/tools/config/help.out new file mode 100644 index 000000000..b3e075f75 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/help.out @@ -0,0 +1,18 @@ +usage: uw config [-h] [--version] ACTION ... + +Handle configs + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + ACTION + compare + Compare configs + realize + Realize config + validate + Validate config diff --git a/docs/sections/user_guide/cli/tools/config/realize-combo.cmd b/docs/sections/user_guide/cli/tools/config/realize-combo.cmd new file mode 100644 index 000000000..656b30774 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-combo.cmd @@ -0,0 +1 @@ +cat config.yaml | uw config realize --input-format yaml --update-file update.yaml --output-block values --output-format sh diff --git a/docs/sections/user_guide/cli/tools/config/realize-combo.out b/docs/sections/user_guide/cli/tools/config/realize-combo.out new file mode 100644 index 000000000..bb4702819 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-combo.out @@ -0,0 +1,6 @@ +date=20240105 +empty=None +greeting='Good Night' +message='Good Night Moon Good Night Moon' +recipient=Moon +repeat=2 diff --git a/docs/sections/user_guide/cli/tools/config/realize-depth-mismatch.cmd b/docs/sections/user_guide/cli/tools/config/realize-depth-mismatch.cmd new file mode 100644 index 000000000..7f3755477 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-depth-mismatch.cmd @@ -0,0 +1 @@ +uw config realize --input-file config.yaml --output-format sh diff --git a/docs/sections/user_guide/cli/tools/config/realize-depth-mismatch.out b/docs/sections/user_guide/cli/tools/config/realize-depth-mismatch.out new file mode 100644 index 000000000..e5bc17fda --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-depth-mismatch.out @@ -0,0 +1 @@ +[2024-05-23T19:39:15] ERROR Cannot realize depth-2 config to type-'sh' config diff --git a/docs/sections/user_guide/cli/tools/config/realize-dry-run.cmd b/docs/sections/user_guide/cli/tools/config/realize-dry-run.cmd new file mode 100644 index 000000000..cec2c285f --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-dry-run.cmd @@ -0,0 +1 @@ +uw config realize --input-file config.yaml --update-file update.yaml --output-file realized.yaml --dry-run diff --git a/docs/sections/user_guide/cli/tools/config/realize-dry-run.out b/docs/sections/user_guide/cli/tools/config/realize-dry-run.out new file mode 100644 index 000000000..98ec811a9 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-dry-run.out @@ -0,0 +1,7 @@ +[2024-05-23T19:39:16] INFO values: +[2024-05-23T19:39:16] INFO date: 20240105 +[2024-05-23T19:39:16] INFO empty: null +[2024-05-23T19:39:16] INFO greeting: Good Night +[2024-05-23T19:39:16] INFO message: Good Night Moon Good Night Moon +[2024-05-23T19:39:16] INFO recipient: Moon +[2024-05-23T19:39:16] INFO repeat: 2 diff --git a/docs/sections/user_guide/cli/tools/config/realize-extension-file-bad.cmd b/docs/sections/user_guide/cli/tools/config/realize-extension-file-bad.cmd new file mode 100644 index 000000000..a8517461a --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-extension-file-bad.cmd @@ -0,0 +1 @@ +uw config realize --input-file config.txt --update-file update.yaml --output-format yaml diff --git a/docs/sections/user_guide/cli/tools/config/realize-extension-file-bad.out b/docs/sections/user_guide/cli/tools/config/realize-extension-file-bad.out new file mode 100644 index 000000000..32b1809c0 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-extension-file-bad.out @@ -0,0 +1 @@ +Cannot deduce format of 'config.txt' from unknown extension 'txt' diff --git a/docs/sections/user_guide/cli/tools/config/realize-extension-file-fix.cmd b/docs/sections/user_guide/cli/tools/config/realize-extension-file-fix.cmd new file mode 100644 index 000000000..9089c09e6 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-extension-file-fix.cmd @@ -0,0 +1 @@ +uw config realize --input-file config.txt --update-file update.yaml --output-format yaml --input-format yaml diff --git a/docs/sections/user_guide/cli/tools/config/realize-extension-file-fix.out b/docs/sections/user_guide/cli/tools/config/realize-extension-file-fix.out new file mode 100644 index 000000000..788934c89 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-extension-file-fix.out @@ -0,0 +1,7 @@ +values: + date: 20240105 + empty: null + greeting: Good Night + message: Good Night Moon Good Night Moon + recipient: Moon + repeat: 2 diff --git a/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-bad.cmd b/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-bad.cmd new file mode 100644 index 000000000..cdacab963 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-bad.cmd @@ -0,0 +1 @@ +cat config.yaml | uw config realize --update-file update.yaml --output-format yaml diff --git a/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-bad.out b/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-bad.out new file mode 100644 index 000000000..dc6d2b7cc --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-bad.out @@ -0,0 +1 @@ +Specify --input-format when --input-file is not specified diff --git a/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-fix.cmd b/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-fix.cmd new file mode 100644 index 000000000..bb386ae4f --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-fix.cmd @@ -0,0 +1 @@ +cat config.yaml | uw config realize --update-file update.yaml --output-format yaml --input-format yaml diff --git a/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-fix.out b/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-fix.out new file mode 100644 index 000000000..788934c89 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-extension-stdin-fix.out @@ -0,0 +1,7 @@ +values: + date: 20240105 + empty: null + greeting: Good Night + message: Good Night Moon Good Night Moon + recipient: Moon + repeat: 2 diff --git a/docs/sections/user_guide/cli/tools/config/realize-flowers-noop.cmd b/docs/sections/user_guide/cli/tools/config/realize-flowers-noop.cmd new file mode 100644 index 000000000..23b011fc7 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-flowers-noop.cmd @@ -0,0 +1,2 @@ +uw config realize --input-file flowers.yaml --output-format yaml +echo -e "\nExit status: $?" diff --git a/docs/sections/user_guide/cli/tools/config/realize-flowers-noop.out b/docs/sections/user_guide/cli/tools/config/realize-flowers-noop.out new file mode 100644 index 000000000..cfcda5678 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-flowers-noop.out @@ -0,0 +1,5 @@ +roses: red +violets: '{{ color2 }}' +color1: red + +Exit status: 0 diff --git a/docs/sections/user_guide/cli/tools/config/realize-flowers-total.cmd b/docs/sections/user_guide/cli/tools/config/realize-flowers-total.cmd new file mode 100644 index 000000000..30291c8b7 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-flowers-total.cmd @@ -0,0 +1,2 @@ +uw config realize --input-file flowers.yaml --output-format yaml --total +echo -e "\nExit status: $?" diff --git a/docs/sections/user_guide/cli/tools/config/realize-flowers-total.out b/docs/sections/user_guide/cli/tools/config/realize-flowers-total.out new file mode 100644 index 000000000..be300a143 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-flowers-total.out @@ -0,0 +1,3 @@ +[2024-05-23T19:39:14] ERROR Config could not be realized. Try with --values-needed for details. + +Exit status: 1 diff --git a/docs/sections/user_guide/cli/tools/config/realize-help.cmd b/docs/sections/user_guide/cli/tools/config/realize-help.cmd new file mode 100644 index 000000000..6ecda054d --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-help.cmd @@ -0,0 +1 @@ +uw config realize --help diff --git a/docs/sections/user_guide/cli/tools/config/realize-help.out b/docs/sections/user_guide/cli/tools/config/realize-help.out new file mode 100644 index 000000000..f66089ffd --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-help.out @@ -0,0 +1,40 @@ +usage: uw config realize [-h] [--version] [--input-file PATH] + [--input-format {ini,nml,sh,yaml}] + [--update-file PATH] + [--update-format {ini,nml,sh,yaml}] + [--output-file PATH] + [--output-format {ini,nml,sh,yaml}] + [--output-block KEY[.KEY[.KEY]...]] [--values-needed] + [--total] [--dry-run] [--quiet] [--verbose] + +Realize config + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + --input-file PATH, -i PATH + Path to input file (defaults to stdin) + --input-format {ini,nml,sh,yaml} + Input format + --update-file PATH, -u PATH + Path to update file (defaults to stdin) + --update-format {ini,nml,sh,yaml} + Update format + --output-file PATH, -o PATH + Path to output file (defaults to stdout) + --output-format {ini,nml,sh,yaml} + Output format + --output-block KEY[.KEY[.KEY]...] + Dot-separated path of keys to the block to be output + --values-needed + Print report of values needed to render template + --total + Require rendering of all Jinja2 variables/expressions + --dry-run + Only log info, making no changes + --quiet, -q + Print no logging messages + --verbose, -v + Print all logging messages diff --git a/docs/sections/user_guide/cli/tools/config/realize-roses-noop.cmd b/docs/sections/user_guide/cli/tools/config/realize-roses-noop.cmd new file mode 100644 index 000000000..50d451041 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-roses-noop.cmd @@ -0,0 +1 @@ +uw config realize --input-file roses.yaml --output-format yaml diff --git a/docs/sections/user_guide/cli/tools/config/realize-roses-noop.out b/docs/sections/user_guide/cli/tools/config/realize-roses-noop.out new file mode 100644 index 000000000..de5e3c0c9 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-roses-noop.out @@ -0,0 +1,2 @@ +roses: '{{ color1 }} or {{ color2 }}' +color1: red diff --git a/docs/sections/user_guide/cli/tools/config/realize-stdout.cmd b/docs/sections/user_guide/cli/tools/config/realize-stdout.cmd new file mode 100644 index 000000000..b5494a55a --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-stdout.cmd @@ -0,0 +1 @@ +uw config realize --input-file config.yaml --output-format yaml diff --git a/docs/sections/user_guide/cli/tools/config/realize-stdout.out b/docs/sections/user_guide/cli/tools/config/realize-stdout.out new file mode 100644 index 000000000..c830a2125 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-stdout.out @@ -0,0 +1,7 @@ +values: + date: '{{ yyyymmdd }}' + empty: null + greeting: Hello + message: Hello World + recipient: World + repeat: 1 diff --git a/docs/sections/user_guide/cli/tools/config/realize-update-file-outfile.cmd b/docs/sections/user_guide/cli/tools/config/realize-update-file-outfile.cmd new file mode 100644 index 000000000..49c3e1e8f --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-update-file-outfile.cmd @@ -0,0 +1,3 @@ +rm -f realized.yaml +uw config realize --input-file config.yaml --update-file update.yaml --output-file realized.yaml +cat realized.yaml diff --git a/docs/sections/user_guide/cli/tools/config/realize-update-file-outfile.out b/docs/sections/user_guide/cli/tools/config/realize-update-file-outfile.out new file mode 100644 index 000000000..788934c89 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-update-file-outfile.out @@ -0,0 +1,7 @@ +values: + date: 20240105 + empty: null + greeting: Good Night + message: Good Night Moon Good Night Moon + recipient: Moon + repeat: 2 diff --git a/docs/sections/user_guide/cli/tools/config/realize-update-file.cmd b/docs/sections/user_guide/cli/tools/config/realize-update-file.cmd new file mode 100644 index 000000000..3c7cce156 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-update-file.cmd @@ -0,0 +1 @@ +uw config realize --input-file config.yaml --update-file update.yaml --output-format yaml diff --git a/docs/sections/user_guide/cli/tools/config/realize-update-file.out b/docs/sections/user_guide/cli/tools/config/realize-update-file.out new file mode 100644 index 000000000..788934c89 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-update-file.out @@ -0,0 +1,7 @@ +values: + date: 20240105 + empty: null + greeting: Good Night + message: Good Night Moon Good Night Moon + recipient: Moon + repeat: 2 diff --git a/docs/sections/user_guide/cli/tools/config/realize-update-stdin.cmd b/docs/sections/user_guide/cli/tools/config/realize-update-stdin.cmd new file mode 100644 index 000000000..1441560f4 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-update-stdin.cmd @@ -0,0 +1 @@ +echo "yyyymmdd: 20240520" | uw config realize --input-file config.yaml --update-format yaml --output-format yaml diff --git a/docs/sections/user_guide/cli/tools/config/realize-update-stdin.out b/docs/sections/user_guide/cli/tools/config/realize-update-stdin.out new file mode 100644 index 000000000..24f5eb0ed --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-update-stdin.out @@ -0,0 +1,8 @@ +values: + date: '20240520' + empty: null + greeting: Hello + message: Hello World + recipient: World + repeat: 1 +yyyymmdd: 20240520 diff --git a/docs/sections/user_guide/cli/tools/config/realize-values-needed.cmd b/docs/sections/user_guide/cli/tools/config/realize-values-needed.cmd new file mode 100644 index 000000000..0f7603b1e --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-values-needed.cmd @@ -0,0 +1 @@ +uw config realize --input-file config.yaml --output-format yaml --values-needed diff --git a/docs/sections/user_guide/cli/tools/config/realize-values-needed.out b/docs/sections/user_guide/cli/tools/config/realize-values-needed.out new file mode 100644 index 000000000..6d2008fdd --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-values-needed.out @@ -0,0 +1,12 @@ +[2024-05-23T19:39:17] INFO Keys that are complete: +[2024-05-23T19:39:17] INFO values +[2024-05-23T19:39:17] INFO values.greeting +[2024-05-23T19:39:17] INFO values.message +[2024-05-23T19:39:17] INFO values.recipient +[2024-05-23T19:39:17] INFO values.repeat +[2024-05-23T19:39:17] INFO +[2024-05-23T19:39:17] INFO Keys with unrendered Jinja2 variables/expressions: +[2024-05-23T19:39:17] INFO values.date: {{ yyyymmdd }} +[2024-05-23T19:39:17] INFO +[2024-05-23T19:39:17] INFO Keys that are set to empty: +[2024-05-23T19:39:17] INFO values.empty diff --git a/docs/sections/user_guide/cli/tools/config/realize-verbose.cmd b/docs/sections/user_guide/cli/tools/config/realize-verbose.cmd new file mode 100644 index 000000000..6bea1fefe --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-verbose.cmd @@ -0,0 +1 @@ +echo "{hello: '{{ recipient }}', recipient: world}" | uw config realize --input-format yaml --output-format yaml --verbose diff --git a/docs/sections/user_guide/cli/tools/config/realize-verbose.out b/docs/sections/user_guide/cli/tools/config/realize-verbose.out new file mode 100644 index 000000000..3371e2070 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/realize-verbose.out @@ -0,0 +1,30 @@ +[2024-05-23T19:39:16] DEBUG Command: uw config realize --input-format yaml --output-format yaml --verbose +[2024-05-23T19:39:16] DEBUG Reading input from stdin +[2024-05-23T19:39:16] DEBUG Dereferencing, current value: +[2024-05-23T19:39:16] DEBUG hello: '{{ recipient }}' +[2024-05-23T19:39:16] DEBUG recipient: world +[2024-05-23T19:39:16] DEBUG [dereference] Rendering: {{ recipient }} +[2024-05-23T19:39:16] DEBUG [dereference] Rendered: world +[2024-05-23T19:39:16] DEBUG [dereference] Rendering: hello +[2024-05-23T19:39:16] DEBUG [dereference] Rendered: hello +[2024-05-23T19:39:16] DEBUG [dereference] Rendering: world +[2024-05-23T19:39:16] DEBUG [dereference] Rendered: world +[2024-05-23T19:39:16] DEBUG [dereference] Rendering: recipient +[2024-05-23T19:39:16] DEBUG [dereference] Rendered: recipient +[2024-05-23T19:39:16] DEBUG Dereferencing, current value: +[2024-05-23T19:39:16] DEBUG hello: world +[2024-05-23T19:39:16] DEBUG recipient: world +[2024-05-23T19:39:16] DEBUG [dereference] Rendering: world +[2024-05-23T19:39:16] DEBUG [dereference] Rendered: world +[2024-05-23T19:39:16] DEBUG [dereference] Rendering: hello +[2024-05-23T19:39:16] DEBUG [dereference] Rendered: hello +[2024-05-23T19:39:16] DEBUG [dereference] Rendering: world +[2024-05-23T19:39:16] DEBUG [dereference] Rendered: world +[2024-05-23T19:39:16] DEBUG [dereference] Rendering: recipient +[2024-05-23T19:39:16] DEBUG [dereference] Rendered: recipient +[2024-05-23T19:39:16] DEBUG Dereferencing, final value: +[2024-05-23T19:39:16] DEBUG hello: world +[2024-05-23T19:39:16] DEBUG recipient: world +[2024-05-23T19:39:16] DEBUG Writing output to stdout +hello: world +recipient: world diff --git a/docs/sections/user_guide/cli/tools/config/roses.yaml b/docs/sections/user_guide/cli/tools/config/roses.yaml new file mode 100644 index 000000000..50a423063 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/roses.yaml @@ -0,0 +1,2 @@ +roses: "{{ color1 }} or {{ color2 }}" +color1: red diff --git a/docs/sections/user_guide/cli/tools/config/schema.jsonschema b/docs/sections/user_guide/cli/tools/config/schema.jsonschema new file mode 100644 index 000000000..f346a2117 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/schema.jsonschema @@ -0,0 +1,21 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "values": { + "type": "object", + "properties": { + "greeting": { + "type": "string" + }, + "recipient": { + "type": "string" + } + }, + "required": ["greeting", "recipient"], + "additionalProperties": false + } + }, + "required": ["values"], + "additionalProperties": false +} diff --git a/docs/sections/user_guide/cli/tools/config/update.yaml b/docs/sections/user_guide/cli/tools/config/update.yaml new file mode 100644 index 000000000..e03401b54 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/update.yaml @@ -0,0 +1,5 @@ +values: + date: 20240105 + greeting: Good Night + recipient: Moon + repeat: 2 diff --git a/docs/sections/user_guide/cli/tools/config/validate-fail.cmd b/docs/sections/user_guide/cli/tools/config/validate-fail.cmd new file mode 100644 index 000000000..28b316813 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-fail.cmd @@ -0,0 +1 @@ +uw config validate --schema-file schema.jsonschema --input-file values-bad.yaml diff --git a/docs/sections/user_guide/cli/tools/config/validate-fail.out b/docs/sections/user_guide/cli/tools/config/validate-fail.out new file mode 100644 index 000000000..a581b8ce3 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-fail.out @@ -0,0 +1,3 @@ +[2024-05-23T19:39:17] ERROR 1 UW schema-validation error found +[2024-05-23T19:39:17] ERROR Error at values: +[2024-05-23T19:39:17] ERROR 'recipient' is a required property diff --git a/docs/sections/user_guide/cli/tools/config/validate-help.cmd b/docs/sections/user_guide/cli/tools/config/validate-help.cmd new file mode 100644 index 000000000..e51b4f5c2 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-help.cmd @@ -0,0 +1 @@ +uw config validate --help diff --git a/docs/sections/user_guide/cli/tools/config/validate-help.out b/docs/sections/user_guide/cli/tools/config/validate-help.out new file mode 100644 index 000000000..bc69e8087 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-help.out @@ -0,0 +1,20 @@ +usage: uw config validate --schema-file PATH [-h] [--version] + [--input-file PATH] [--quiet] [--verbose] + +Validate config + +Required arguments: + --schema-file PATH + Path to schema file to use for validation + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + --input-file PATH, -i PATH + Path to input file (defaults to stdin) + --quiet, -q + Print no logging messages + --verbose, -v + Print all logging messages diff --git a/docs/sections/user_guide/cli/tools/config/validate-pass-stdin.cmd b/docs/sections/user_guide/cli/tools/config/validate-pass-stdin.cmd new file mode 100644 index 000000000..db1dc4b72 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-pass-stdin.cmd @@ -0,0 +1 @@ +cat values.yaml | uw config validate --schema-file schema.jsonschema diff --git a/docs/sections/user_guide/cli/tools/config/validate-pass-stdin.out b/docs/sections/user_guide/cli/tools/config/validate-pass-stdin.out new file mode 100644 index 000000000..a760389d0 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-pass-stdin.out @@ -0,0 +1 @@ +[2024-05-23T19:39:15] INFO 0 UW schema-validation errors found diff --git a/docs/sections/user_guide/cli/tools/config/validate-pass.cmd b/docs/sections/user_guide/cli/tools/config/validate-pass.cmd new file mode 100644 index 000000000..49230576c --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-pass.cmd @@ -0,0 +1 @@ +uw config validate --schema-file schema.jsonschema --input-file values.yaml diff --git a/docs/sections/user_guide/cli/tools/config/validate-pass.out b/docs/sections/user_guide/cli/tools/config/validate-pass.out new file mode 100644 index 000000000..efd846fd7 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-pass.out @@ -0,0 +1 @@ +[2024-05-23T19:39:17] INFO 0 UW schema-validation errors found diff --git a/docs/sections/user_guide/cli/tools/config/validate-verbose.cmd b/docs/sections/user_guide/cli/tools/config/validate-verbose.cmd new file mode 100644 index 000000000..c67ec2cfd --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-verbose.cmd @@ -0,0 +1 @@ +uw config validate --schema-file schema.jsonschema --input-file values.yaml --verbose diff --git a/docs/sections/user_guide/cli/tools/config/validate-verbose.out b/docs/sections/user_guide/cli/tools/config/validate-verbose.out new file mode 100644 index 000000000..d1ed3d613 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/validate-verbose.out @@ -0,0 +1,20 @@ +[2024-05-23T19:39:16] DEBUG Command: uw config validate --schema-file schema.jsonschema --input-file values.yaml --verbose +[2024-05-23T19:39:16] DEBUG Dereferencing, current value: +[2024-05-23T19:39:16] DEBUG values: +[2024-05-23T19:39:16] DEBUG greeting: Hello +[2024-05-23T19:39:16] DEBUG recipient: World +[2024-05-23T19:39:16] DEBUG [dereference] Rendering: Hello +[2024-05-23T19:39:17] DEBUG [dereference] Rendered: Hello +[2024-05-23T19:39:17] DEBUG [dereference] Rendering: greeting +[2024-05-23T19:39:17] DEBUG [dereference] Rendered: greeting +[2024-05-23T19:39:17] DEBUG [dereference] Rendering: World +[2024-05-23T19:39:17] DEBUG [dereference] Rendered: World +[2024-05-23T19:39:17] DEBUG [dereference] Rendering: recipient +[2024-05-23T19:39:17] DEBUG [dereference] Rendered: recipient +[2024-05-23T19:39:17] DEBUG [dereference] Rendering: values +[2024-05-23T19:39:17] DEBUG [dereference] Rendered: values +[2024-05-23T19:39:17] DEBUG Dereferencing, final value: +[2024-05-23T19:39:17] DEBUG values: +[2024-05-23T19:39:17] DEBUG greeting: Hello +[2024-05-23T19:39:17] DEBUG recipient: World +[2024-05-23T19:39:17] INFO 0 UW schema-validation errors found diff --git a/docs/sections/user_guide/cli/tools/config/values-bad.yaml b/docs/sections/user_guide/cli/tools/config/values-bad.yaml new file mode 100644 index 000000000..2b3f57990 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/values-bad.yaml @@ -0,0 +1,2 @@ +values: + greeting: Hello diff --git a/docs/sections/user_guide/cli/tools/config/values.yaml b/docs/sections/user_guide/cli/tools/config/values.yaml new file mode 100644 index 000000000..ee1dbeef7 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/config/values.yaml @@ -0,0 +1,3 @@ +values: + greeting: Hello + recipient: World diff --git a/docs/sections/user_guide/cli/tools/file.rst b/docs/sections/user_guide/cli/tools/file.rst index bfe7b28db..b7884ff10 100644 --- a/docs/sections/user_guide/cli/tools/file.rst +++ b/docs/sections/user_guide/cli/tools/file.rst @@ -3,25 +3,10 @@ The ``uw`` mode for handling filesystem files. -.. code-block:: text - - $ uw file --help - usage: uw file [-h] [--version] ACTION ... - - Handle files - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - ACTION - copy - Copy files - link - Link files +.. literalinclude:: file/help.cmd + :emphasize-lines: 1 +.. literalinclude:: file/help.out + :language: text .. _cli_file_copy_examples: @@ -30,75 +15,22 @@ The ``uw`` mode for handling filesystem files. The ``copy`` action stages files in a target directory by copying files. Any ``KEY`` positional arguments are used to navigate, in the order given, from the top of the config to the :ref:`file block `. -.. code-block:: text - - $ uw file copy --help - usage: uw file copy --target-dir PATH [-h] [--version] [--config-file PATH] [--dry-run] [--quiet] - [--verbose] - [KEY ...] - - Copy files - - Required arguments: - --target-dir PATH - Path to target directory - - 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 - --dry-run - Only log info, making no changes - --quiet, -q - Print no logging messages - --verbose, -v - Print all logging messages - KEY - YAML key leading to file dst/src block +.. literalinclude:: file/copy-help.cmd + :emphasize-lines: 1 +.. literalinclude:: file/copy-help.out + :language: text Examples ^^^^^^^^ -Given ``config.yaml`` containing - -.. code-block:: yaml - - config: - files: - foo: /path/to/foo - subdir/bar: /path/to/bar +Given ``copy-config.yaml`` containing -.. code-block:: text - - $ uw file copy --target-dir /tmp/target --config-file config.yaml config files - [2024-03-14T19:00:02] INFO Validating config against internal schema files-to-stage - [2024-03-14T19:00:02] INFO 0 UW schema-validation errors found - [2024-03-14T19:00:02] INFO File copies: Initial state: Pending - [2024-03-14T19:00:02] INFO File copies: Checking requirements - [2024-03-14T19:00:02] INFO Copy /tmp/source/foo -> /tmp/target/foo: Initial state: Pending - [2024-03-14T19:00:02] INFO Copy /tmp/source/foo -> /tmp/target/foo: Checking requirements - [2024-03-14T19:00:02] INFO Copy /tmp/source/foo -> /tmp/target/foo: Requirement(s) ready - [2024-03-14T19:00:02] INFO Copy /tmp/source/foo -> /tmp/target/foo: Executing - [2024-03-14T19:00:02] INFO Copy /tmp/source/foo -> /tmp/target/foo: Final state: Ready - [2024-03-14T19:00:02] INFO Copy /tmp/source/bar -> /tmp/target/subdir/bar: Initial state: Pending - [2024-03-14T19:00:02] INFO Copy /tmp/source/bar -> /tmp/target/subdir/bar: Checking requirements - [2024-03-14T19:00:02] INFO Copy /tmp/source/bar -> /tmp/target/subdir/bar: Requirement(s) ready - [2024-03-14T19:00:02] INFO Copy /tmp/source/bar -> /tmp/target/subdir/bar: Executing - [2024-03-14T19:00:02] INFO Copy /tmp/source/bar -> /tmp/target/subdir/bar: Final state: Ready - [2024-03-14T19:00:02] INFO File copies: Final state: Ready - -After executing this command: - -.. code-block:: text - - $ tree /tmp/target - /tmp/target - ├── foo - └── subdir - └── bar +.. literalinclude:: file/copy-config.yaml + :language: yaml +.. literalinclude:: file/copy-exec.cmd + :emphasize-lines: 2 +.. literalinclude:: file/copy-exec.out + :language: text Here, ``foo`` and ``bar`` are copies of their respective source files. @@ -109,74 +41,21 @@ Here, ``foo`` and ``bar`` are copies of their respective source files. The ``link`` action stages files in a target directory by linking files, directories, or other symbolic links. Any ``KEY`` positional arguments are used to navigate, in the order given, from the top of the config to the :ref:`file block `. -.. code-block:: text - - $ uw file link --help - usage: uw file link --target-dir PATH [-h] [--version] [--config-file PATH] [--dry-run] [--quiet] - [--verbose] - [KEY ...] - - Link files - - Required arguments: - --target-dir PATH - Path to target directory - - 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 - --dry-run - Only log info, making no changes - --quiet, -q - Print no logging messages - --verbose, -v - Print all logging messages - KEY - YAML key leading to file dst/src block +.. literalinclude:: file/link-help.cmd + :emphasize-lines: 1 +.. literalinclude:: file/link-help.out + :language: text Examples ^^^^^^^^ -Given ``config.yaml`` containing - -.. code-block:: yaml - - config: - files: - foo: /path/to/foo - subdir/bar: /path/to/bar - -.. code-block:: text - - $ uw file link --target-dir /tmp/target --config-file config.yaml config files - [2024-03-14T19:02:49] INFO Validating config against internal schema files-to-stage - [2024-03-14T19:02:49] INFO 0 UW schema-validation errors found - [2024-03-14T19:02:49] INFO File links: Initial state: Pending - [2024-03-14T19:02:49] INFO File links: Checking requirements - [2024-03-14T19:02:49] INFO Link /tmp/target/foo -> /tmp/source/foo: Initial state: Pending - [2024-03-14T19:02:49] INFO Link /tmp/target/foo -> /tmp/source/foo: Checking requirements - [2024-03-14T19:02:49] INFO Link /tmp/target/foo -> /tmp/source/foo: Requirement(s) ready - [2024-03-14T19:02:49] INFO Link /tmp/target/foo -> /tmp/source/foo: Executing - [2024-03-14T19:02:49] INFO Link /tmp/target/foo -> /tmp/source/foo: Final state: Ready - [2024-03-14T19:02:49] INFO Link /tmp/target/subdir/bar -> /tmp/source/bar: Initial state: Pending - [2024-03-14T19:02:49] INFO Link /tmp/target/subdir/bar -> /tmp/source/bar: Checking requirements - [2024-03-14T19:02:49] INFO Link /tmp/target/subdir/bar -> /tmp/source/bar: Requirement(s) ready - [2024-03-14T19:02:49] INFO Link /tmp/target/subdir/bar -> /tmp/source/bar: Executing - [2024-03-14T19:02:49] INFO Link /tmp/target/subdir/bar -> /tmp/source/bar: Final state: Ready - [2024-03-14T19:02:49] INFO File links: Final state: Ready - -After executing this command: - -.. code-block:: text - - $ tree /tmp/target - /tmp/target - ├── foo -> /tmp/source/foo - └── subdir - └── bar -> /tmp/source/bar +Given ``link-config.yaml`` containing + +.. literalinclude:: file/link-config.yaml + :language: yaml +.. literalinclude:: file/link-exec.cmd + :emphasize-lines: 2 +.. literalinclude:: file/link-exec.out + :language: text Here, ``foo`` and ``bar`` are symbolic links. diff --git a/docs/sections/user_guide/cli/tools/file/.gitignore b/docs/sections/user_guide/cli/tools/file/.gitignore new file mode 100644 index 000000000..c14405037 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/.gitignore @@ -0,0 +1,2 @@ +dst-copy +dst-link diff --git a/docs/sections/user_guide/cli/tools/file/Makefile b/docs/sections/user_guide/cli/tools/file/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/file/copy-config.yaml b/docs/sections/user_guide/cli/tools/file/copy-config.yaml new file mode 100644 index 000000000..17c45a3e6 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/copy-config.yaml @@ -0,0 +1,4 @@ +config: + files: + foo: src/foo + subdir/bar: src/bar diff --git a/docs/sections/user_guide/cli/tools/file/copy-exec.cmd b/docs/sections/user_guide/cli/tools/file/copy-exec.cmd new file mode 100644 index 000000000..d1abc7599 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/copy-exec.cmd @@ -0,0 +1,4 @@ +rm -rf dst-copy +uw file copy --target-dir dst-copy --config-file copy-config.yaml config files +echo +tree dst-copy diff --git a/docs/sections/user_guide/cli/tools/file/copy-exec.out b/docs/sections/user_guide/cli/tools/file/copy-exec.out new file mode 100644 index 000000000..855a149df --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/copy-exec.out @@ -0,0 +1,22 @@ +[2024-05-23T19:39:15] INFO Validating config against internal schema files-to-stage +[2024-05-23T19:39:15] INFO 0 UW schema-validation errors found +[2024-05-23T19:39:15] INFO File copies: Initial state: Pending +[2024-05-23T19:39:15] INFO File copies: Checking requirements +[2024-05-23T19:39:15] INFO Copy src/foo -> dst-copy/foo: Initial state: Pending +[2024-05-23T19:39:15] INFO Copy src/foo -> dst-copy/foo: Checking requirements +[2024-05-23T19:39:15] INFO Copy src/foo -> dst-copy/foo: Requirement(s) ready +[2024-05-23T19:39:15] INFO Copy src/foo -> dst-copy/foo: Executing +[2024-05-23T19:39:15] INFO Copy src/foo -> dst-copy/foo: Final state: Ready +[2024-05-23T19:39:15] INFO Copy src/bar -> dst-copy/subdir/bar: Initial state: Pending +[2024-05-23T19:39:15] INFO Copy src/bar -> dst-copy/subdir/bar: Checking requirements +[2024-05-23T19:39:15] INFO Copy src/bar -> dst-copy/subdir/bar: Requirement(s) ready +[2024-05-23T19:39:15] INFO Copy src/bar -> dst-copy/subdir/bar: Executing +[2024-05-23T19:39:15] INFO Copy src/bar -> dst-copy/subdir/bar: Final state: Ready +[2024-05-23T19:39:15] INFO File copies: Final state: Ready + +dst-copy +├── foo +└── subdir + └── bar + +2 directories, 2 files diff --git a/docs/sections/user_guide/cli/tools/file/copy-help.cmd b/docs/sections/user_guide/cli/tools/file/copy-help.cmd new file mode 100644 index 000000000..5a5188caa --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/copy-help.cmd @@ -0,0 +1 @@ +uw file copy --help diff --git a/docs/sections/user_guide/cli/tools/file/copy-help.out b/docs/sections/user_guide/cli/tools/file/copy-help.out new file mode 100644 index 000000000..27b6a053b --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/copy-help.out @@ -0,0 +1,25 @@ +usage: uw file copy --target-dir PATH [-h] [--version] [--config-file PATH] + [--dry-run] [--quiet] [--verbose] + [KEY ...] + +Copy files + +Required arguments: + --target-dir PATH + Path to target directory + +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) + --dry-run + Only log info, making no changes + --quiet, -q + Print no logging messages + --verbose, -v + Print all logging messages + KEY + YAML key leading to file dst/src block diff --git a/docs/sections/user_guide/cli/tools/file/help.cmd b/docs/sections/user_guide/cli/tools/file/help.cmd new file mode 100644 index 000000000..e89f12e45 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/help.cmd @@ -0,0 +1 @@ +uw file --help diff --git a/docs/sections/user_guide/cli/tools/file/help.out b/docs/sections/user_guide/cli/tools/file/help.out new file mode 100644 index 000000000..70252750d --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/help.out @@ -0,0 +1,16 @@ +usage: uw file [-h] [--version] ACTION ... + +Handle files + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + ACTION + copy + Copy files + link + Link files diff --git a/docs/sections/user_guide/cli/tools/file/link-config.yaml b/docs/sections/user_guide/cli/tools/file/link-config.yaml new file mode 100644 index 000000000..17c45a3e6 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/link-config.yaml @@ -0,0 +1,4 @@ +config: + files: + foo: src/foo + subdir/bar: src/bar diff --git a/docs/sections/user_guide/cli/tools/file/link-exec.cmd b/docs/sections/user_guide/cli/tools/file/link-exec.cmd new file mode 100644 index 000000000..f9c4328c2 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/link-exec.cmd @@ -0,0 +1,4 @@ +rm -rf dst-link +uw file link --target-dir dst-link --config-file link-config.yaml config files +echo +tree dst-link diff --git a/docs/sections/user_guide/cli/tools/file/link-exec.out b/docs/sections/user_guide/cli/tools/file/link-exec.out new file mode 100644 index 000000000..ae6fb2df1 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/link-exec.out @@ -0,0 +1,22 @@ +[2024-05-23T19:39:16] INFO Validating config against internal schema files-to-stage +[2024-05-23T19:39:16] INFO 0 UW schema-validation errors found +[2024-05-23T19:39:16] INFO File links: Initial state: Pending +[2024-05-23T19:39:16] INFO File links: Checking requirements +[2024-05-23T19:39:16] INFO Link dst-link/foo -> src/foo: Initial state: Pending +[2024-05-23T19:39:16] INFO Link dst-link/foo -> src/foo: Checking requirements +[2024-05-23T19:39:16] INFO Link dst-link/foo -> src/foo: Requirement(s) ready +[2024-05-23T19:39:16] INFO Link dst-link/foo -> src/foo: Executing +[2024-05-23T19:39:16] INFO Link dst-link/foo -> src/foo: Final state: Ready +[2024-05-23T19:39:16] INFO Link dst-link/subdir/bar -> src/bar: Initial state: Pending +[2024-05-23T19:39:16] INFO Link dst-link/subdir/bar -> src/bar: Checking requirements +[2024-05-23T19:39:16] INFO Link dst-link/subdir/bar -> src/bar: Requirement(s) ready +[2024-05-23T19:39:16] INFO Link dst-link/subdir/bar -> src/bar: Executing +[2024-05-23T19:39:16] INFO Link dst-link/subdir/bar -> src/bar: Final state: Ready +[2024-05-23T19:39:16] INFO File links: Final state: Ready + +dst-link +├── foo -> ../src/foo +└── subdir + └── bar -> ../../src/bar + +2 directories, 2 files diff --git a/docs/sections/user_guide/cli/tools/file/link-help.cmd b/docs/sections/user_guide/cli/tools/file/link-help.cmd new file mode 100644 index 000000000..a3ce9a824 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/link-help.cmd @@ -0,0 +1 @@ +uw file link --help diff --git a/docs/sections/user_guide/cli/tools/file/link-help.out b/docs/sections/user_guide/cli/tools/file/link-help.out new file mode 100644 index 000000000..5b6d7c9b3 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/link-help.out @@ -0,0 +1,25 @@ +usage: uw file link --target-dir PATH [-h] [--version] [--config-file PATH] + [--dry-run] [--quiet] [--verbose] + [KEY ...] + +Link files + +Required arguments: + --target-dir PATH + Path to target directory + +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) + --dry-run + Only log info, making no changes + --quiet, -q + Print no logging messages + --verbose, -v + Print all logging messages + KEY + YAML key leading to file dst/src block diff --git a/docs/sections/user_guide/cli/tools/file/src/bar b/docs/sections/user_guide/cli/tools/file/src/bar new file mode 100644 index 000000000..5716ca598 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/src/bar @@ -0,0 +1 @@ +bar diff --git a/docs/sections/user_guide/cli/tools/file/src/foo b/docs/sections/user_guide/cli/tools/file/src/foo new file mode 100644 index 000000000..257cc5642 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/file/src/foo @@ -0,0 +1 @@ +foo diff --git a/docs/sections/user_guide/cli/tools/rocoto.rst b/docs/sections/user_guide/cli/tools/rocoto.rst index 8a17f7425..1154e68a7 100644 --- a/docs/sections/user_guide/cli/tools/rocoto.rst +++ b/docs/sections/user_guide/cli/tools/rocoto.rst @@ -3,25 +3,11 @@ The ``uw`` mode for realizing and validating Rocoto XML documents. -.. code-block:: text - - $ uw rocoto --help - usage: uw rocoto [-h] [--version] ACTION ... - - Realize and validate Rocoto XML Documents - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - ACTION - realize - Realize a Rocoto XML workflow document - validate - Validate Rocoto XML +.. literalinclude:: rocoto/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: rocoto/help.out + :language: text .. _cli_rocoto_realize_examples: @@ -32,342 +18,99 @@ In ``uw`` terminology, to ``realize`` a configuration file is to transform it fr More information about the structured UW YAML file for Rocoto can be found :any:`here`. -.. code-block:: text - - $ uw rocoto realize --help - usage: uw rocoto realize [-h] [--version] [--config-file PATH] [--output-file PATH] [--quiet] - [--verbose] - - Realize a Rocoto XML workflow document - - 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) - --output-file PATH, -o PATH - Path to output file (defaults to stdout) - --quiet, -q - Print no logging messages - --verbose, -v - Print all logging messages +.. literalinclude:: rocoto/realize-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: rocoto/realize-help.out + :language: text Examples ^^^^^^^^ -The examples in this section use a UW YAML file called ``rocoto.yaml`` with the following contents: - -.. code-block:: python - - workflow: - attrs: - realtime: false - scheduler: slurm - cycledef: - - attrs: - group: howdy - spec: 202209290000 202209300000 06:00:00 - entities: - ACCOUNT: myaccount - FOO: test.log - log: /some/path/to/&FOO; - tasks: - task_hello: - attrs: - cycledefs: howdy - account: "&ACCOUNT;" - command: "echo hello $person" - jobname: hello - nodes: 1:ppn=1 - walltime: 00:01:00 - envars: - person: siri +The examples in this section use a UW YAML file ``rocoto.yaml`` with contents: + +.. literalinclude:: rocoto/rocoto.yaml + :language: yaml * To realize a UW YAML input file to ``stdout`` in Rocoto XML format: - .. code-block:: xml - - $ uw rocoto realize --config-file rocoto.yaml - [2024-01-02T13:41:25] INFO 0 UW schema-validation errors found - [2024-01-02T13:41:25] INFO 0 Rocoto validation errors found - - - - ]> - - 202209290000 202209300000 06:00:00 - /some/path/to/&FOO; - - &ACCOUNT; - 1:ppn=1 - 00:01:00 - echo hello $person - hello - - person - siri - - - + .. literalinclude:: rocoto/realize-exec-stdout.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: rocoto/realize-exec-stdout.out + :language: xml * To realize a UW YAML input file to a file named ``rocoto.xml``: - .. code-block:: text - - $ uw rocoto realize --config-file rocoto.yaml --output-file rocoto.xml - [2024-01-02T13:45:46] INFO 0 UW schema-validation errors found - [2024-01-02T13:45:46] INFO 0 Rocoto validation errors found - - The content of ``rocoto.xml``: - - .. code-block:: xml - - - - - ]> - - 202209290000 202209300000 06:00:00 - /some/path/to/&FOO; - - &ACCOUNT; - 1:ppn=1 - 00:01:00 - echo hello $person - hello - - person - siri - - - + .. literalinclude:: rocoto/realize-exec-file.cmd + :language: text + :emphasize-lines: 2 + .. literalinclude:: rocoto/realize-exec-file.out + :language: text * To read the UW YAML from ``stdin`` and write the XML to ``stdout``: - .. code-block:: xml - - $ cat rocoto.yaml | uw rocoto realize - [2024-01-02T14:09:08] INFO 0 UW schema-validation errors found - [2024-01-02T14:09:08] INFO 0 Rocoto validation errors found - - - - ]> - - 202209290000 202209300000 06:00:00 - /some/path/to/&FOO; - - &ACCOUNT; - 1:ppn=1 - 00:01:00 - echo hello $person - hello - - person - siri - - - - -* To realize a UW YAML input file to a file named ``rocoto.xml`` in quiet mode: - - .. code-block:: text - - $ uw rocoto realize --config-file rocoto.yaml --output-file rocoto.xml -q - $ - - The contents of ``rocoto.xml`` are unchanged from the previous example. - -* To realize a UW YAML file to a file named ``rocoto.xml`` with verbose log output: - - .. note:: This output has been shortened for demonstration purposes. - - .. code-block:: text - - $ uw rocoto realize --config-file rocoto.yaml --output-file rocoto.xml -v - [2024-01-02T14:00:01] DEBUG Command: uw rocoto realize --config-file rocoto.yaml --output-file rocoto.xml -v - [2024-01-02T14:00:01] DEBUG Dereferencing, initial value: {'workflow': {'attrs': {'realtime': ... - [2024-01-02T14:00:01] DEBUG Rendering: {'workflow': {'attrs': {'realtime': ... - [2024-01-02T14:00:01] DEBUG Rendering: {'attrs': {'realtime': False, 'scheduler': ... - [2024-01-02T14:00:01] DEBUG Rendering: {'realtime': False, 'scheduler': 'slurm'} - [2024-01-02T14:00:01] DEBUG Rendering: False - [2024-01-02T14:00:01] DEBUG Rendered: False - [2024-01-02T14:00:01] DEBUG Rendering: slurm - ... - [2024-01-02T14:00:01] DEBUG Rendering: {'person': 'siri'} - [2024-01-02T14:00:01] DEBUG Rendering: siri - [2024-01-02T14:00:01] INFO 0 UW schema-validation errors found - [2024-01-02T14:00:01] INFO 0 Rocoto validation errors found + .. literalinclude:: rocoto/realize-exec-stdin-stdout.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: rocoto/realize-exec-stdin-stdout.out + :language: xml + +* To see verbose log output (Rocoto XML and some output elided for brevity): + + .. literalinclude:: rocoto/realize-exec-stdout-verbose.cmd + :language: text + :emphasize-lines: 2 + .. literalinclude:: rocoto/realize-exec-stdout-verbose.out + :language: xml .. _cli_rocoto_validate_examples: ``validate`` ------------ -.. code-block:: text - - $ uw rocoto validate --help - usage: uw rocoto validate [-h] [--version] [--input-file PATH] [--quiet] [--verbose] - - Validate Rocoto XML - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - --input-file PATH, -i PATH - Path to input file (defaults to stdin) - --quiet, -q - Print no logging messages - --verbose, -v - Print all logging messages +.. literalinclude:: rocoto/validate-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: rocoto/validate-help.out + :language: text Examples ^^^^^^^^ -The examples in this section use a Rocoto XML file called ``rocoto.xml`` with the following content: +The examples in this section use a Rocoto XML file ``rocoto-good.xml`` with contents: -.. code-block:: xml - :linenos: +.. literalinclude:: rocoto/rocoto-good.xml + :language: xml - - - - ]> - - 202209290000 202209300000 06:00:00 - /some/path/to/&FOO; - - &ACCOUNT; - 1:ppn=1 - 00:01:00 - echo hello $person - hello - - person - siri - - - +* To validate XML from ``stdin``: -* To validate an XML from ``stdin``: + .. literalinclude:: rocoto/validate-good-stdin.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: rocoto/validate-good-stdin.out + :language: text - .. code-block:: text +* To validate XML from file ``rocoto-good.xml``: - $ cat rocoto.xml | uw rocoto validate - [2024-01-02T14:18:46] INFO 0 Rocoto validation errors found + .. literalinclude:: rocoto/validate-good-file.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: rocoto/validate-good-file.out + :language: text -* To validate an XML from file ``rocoto.xml``: +* When the XML is invalid: - .. code-block:: text + In this example, the ```` line was removed from ``rocoto-good.xml`` to create ``rocoto-bad.xml``. - $ uw rocoto validate --input-file rocoto.xml - [2024-01-02T14:18:46] INFO 0 Rocoto validation errors found + .. literalinclude:: rocoto/validate-bad-file.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: rocoto/validate-bad-file.out + :language: text -* When the XML is invalid: + To decode the three ``ERROR:RELAXNGV`` messages, it is easiest to read from the bottom up. They say: - In this example, the ```` line was removed from the XML. - - .. code-block:: text - - $ uw rocoto validate --input-file rocoto.xml - [2024-01-10T21:54:51] ERROR 3 Rocoto validation errors found - [2024-01-10T21:54:51] ERROR :9:0:ERROR:RELAXNGV:RELAXNG_ERR_NOELEM: Expecting an element command, got nothing - [2024-01-10T21:54:51] ERROR :9:0:ERROR:RELAXNGV:RELAXNG_ERR_INTERSEQ: Invalid sequence in interleave - [2024-01-10T21:54:51] ERROR :9:0:ERROR:RELAXNGV:RELAXNG_ERR_CONTENTVALID: Element task failed to validate content - [2024-01-10T21:54:51] ERROR Invalid Rocoto XML: - [2024-01-10T21:54:51] ERROR 1 - [2024-01-10T21:54:51] ERROR 2 - [2024-01-10T21:54:51] ERROR 4 - [2024-01-10T21:54:51] ERROR 5 ]> - [2024-01-10T21:54:51] ERROR 6 - [2024-01-10T21:54:51] ERROR 7 202209290000 202209300000 06:00:00 - [2024-01-10T21:54:51] ERROR 8 /some/path/to/&FOO; - [2024-01-10T21:54:51] ERROR 9 - [2024-01-10T21:54:51] ERROR 10 &ACCOUNT; - [2024-01-10T21:54:51] ERROR 11 1:ppn=1 - [2024-01-10T21:54:51] ERROR 12 00:01:00 - [2024-01-10T21:54:51] ERROR 13 hello - [2024-01-10T21:54:51] ERROR 14 - [2024-01-10T21:54:51] ERROR 15 person - [2024-01-10T21:54:51] ERROR 16 siri - [2024-01-10T21:54:51] ERROR 17 - [2024-01-10T21:54:51] ERROR 18 - [2024-01-10T21:54:51] ERROR 19 - - To decode this type of output, it is easiest to interpret it from the bottom up. It says: - - * The task starting at Line 9 has invalid content. - * There was an invalid sequence. - * It was expecting a ```` element, but there wasn't one. - - In the following example, an empty ```` element was added at the end of the task: - - .. code-block:: xml - :linenos: - - - - - ]> - - 202209290000 202209300000 06:00:00 - /some/path/to/&FOO; - - &ACCOUNT; - 1:ppn=1 - 00:01:00 - echo hello $person - hello - - person - siri - - - - - - - .. code-block:: text - - $ uw rocoto validate --input-file rocoto.xml - [2024-01-10T21:56:14] ERROR 2 Rocoto validation errors found - [2024-01-10T21:56:14] ERROR :0:0:ERROR:RELAXNGV:RELAXNG_ERR_INTEREXTRA: Extra element dependency in interleave - [2024-01-10T21:56:14] ERROR :9:0:ERROR:RELAXNGV:RELAXNG_ERR_CONTENTVALID: Element task failed to validate content - [2024-01-10T21:56:14] ERROR Invalid Rocoto XML: - [2024-01-10T21:56:14] ERROR 1 - [2024-01-10T21:56:14] ERROR 2 - [2024-01-10T21:56:14] ERROR 4 - [2024-01-10T21:56:14] ERROR 5 ]> - [2024-01-10T21:56:14] ERROR 6 - [2024-01-10T21:56:14] ERROR 7 202209290000 202209300000 06:00:00 - [2024-01-10T21:56:14] ERROR 8 /some/path/to/&FOO; - [2024-01-10T21:56:14] ERROR 9 - [2024-01-10T21:56:14] ERROR 10 &ACCOUNT; - [2024-01-10T21:56:14] ERROR 11 1:ppn=1 - [2024-01-10T21:56:14] ERROR 12 00:01:00 - [2024-01-10T21:56:14] ERROR 13 echo hello $person - [2024-01-10T21:56:14] ERROR 14 hello - [2024-01-10T21:56:14] ERROR 15 - [2024-01-10T21:56:14] ERROR 16 person - [2024-01-10T21:56:14] ERROR 17 siri - [2024-01-10T21:56:14] ERROR 18 - [2024-01-10T21:56:14] ERROR 19 - [2024-01-10T21:56:14] ERROR 20 - [2024-01-10T21:56:14] ERROR 21 - [2024-01-10T21:56:14] ERROR 22 - - Once again, interpreting from the bottom: - - * The content of the task starting at Line 9 is not valid. - * There is an extra element ```` in the task. + * At line 9 column 0 (i.e. ``:9:0``), the element (i.e. ````) failed to validate. + * The sequence of interleaved elements under ```` was invalid. + * A ```` element was expected, but it wasn't found. diff --git a/docs/sections/user_guide/cli/tools/rocoto/.gitignore b/docs/sections/user_guide/cli/tools/rocoto/.gitignore new file mode 100644 index 000000000..0765e6530 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/.gitignore @@ -0,0 +1,2 @@ +rocoto.log +rocoto.xml diff --git a/docs/sections/user_guide/cli/tools/rocoto/Makefile b/docs/sections/user_guide/cli/tools/rocoto/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/rocoto/help.cmd b/docs/sections/user_guide/cli/tools/rocoto/help.cmd new file mode 100644 index 000000000..0c67338aa --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/help.cmd @@ -0,0 +1 @@ +uw rocoto --help diff --git a/docs/sections/user_guide/cli/tools/rocoto/help.out b/docs/sections/user_guide/cli/tools/rocoto/help.out new file mode 100644 index 000000000..7b066c847 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/help.out @@ -0,0 +1,16 @@ +usage: uw rocoto [-h] [--version] ACTION ... + +Realize and validate Rocoto XML documents + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + ACTION + realize + Realize a Rocoto XML workflow document + validate + Validate Rocoto XML diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-exec-file.cmd b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-file.cmd new file mode 100644 index 000000000..8d886ac7a --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-file.cmd @@ -0,0 +1,4 @@ +rm -f rocoto.xml +uw rocoto realize --config-file rocoto.yaml --output-file rocoto.xml +echo +cat rocoto.xml diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-exec-file.out b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-file.out new file mode 100644 index 000000000..8a5125f26 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-file.out @@ -0,0 +1,23 @@ +[2024-05-23T19:39:16] INFO 0 UW schema-validation errors found +[2024-05-23T19:39:16] INFO 0 Rocoto validation errors found + + + + +]> + + 202209290000 202209300000 06:00:00 + /some/path/to/&FOO; + + &ACCOUNT; + 1:ppn=1 + 00:01:00 + echo hello $person + hello + + person + siri + + + diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdin-stdout.cmd b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdin-stdout.cmd new file mode 100644 index 000000000..7927ea813 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdin-stdout.cmd @@ -0,0 +1 @@ +cat rocoto.yaml | uw rocoto realize diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdin-stdout.out b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdin-stdout.out new file mode 100644 index 000000000..b1a091c82 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdin-stdout.out @@ -0,0 +1,22 @@ +[2024-05-23T19:39:16] INFO 0 UW schema-validation errors found +[2024-05-23T19:39:16] INFO 0 Rocoto validation errors found + + + +]> + + 202209290000 202209300000 06:00:00 + /some/path/to/&FOO; + + &ACCOUNT; + 1:ppn=1 + 00:01:00 + echo hello $person + hello + + person + siri + + + diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout-verbose.cmd b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout-verbose.cmd new file mode 100644 index 000000000..a21224173 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout-verbose.cmd @@ -0,0 +1,5 @@ +rm -f rocoto.log +uw rocoto realize --config-file rocoto.yaml --verbose >/dev/null 2>rocoto.log +head -n10 rocoto.log +echo ... +tail -n10 rocoto.log diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout-verbose.out b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout-verbose.out new file mode 100644 index 000000000..d04532f14 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout-verbose.out @@ -0,0 +1,21 @@ +[2024-05-23T19:39:16] DEBUG Command: uw rocoto realize --config-file rocoto.yaml --verbose +[2024-05-23T19:39:16] DEBUG Dereferencing, current value: +[2024-05-23T19:39:16] DEBUG workflow: +[2024-05-23T19:39:16] DEBUG attrs: +[2024-05-23T19:39:16] DEBUG realtime: false +[2024-05-23T19:39:16] DEBUG scheduler: slurm +[2024-05-23T19:39:16] DEBUG cycledef: +[2024-05-23T19:39:16] DEBUG - attrs: +[2024-05-23T19:39:16] DEBUG group: howdy +[2024-05-23T19:39:16] DEBUG spec: 202209290000 202209300000 06:00:00 +... +[2024-05-23T19:39:16] DEBUG account: '&ACCOUNT;' +[2024-05-23T19:39:16] DEBUG attrs: +[2024-05-23T19:39:16] DEBUG cycledefs: howdy +[2024-05-23T19:39:16] DEBUG command: echo hello $person +[2024-05-23T19:39:16] DEBUG envars: +[2024-05-23T19:39:16] DEBUG person: siri +[2024-05-23T19:39:16] DEBUG jobname: hello +[2024-05-23T19:39:16] DEBUG nodes: 1:ppn=1 +[2024-05-23T19:39:16] DEBUG walltime: 00:01:00 +[2024-05-23T19:39:16] INFO 0 Rocoto validation errors found diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout.cmd b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout.cmd new file mode 100644 index 000000000..277b8a2ba --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout.cmd @@ -0,0 +1 @@ +uw rocoto realize --config-file rocoto.yaml diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout.out b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout.out new file mode 100644 index 000000000..b1a091c82 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-exec-stdout.out @@ -0,0 +1,22 @@ +[2024-05-23T19:39:16] INFO 0 UW schema-validation errors found +[2024-05-23T19:39:16] INFO 0 Rocoto validation errors found + + + +]> + + 202209290000 202209300000 06:00:00 + /some/path/to/&FOO; + + &ACCOUNT; + 1:ppn=1 + 00:01:00 + echo hello $person + hello + + person + siri + + + diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-help.cmd b/docs/sections/user_guide/cli/tools/rocoto/realize-help.cmd new file mode 100644 index 000000000..d6d69c1c8 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-help.cmd @@ -0,0 +1 @@ +uw rocoto realize --help diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-help.out b/docs/sections/user_guide/cli/tools/rocoto/realize-help.out new file mode 100644 index 000000000..25a08e3af --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/realize-help.out @@ -0,0 +1,18 @@ +usage: uw rocoto realize [-h] [--version] [--config-file PATH] + [--output-file PATH] [--quiet] [--verbose] + +Realize a Rocoto XML workflow document + +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) + --output-file PATH, -o PATH + Path to output file (defaults to stdout) + --quiet, -q + Print no logging messages + --verbose, -v + Print all logging messages diff --git a/docs/sections/user_guide/cli/tools/rocoto/rocoto-bad.xml b/docs/sections/user_guide/cli/tools/rocoto/rocoto-bad.xml new file mode 100644 index 000000000..aa326c699 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/rocoto-bad.xml @@ -0,0 +1,19 @@ + + + +]> + + 202209290000 202209300000 06:00:00 + /some/path/to/&FOO; + + &ACCOUNT; + 1:ppn=1 + 00:01:00 + hello + + person + siri + + + diff --git a/docs/sections/user_guide/cli/tools/rocoto/rocoto-good.xml b/docs/sections/user_guide/cli/tools/rocoto/rocoto-good.xml new file mode 100644 index 000000000..2f13a5b23 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/rocoto-good.xml @@ -0,0 +1,20 @@ + + + +]> + + 202209290000 202209300000 06:00:00 + /some/path/to/&FOO; + + &ACCOUNT; + 1:ppn=1 + 00:01:00 + echo hello $person + hello + + person + siri + + + diff --git a/docs/sections/user_guide/cli/tools/rocoto/rocoto.yaml b/docs/sections/user_guide/cli/tools/rocoto/rocoto.yaml new file mode 100644 index 000000000..eac2c7fa5 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/rocoto.yaml @@ -0,0 +1,23 @@ +workflow: + attrs: + realtime: false + scheduler: slurm + cycledef: + - attrs: + group: howdy + spec: 202209290000 202209300000 06:00:00 + entities: + ACCOUNT: myaccount + FOO: test.log + log: /some/path/to/&FOO; + tasks: + task_hello: + attrs: + cycledefs: howdy + account: "&ACCOUNT;" + command: "echo hello $person" + jobname: hello + nodes: 1:ppn=1 + walltime: 00:01:00 + envars: + person: siri diff --git a/docs/sections/user_guide/cli/tools/rocoto/validate-bad-file.cmd b/docs/sections/user_guide/cli/tools/rocoto/validate-bad-file.cmd new file mode 100644 index 000000000..715c34653 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/validate-bad-file.cmd @@ -0,0 +1 @@ +uw rocoto validate --input-file rocoto-bad.xml diff --git a/docs/sections/user_guide/cli/tools/rocoto/validate-bad-file.out b/docs/sections/user_guide/cli/tools/rocoto/validate-bad-file.out new file mode 100644 index 000000000..30cf8fe43 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/validate-bad-file.out @@ -0,0 +1,24 @@ +[2024-05-23T19:39:16] ERROR 3 Rocoto validation errors found +[2024-05-23T19:39:16] ERROR :9:0:ERROR:RELAXNGV:RELAXNG_ERR_NOELEM: Expecting an element command, got nothing +[2024-05-23T19:39:16] ERROR :9:0:ERROR:RELAXNGV:RELAXNG_ERR_INTERSEQ: Invalid sequence in interleave +[2024-05-23T19:39:16] ERROR :9:0:ERROR:RELAXNGV:RELAXNG_ERR_CONTENTVALID: Element task failed to validate content +[2024-05-23T19:39:16] ERROR Invalid Rocoto XML: +[2024-05-23T19:39:16] ERROR 1 +[2024-05-23T19:39:16] ERROR 2 +[2024-05-23T19:39:16] ERROR 4 +[2024-05-23T19:39:16] ERROR 5 ]> +[2024-05-23T19:39:16] ERROR 6 +[2024-05-23T19:39:16] ERROR 7 202209290000 202209300000 06:00:00 +[2024-05-23T19:39:16] ERROR 8 /some/path/to/&FOO; +[2024-05-23T19:39:16] ERROR 9 +[2024-05-23T19:39:16] ERROR 10 &ACCOUNT; +[2024-05-23T19:39:16] ERROR 11 1:ppn=1 +[2024-05-23T19:39:16] ERROR 12 00:01:00 +[2024-05-23T19:39:16] ERROR 13 hello +[2024-05-23T19:39:16] ERROR 14 +[2024-05-23T19:39:16] ERROR 15 person +[2024-05-23T19:39:16] ERROR 16 siri +[2024-05-23T19:39:16] ERROR 17 +[2024-05-23T19:39:16] ERROR 18 +[2024-05-23T19:39:16] ERROR 19 diff --git a/docs/sections/user_guide/cli/tools/rocoto/validate-good-file.cmd b/docs/sections/user_guide/cli/tools/rocoto/validate-good-file.cmd new file mode 100644 index 000000000..602c7bb93 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/validate-good-file.cmd @@ -0,0 +1 @@ +uw rocoto validate --input-file rocoto-good.xml diff --git a/docs/sections/user_guide/cli/tools/rocoto/validate-good-file.out b/docs/sections/user_guide/cli/tools/rocoto/validate-good-file.out new file mode 100644 index 000000000..75a232457 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/validate-good-file.out @@ -0,0 +1 @@ +[2024-05-23T19:39:16] INFO 0 Rocoto validation errors found diff --git a/docs/sections/user_guide/cli/tools/rocoto/validate-good-stdin.cmd b/docs/sections/user_guide/cli/tools/rocoto/validate-good-stdin.cmd new file mode 100644 index 000000000..cbd8280b3 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/validate-good-stdin.cmd @@ -0,0 +1 @@ +cat rocoto-good.xml | uw rocoto validate diff --git a/docs/sections/user_guide/cli/tools/rocoto/validate-good-stdin.out b/docs/sections/user_guide/cli/tools/rocoto/validate-good-stdin.out new file mode 100644 index 000000000..75a232457 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/validate-good-stdin.out @@ -0,0 +1 @@ +[2024-05-23T19:39:16] INFO 0 Rocoto validation errors found diff --git a/docs/sections/user_guide/cli/tools/rocoto/validate-help.cmd b/docs/sections/user_guide/cli/tools/rocoto/validate-help.cmd new file mode 100644 index 000000000..202b4348e --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/validate-help.cmd @@ -0,0 +1 @@ +uw rocoto validate --help diff --git a/docs/sections/user_guide/cli/tools/rocoto/validate-help.out b/docs/sections/user_guide/cli/tools/rocoto/validate-help.out new file mode 100644 index 000000000..23c28085e --- /dev/null +++ b/docs/sections/user_guide/cli/tools/rocoto/validate-help.out @@ -0,0 +1,16 @@ +usage: uw rocoto validate [-h] [--version] [--input-file PATH] [--quiet] + [--verbose] + +Validate Rocoto XML + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + --input-file PATH, -i PATH + Path to input file (defaults to stdin) + --quiet, -q + Print no logging messages + --verbose, -v + Print all logging messages diff --git a/docs/sections/user_guide/cli/tools/template.rst b/docs/sections/user_guide/cli/tools/template.rst index 3f0c07986..cd931e50f 100644 --- a/docs/sections/user_guide/cli/tools/template.rst +++ b/docs/sections/user_guide/cli/tools/template.rst @@ -3,349 +3,230 @@ The ``uw`` mode for handling :jinja2:`Jinja2 templates`. -.. code-block:: text - - $ uw template --help - usage: uw template [-h] [--version] ACTION ... - - Handle templates - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - - Positional arguments: - ACTION - render - Render a template - translate - Translate atparse to Jinja2 +.. literalinclude:: template/help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: template/help.out + :language: text .. _cli_template_render_examples: ``render`` ---------- -.. code-block:: text - - $ uw template render --help - usage: uw template render [-h] [--version] [--input-file PATH] [--output-file PATH] - [--values-file PATH] [--values-format {ini,nml,sh,yaml}] [--env] - [--search-path PATH[:PATH:...]] [--values-needed] [--dry-run] [--quiet] - [--verbose] - [KEY=VALUE ...] - - Render a template - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - --input-file PATH, -i PATH - Path to input file (defaults to stdin) - --output-file PATH, -o PATH - Path to output file (defaults to stdout) - --values-file PATH - Path to file providing override or interpolation values - --values-format {ini,nml,sh,yaml} - Values format - --env - Use environment variables - --search-path PATH[:PATH:...] - Colon-separated paths to search for extra templates - --values-needed - Print report of values needed to render template - --dry-run - Only log info, making no changes - --quiet, -q - Print no logging messages - --verbose, -v - Print all logging messages - KEY=VALUE - A key=value pair to override/supplement config +.. literalinclude:: template/render-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: template/render-help.out + :language: text Examples ^^^^^^^^ -The examples in this section use a template file named ``template`` with the following contents: - -.. code-block:: jinja - - {{ greeting }}, {{ recipient }}! +The examples in this section use a template file ``template`` with contents: -and a YAML file called ``values.yaml`` with the following contents: +.. literalinclude:: template/template + :language: jinja -.. code-block:: yaml +and a YAML file called ``values.yaml`` with contents: - greeting: Hello - recipient: World +.. literalinclude:: template/values.yaml + :language: yaml * To show the values needed to render the template: - .. code-block:: text - - $ uw template render --input-file template --values-needed - [2023-12-18T19:16:08] INFO Value(s) needed to render this template are: - [2023-12-18T19:16:08] INFO greeting - [2023-12-18T19:16:08] INFO recipient + .. literalinclude:: template/render-exec-values-needed.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-values-needed.out + :language: text * To render the template to ``stdout``: - .. code-block:: text - - $ uw template render --input-file template --values-file values.yaml - Hello, World! + .. literalinclude:: template/render-exec-stdout.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-stdout.out + :language: text - Shell redirection via ``|``, ``>``, et al. may also be used to stream output to a file, another process, etc. + :shell-redirection:`Shell redirection<>` may also be used to stream output to a file, another process, etc. * To render the template to a file via command-line argument: - .. code-block:: text - - $ uw template render --input-file template --values-file values.yaml --output-file rendered - - The content of ``rendered``: - - .. code-block:: text - - Hello, World! + .. literalinclude:: template/render-exec-file.cmd + :language: text + :emphasize-lines: 2 + .. literalinclude:: template/render-exec-file.out + :language: text * With the ``--dry-run`` flag specified, nothing is written to ``stdout`` (or to a file if ``--output-file`` is specified), but a report of what would have been written is logged to ``stderr``: - .. code-block:: text - - $ uw template render --input-file template --values-file values.yaml --dry-run - [2023-12-18T19:38:15] INFO Hello, World! + .. literalinclude:: template/render-exec-dry-run.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-dry-run.out + :language: text * To read the template from ``stdin`` and render to ``stdout``: - .. code-block:: text - - $ cat template | uw template render --values-file values.yaml - Hello, World! + .. literalinclude:: template/render-exec-read-stdin.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-read-stdin.out + :language: text * If the values file has an unrecognized (or no) extension, ``uw`` will not know how to parse its contents: - .. code-block:: text - - $ uw template render --input-file template --values-file values.txt - Cannot deduce format of 'values.txt' from unknown extension 'txt' + .. literalinclude:: template/render-exec-bad-extension.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-bad-extension.out + :language: text - In this case, the format can be explicitly specified: + The format must be explicitly specified (here, ``values.txt`` is identical to ``values.yaml``): - .. code-block:: text - - $ uw template render --input-file template --values-file values.txt --values-format yaml - Hello, World! + .. literalinclude:: template/render-exec-explicit-extension.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-explicit-extension.out + :language: text * To request verbose log output: - .. code-block:: text - - $ uw template render --input-file template --values-file values.yaml --verbose - [2023-12-18T23:25:01] DEBUG Command: uw template render --input-file template --values-file values.yaml --verbose - [2023-12-18T23:25:01] DEBUG Internal arguments: - [2023-12-18T23:25:01] DEBUG --------------------------------------------------------------------- - [2023-12-18T23:25:01] DEBUG values: values.yaml - [2023-12-18T23:25:01] DEBUG values_format: yaml - [2023-12-18T23:25:01] DEBUG input_file: template - [2023-12-18T23:25:01] DEBUG output_file: None - [2023-12-18T23:25:01] DEBUG overrides: {} - [2023-12-18T23:25:01] DEBUG values_needed: False - [2023-12-18T23:25:01] DEBUG dry_run: False - [2023-12-18T23:25:01] DEBUG --------------------------------------------------------------------- - [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 - - $ uw template render --input-file template --values-file values.yaml --verbose >rendered 2>rendered.log - - The content of ``rendered``: - - .. code-block:: text + .. literalinclude:: template/render-exec-verbose.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-verbose.out + :language: text - Hello, World! + Note that ``uw`` logs to ``stderr``. Use :shell-redirection:`shell redirection<>` as needed. - The content of ``rendered.log``: +* The following examples use the YAML file ``greeting.yaml`` with contents: - .. code-block:: text - - [2023-12-18T23:27:04] DEBUG Command: uw template render --input-file template --values-file values.yaml --verbose - [2023-12-18T23:27:04] DEBUG Internal arguments: - [2023-12-18T23:27:04] DEBUG --------------------------------------------------------------------- - [2023-12-18T23:27:04] DEBUG values: values.yaml - [2023-12-18T23:27:04] DEBUG values_format: yaml - [2023-12-18T23:27:04] DEBUG input_file: template - [2023-12-18T23:27:04] DEBUG output_file: None - [2023-12-18T23:27:04] DEBUG overrides: {} - [2023-12-18T23:27:04] DEBUG values_needed: False - [2023-12-18T23:27:04] DEBUG dry_run: False - [2023-12-18T23:27:04] DEBUG --------------------------------------------------------------------- - [2023-12-18T23:27:04] DEBUG Read initial values from values.yaml - -* **NB**: This set of examples is based on a ``values.yaml`` file with ``recipient: World`` removed. + .. literalinclude:: template/greeting.yaml + :language: yaml It is an error to render a template without providing all needed values. - .. code-block:: text - - $ uw template render --input-file template --values-file values.yaml - [2024-03-02T16:42:48] ERROR Required value(s) not provided: - [2024-03-02T16:42:48] ERROR recipient - [2024-03-02T16:42:48] ERROR Template could not be rendered + .. literalinclude:: template/render-exec-missing-value.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-missing-value.out + :language: text Values may also be supplemented by ``key=value`` command-line arguments: - .. code-block:: text - - $ uw template render --input-file template --values-file values.yaml recipient=Reader - Hello, Reader! + .. literalinclude:: template/render-exec-cli-value.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-cli-value.out + :language: text The optional ``--env`` switch allows environment variables to be used to supply values: - .. code-block:: text - - $ export recipient=You - $ uw template render --input-file template --values-file values.yaml --env - Hello, You! + .. literalinclude:: template/render-exec-env-value.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-env-value.out + :language: text Values from ``key=value`` arguments override values from file, and environment variables override both: - .. code-block:: text - - $ recipient=Sunshine uw template render --input-file template --values-file values.yaml recipient=Reader greeting="Good day" --env - Good day, Sunshine! + .. literalinclude:: template/render-exec-combo-value.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-combo-value.out + :language: text - Note that ``recipient=Sunshine`` is shell syntax for exporting environment variable ``recipient`` only for the duration of the command that follows. It should not be confused with the two ``key=value`` pairs later on the command line, which are arguments to ``uw``. +Note that, in the previous two examples, the ``var=val`` syntax preceding the ``uw`` command is shell syntax for exporting environment variable ``var`` only for the duration of the command that follows. It should not be confused with the two ``key=value`` pairs later on the command line, which are arguments to ``uw``.) * Jinja2 supports references to additional templates via, for example, `import `_ expressions, and ``uw`` provides support as follows: #. By default, the directory containing the primary template file is used as the search path for additional templates. #. The optional ``--search-path`` flag overrides the default search path with any number of explicitly specified, colon-separated paths. - For example, given file ``template`` + For example, given file ``template-with-macros`` - .. code-block:: text + .. literalinclude:: template/template-with-macros + :language: jinja - {% import "macros" as m -%} - {{ m.double(11) }} + and file ``macros`` (in the same directory as ``template-with-macros``) - and file ``macros`` (in the same directory as ``template``) - - .. code-block:: text - - {% macro double(n) -%} - {{ n * 2 }} - {%- endmacro %} + .. literalinclude:: template/macros + :language: jinja the template is rendered as - .. code-block:: text - - $ uw template render --input-file template - 22 - - The invocation ``uw template render --input-file template --search-path $PWD`` would behave identically. Alternatively, ``--search-path`` could be specified with a colon-separated set of directories to be searched for templates. - - **NB**: Reading the primary template from ``stdin`` requires use of ``--search-path``, as there is no implicit directory related to the input. For example, given the existence of ``/path/to/macros``: + .. literalinclude:: template/render-exec-macros.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-macros.out + :language: text - .. code-block:: text + The ``--search-path`` option can also be specified with a colon-separated set of directories to be searched for templates. - $ cat template | uw template render --search-path /path/to - 22 + **NB**: Reading the primary template from ``stdin`` requires use of ``--search-path``, as there is no implicit directory related to the input. For example, given the existence of directory ``macros-dir``: -* Non-YAML-formatted files may also be used as value sources. For example, ``template`` + .. literalinclude:: template/render-exec-macros-dir.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-macros-dir.out + :language: text - .. code-block:: jinja +* Non-YAML-formatted files may also be used as value sources. For example, ``values.sh`` with contents - {{ values.greeting }}, {{ values.recipient }}! + .. literalinclude:: template/values.sh + :language: fortran - can be rendered with ``values.nml`` + can be used to render ``template``: - .. code-block:: fortran - - &values - greeting = "Hello" - recipient = "World" - / - - like so: - - .. code-block:: text - - $ uw template render --input-file template --values-file values.nml - Hello, World! + .. literalinclude:: template/render-exec-sh.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/render-exec-sh.out + :language: text .. _cli_template_translate_examples: ``translate`` ------------- -.. code-block:: text - - $ uw template translate --help - usage: uw template translate [-h] [--version] [--input-file PATH] [--output-file PATH] [--dry-run] - [--quiet] [--verbose] - - Translate atparse to Jinja2 - - Optional arguments: - -h, --help - Show help and exit - --version - Show version info and exit - --input-file PATH, -i PATH - Path to input file (defaults to stdin) - --output-file PATH, -o PATH - Path to output file (defaults to stdout) - --dry-run - Only log info, making no changes - --quiet, -q - Print no logging messages - --verbose, -v - Print all logging messages +.. literalinclude:: template/translate-help.cmd + :language: text + :emphasize-lines: 1 +.. literalinclude:: template/translate-help.out + :language: text Examples ^^^^^^^^ -The examples in this section use atparse-formatted template file ``atparse.txt`` with the following contents: - -.. code-block:: text +The examples in this section use atparse-formatted template file ``atparse.txt`` with contents: - @[greeting], @[recipient]! + .. literalinclude:: template/atparse.txt + :language: text * To convert an atparse-formatted template file to Jinja2 format: - .. code-block:: text - - $ uw template translate --input-file atparse.txt - {{ greeting }}, {{ recipient }}! + .. literalinclude:: template/translate-exec-stdout.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/translate-exec-stdout.out + :language: text - Shell redirection via ``|``, ``>``, et al. may also be used to stream output to a file, another process, etc. + :shell-redirection:`Shell redirection<>` may also be used to stream output to a file, another process, etc. * To convert the template to a file via command-line argument: - .. code-block:: text - - $ uw template translate --input-file atparse.txt --output-file jinja2.txt - - The content of ``jinja2.txt``: - - .. code-block:: jinja - - {{ greeting }}, {{ recipient }}! + .. literalinclude:: template/translate-exec-file.cmd + :language: text + :emphasize-lines: 2 + .. literalinclude:: template/translate-exec-file.out + :language: text * With the ``--dry-run`` flag specified, nothing is written to ``stdout`` (or to a file if ``--output-file`` is specified), but a report of what would have been written is logged to ``stderr``: - .. code-block:: text - - $ uw template translate --input-file atparse.txt --dry-run - [2024-02-06T21:53:43] INFO {{ greeting }}, {{ recipient }}! + .. literalinclude:: template/translate-exec-dry-run.cmd + :language: text + :emphasize-lines: 1 + .. literalinclude:: template/translate-exec-dry-run.out + :language: text diff --git a/docs/sections/user_guide/cli/tools/template/.gitignore b/docs/sections/user_guide/cli/tools/template/.gitignore new file mode 100644 index 000000000..9dcdeb0e0 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/.gitignore @@ -0,0 +1,2 @@ +jinja2.txt +rendered diff --git a/docs/sections/user_guide/cli/tools/template/Makefile b/docs/sections/user_guide/cli/tools/template/Makefile new file mode 120000 index 000000000..2486334a6 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/Makefile @@ -0,0 +1 @@ +../../Makefile.outputs \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/template/atparse.txt b/docs/sections/user_guide/cli/tools/template/atparse.txt new file mode 100644 index 000000000..f76888996 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/atparse.txt @@ -0,0 +1 @@ +@[greeting], @[recipient]! diff --git a/docs/sections/user_guide/cli/tools/template/greeting.yaml b/docs/sections/user_guide/cli/tools/template/greeting.yaml new file mode 100644 index 000000000..0f3a310b5 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/greeting.yaml @@ -0,0 +1 @@ +greeting: Hello diff --git a/docs/sections/user_guide/cli/tools/template/help.cmd b/docs/sections/user_guide/cli/tools/template/help.cmd new file mode 100644 index 000000000..fc642dd43 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/help.cmd @@ -0,0 +1 @@ +uw template --help diff --git a/docs/sections/user_guide/cli/tools/template/help.out b/docs/sections/user_guide/cli/tools/template/help.out new file mode 100644 index 000000000..57598d20e --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/help.out @@ -0,0 +1,16 @@ +usage: uw template [-h] [--version] ACTION ... + +Handle templates + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + +Positional arguments: + ACTION + render + Render a template + translate + Translate atparse to Jinja2 diff --git a/docs/sections/user_guide/cli/tools/template/macros b/docs/sections/user_guide/cli/tools/template/macros new file mode 100644 index 000000000..76a16b04c --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/macros @@ -0,0 +1,3 @@ +{% macro double(n) -%} +{{ n * 2 }} +{%- endmacro %} diff --git a/docs/sections/user_guide/cli/tools/template/macros-dir/macros b/docs/sections/user_guide/cli/tools/template/macros-dir/macros new file mode 120000 index 000000000..11f9486ed --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/macros-dir/macros @@ -0,0 +1 @@ +../macros \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-bad-extension.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-bad-extension.cmd new file mode 100644 index 000000000..08f36e939 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-bad-extension.cmd @@ -0,0 +1 @@ +uw template render --input-file template --values-file values.txt diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-bad-extension.out b/docs/sections/user_guide/cli/tools/template/render-exec-bad-extension.out new file mode 100644 index 000000000..90d48f3ec --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-bad-extension.out @@ -0,0 +1 @@ +Cannot deduce format of 'values.txt' from unknown extension 'txt' diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-cli-value.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-cli-value.cmd new file mode 100644 index 000000000..6eea1f1fb --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-cli-value.cmd @@ -0,0 +1 @@ +uw template render --input-file template --values-file greeting.yaml recipient=Reader diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-cli-value.out b/docs/sections/user_guide/cli/tools/template/render-exec-cli-value.out new file mode 100644 index 000000000..dd4507986 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-cli-value.out @@ -0,0 +1 @@ +Hello, Reader! diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-combo-value.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-combo-value.cmd new file mode 100644 index 000000000..f306ff51c --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-combo-value.cmd @@ -0,0 +1 @@ +recipient=Sunshine uw template render --input-file template --values-file greeting.yaml recipient=Reader greeting="Good day" --env diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-combo-value.out b/docs/sections/user_guide/cli/tools/template/render-exec-combo-value.out new file mode 100644 index 000000000..1bdf52037 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-combo-value.out @@ -0,0 +1 @@ +Good day, Sunshine! diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-dry-run.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-dry-run.cmd new file mode 100644 index 000000000..776e2edf4 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-dry-run.cmd @@ -0,0 +1 @@ +uw template render --input-file template --values-file values.yaml --dry-run diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-dry-run.out b/docs/sections/user_guide/cli/tools/template/render-exec-dry-run.out new file mode 100644 index 000000000..f2b258595 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-dry-run.out @@ -0,0 +1 @@ +[2024-05-23T19:39:14] INFO Hello, World! diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-env-value.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-env-value.cmd new file mode 100644 index 000000000..3131e8223 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-env-value.cmd @@ -0,0 +1 @@ +recipient=You uw template render --input-file template --values-file greeting.yaml --env diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-env-value.out b/docs/sections/user_guide/cli/tools/template/render-exec-env-value.out new file mode 100644 index 000000000..1ddb86182 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-env-value.out @@ -0,0 +1 @@ +Hello, You! diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-explicit-extension.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-explicit-extension.cmd new file mode 100644 index 000000000..17a140d45 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-explicit-extension.cmd @@ -0,0 +1 @@ +uw template render --input-file template --values-file values.txt --values-format yaml diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-explicit-extension.out b/docs/sections/user_guide/cli/tools/template/render-exec-explicit-extension.out new file mode 100644 index 000000000..8ab686eaf --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-explicit-extension.out @@ -0,0 +1 @@ +Hello, World! diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-file.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-file.cmd new file mode 100644 index 000000000..0d849c451 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-file.cmd @@ -0,0 +1,3 @@ +rm -f rendered +uw template render --input-file template --values-file values.yaml --output-file rendered +cat rendered diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-file.out b/docs/sections/user_guide/cli/tools/template/render-exec-file.out new file mode 100644 index 000000000..8ab686eaf --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-file.out @@ -0,0 +1 @@ +Hello, World! diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-macros-dir.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-macros-dir.cmd new file mode 100644 index 000000000..484863064 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-macros-dir.cmd @@ -0,0 +1 @@ +cat template-with-macros | uw template render --search-path macros-dir diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-macros-dir.out b/docs/sections/user_guide/cli/tools/template/render-exec-macros-dir.out new file mode 100644 index 000000000..2bd5a0a98 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-macros-dir.out @@ -0,0 +1 @@ +22 diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-macros.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-macros.cmd new file mode 100644 index 000000000..b52041ae9 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-macros.cmd @@ -0,0 +1 @@ +uw template render --input-file template-with-macros diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-macros.out b/docs/sections/user_guide/cli/tools/template/render-exec-macros.out new file mode 100644 index 000000000..2bd5a0a98 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-macros.out @@ -0,0 +1 @@ +22 diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-missing-value.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-missing-value.cmd new file mode 100644 index 000000000..df26bdde0 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-missing-value.cmd @@ -0,0 +1 @@ +uw template render --input-file template --values-file greeting.yaml diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-missing-value.out b/docs/sections/user_guide/cli/tools/template/render-exec-missing-value.out new file mode 100644 index 000000000..fb8dbc4a5 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-missing-value.out @@ -0,0 +1,3 @@ +[2024-05-23T19:39:16] ERROR Required value(s) not provided: +[2024-05-23T19:39:16] ERROR recipient +[2024-05-23T19:39:16] ERROR Template could not be rendered diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-read-stdin.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-read-stdin.cmd new file mode 100644 index 000000000..ae5afb320 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-read-stdin.cmd @@ -0,0 +1 @@ +cat template | uw template render --values-file values.yaml diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-read-stdin.out b/docs/sections/user_guide/cli/tools/template/render-exec-read-stdin.out new file mode 100644 index 000000000..8ab686eaf --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-read-stdin.out @@ -0,0 +1 @@ +Hello, World! diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-sh.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-sh.cmd new file mode 100644 index 000000000..044654e52 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-sh.cmd @@ -0,0 +1 @@ +uw template render --input-file template --values-file values.sh diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-sh.out b/docs/sections/user_guide/cli/tools/template/render-exec-sh.out new file mode 100644 index 000000000..8ab686eaf --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-sh.out @@ -0,0 +1 @@ +Hello, World! diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-stdout.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-stdout.cmd new file mode 100644 index 000000000..0d0c2729b --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-stdout.cmd @@ -0,0 +1 @@ +uw template render --input-file template --values-file values.yaml diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-stdout.out b/docs/sections/user_guide/cli/tools/template/render-exec-stdout.out new file mode 100644 index 000000000..8ab686eaf --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-stdout.out @@ -0,0 +1 @@ +Hello, World! diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-values-needed.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-values-needed.cmd new file mode 100644 index 000000000..fdd495a59 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-values-needed.cmd @@ -0,0 +1 @@ +uw template render --input-file template --values-needed diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-values-needed.out b/docs/sections/user_guide/cli/tools/template/render-exec-values-needed.out new file mode 100644 index 000000000..83dc1084c --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-values-needed.out @@ -0,0 +1,3 @@ +[2024-05-23T19:39:16] INFO Value(s) needed to render this template are: +[2024-05-23T19:39:16] INFO greeting +[2024-05-23T19:39:16] INFO recipient diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-verbose.cmd b/docs/sections/user_guide/cli/tools/template/render-exec-verbose.cmd new file mode 100644 index 000000000..76fec080f --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-verbose.cmd @@ -0,0 +1 @@ +uw template render --input-file template --values-file values.yaml --verbose diff --git a/docs/sections/user_guide/cli/tools/template/render-exec-verbose.out b/docs/sections/user_guide/cli/tools/template/render-exec-verbose.out new file mode 100644 index 000000000..8083dba6f --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-exec-verbose.out @@ -0,0 +1,15 @@ +[2024-05-23T19:39:13] DEBUG Command: uw template render --input-file template --values-file values.yaml --verbose +[2024-05-23T19:39:13] DEBUG Internal arguments: +[2024-05-23T19:39:13] DEBUG --------------------------------------------------------------------- +[2024-05-23T19:39:13] DEBUG values_src: values.yaml +[2024-05-23T19:39:13] DEBUG values_format: yaml +[2024-05-23T19:39:13] DEBUG input_file: template +[2024-05-23T19:39:13] DEBUG output_file: None +[2024-05-23T19:39:13] DEBUG overrides: {} +[2024-05-23T19:39:13] DEBUG env: False +[2024-05-23T19:39:13] DEBUG searchpath: None +[2024-05-23T19:39:13] DEBUG values_needed: False +[2024-05-23T19:39:13] DEBUG dry_run: False +[2024-05-23T19:39:13] DEBUG --------------------------------------------------------------------- +[2024-05-23T19:39:13] DEBUG Read initial values from values.yaml +Hello, World! diff --git a/docs/sections/user_guide/cli/tools/template/render-help.cmd b/docs/sections/user_guide/cli/tools/template/render-help.cmd new file mode 100644 index 000000000..9e8f2536f --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-help.cmd @@ -0,0 +1 @@ +uw template render --help diff --git a/docs/sections/user_guide/cli/tools/template/render-help.out b/docs/sections/user_guide/cli/tools/template/render-help.out new file mode 100644 index 000000000..c48e430bd --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/render-help.out @@ -0,0 +1,36 @@ +usage: uw template render [-h] [--version] [--input-file PATH] + [--output-file PATH] [--values-file PATH] + [--values-format {ini,nml,sh,yaml}] [--env] + [--search-path PATH[:PATH:...]] [--values-needed] + [--dry-run] [--quiet] [--verbose] + [KEY=VALUE ...] + +Render a template + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + --input-file PATH, -i PATH + Path to input file (defaults to stdin) + --output-file PATH, -o PATH + Path to output file (defaults to stdout) + --values-file PATH + Path to file providing override or interpolation values + --values-format {ini,nml,sh,yaml} + Values format + --env + Use environment variables + --search-path PATH[:PATH:...] + Colon-separated paths to search for extra templates + --values-needed + Print report of values needed to render template + --dry-run + Only log info, making no changes + --quiet, -q + Print no logging messages + --verbose, -v + Print all logging messages + KEY=VALUE + A key=value pair to override/supplement config diff --git a/docs/sections/user_guide/cli/tools/template/template b/docs/sections/user_guide/cli/tools/template/template new file mode 100644 index 000000000..41a983ccf --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/template @@ -0,0 +1 @@ +{{ greeting }}, {{ recipient }}! diff --git a/docs/sections/user_guide/cli/tools/template/template-with-macros b/docs/sections/user_guide/cli/tools/template/template-with-macros new file mode 100644 index 000000000..efbf8ffc7 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/template-with-macros @@ -0,0 +1,2 @@ +{% import "macros" as m -%} +{{ m.double(11) }} diff --git a/docs/sections/user_guide/cli/tools/template/translate-exec-dry-run.cmd b/docs/sections/user_guide/cli/tools/template/translate-exec-dry-run.cmd new file mode 100644 index 000000000..b36fcf69f --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/translate-exec-dry-run.cmd @@ -0,0 +1 @@ +uw template translate --input-file atparse.txt --dry-run diff --git a/docs/sections/user_guide/cli/tools/template/translate-exec-dry-run.out b/docs/sections/user_guide/cli/tools/template/translate-exec-dry-run.out new file mode 100644 index 000000000..bc2db473f --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/translate-exec-dry-run.out @@ -0,0 +1 @@ +[2024-05-23T19:39:16] INFO {{ greeting }}, {{ recipient }}! diff --git a/docs/sections/user_guide/cli/tools/template/translate-exec-file.cmd b/docs/sections/user_guide/cli/tools/template/translate-exec-file.cmd new file mode 100644 index 000000000..378d0dde0 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/translate-exec-file.cmd @@ -0,0 +1,3 @@ +rm -f jinja2.txt +uw template translate --input-file atparse.txt --output-file jinja2.txt +cat jinja2.txt diff --git a/docs/sections/user_guide/cli/tools/template/translate-exec-file.out b/docs/sections/user_guide/cli/tools/template/translate-exec-file.out new file mode 100644 index 000000000..41a983ccf --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/translate-exec-file.out @@ -0,0 +1 @@ +{{ greeting }}, {{ recipient }}! diff --git a/docs/sections/user_guide/cli/tools/template/translate-exec-stdout.cmd b/docs/sections/user_guide/cli/tools/template/translate-exec-stdout.cmd new file mode 100644 index 000000000..1fcd5a522 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/translate-exec-stdout.cmd @@ -0,0 +1 @@ +uw template translate --input-file atparse.txt diff --git a/docs/sections/user_guide/cli/tools/template/translate-exec-stdout.out b/docs/sections/user_guide/cli/tools/template/translate-exec-stdout.out new file mode 100644 index 000000000..41a983ccf --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/translate-exec-stdout.out @@ -0,0 +1 @@ +{{ greeting }}, {{ recipient }}! diff --git a/docs/sections/user_guide/cli/tools/template/translate-help.cmd b/docs/sections/user_guide/cli/tools/template/translate-help.cmd new file mode 100644 index 000000000..c446ee6ba --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/translate-help.cmd @@ -0,0 +1 @@ +uw template translate --help diff --git a/docs/sections/user_guide/cli/tools/template/translate-help.out b/docs/sections/user_guide/cli/tools/template/translate-help.out new file mode 100644 index 000000000..d1ca93c39 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/translate-help.out @@ -0,0 +1,21 @@ +usage: uw template translate [-h] [--version] [--input-file PATH] + [--output-file PATH] [--dry-run] [--quiet] + [--verbose] + +Translate atparse to Jinja2 + +Optional arguments: + -h, --help + Show help and exit + --version + Show version info and exit + --input-file PATH, -i PATH + Path to input file (defaults to stdin) + --output-file PATH, -o PATH + Path to output file (defaults to stdout) + --dry-run + Only log info, making no changes + --quiet, -q + Print no logging messages + --verbose, -v + Print all logging messages diff --git a/docs/sections/user_guide/cli/tools/template/values.sh b/docs/sections/user_guide/cli/tools/template/values.sh new file mode 100644 index 000000000..3d5d21ad6 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/values.sh @@ -0,0 +1,2 @@ +greeting="Hello" +recipient="World" diff --git a/docs/sections/user_guide/cli/tools/template/values.txt b/docs/sections/user_guide/cli/tools/template/values.txt new file mode 120000 index 000000000..7d1010096 --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/values.txt @@ -0,0 +1 @@ +values.yaml \ No newline at end of file diff --git a/docs/sections/user_guide/cli/tools/template/values.yaml b/docs/sections/user_guide/cli/tools/template/values.yaml new file mode 100644 index 000000000..be310733b --- /dev/null +++ b/docs/sections/user_guide/cli/tools/template/values.yaml @@ -0,0 +1,2 @@ +greeting: Hello +recipient: World diff --git a/src/uwtools/cli.py b/src/uwtools/cli.py index 63f15b364..58cfbb6f7 100644 --- a/src/uwtools/cli.py +++ b/src/uwtools/cli.py @@ -350,7 +350,7 @@ def _add_subparser_rocoto(subparsers: Subparsers) -> ModeChecks: :param subparsers: Parent parser's subparsers, to add this subparser to. """ - parser = _add_subparser(subparsers, STR.rocoto, "Realize and validate Rocoto XML Documents") + parser = _add_subparser(subparsers, STR.rocoto, "Realize and validate Rocoto XML documents") _basic_setup(parser) subparsers = _add_subparsers(parser, STR.action, STR.action.upper()) return { @@ -530,7 +530,7 @@ def _dispatch_template_translate(args: Args) -> bool: # Arguments -# pylint: disable=line-too-long, missing-function-docstring +# pylint: disable=missing-function-docstring def _add_arg_batch(group: Group) -> None: @@ -644,7 +644,8 @@ def _add_arg_key_eq_val_pairs(group: Group) -> None: def _add_arg_key_path(group: Group) -> None: group.add_argument( _switch(STR.keypath), - help="Dot-separated path of keys leading through the config to the driver's configuration block", + help="Dot-separated path of keys leading through the config " + "to the driver's configuration block", metavar="KEY[.KEY...]", required=False, type=lambda s: s.split("."), diff --git a/src/uwtools/utils/tasks.py b/src/uwtools/utils/tasks.py index ae721d9d8..5665f9d13 100644 --- a/src/uwtools/utils/tasks.py +++ b/src/uwtools/utils/tasks.py @@ -70,4 +70,7 @@ def symlink(target: Path, linkname: Path): yield asset(linkname, linkname.exists) yield existing(target) linkname.parent.mkdir(parents=True, exist_ok=True) - os.symlink(src=target, dst=linkname) + os.symlink( + src=target if target.is_absolute() else os.path.relpath(target, linkname.parent), + dst=linkname, + )