US-157: Edit uwtools documentation

docs/conf.py

@@ -24,6 +24,7 @@
 project = "Unified Workflow Tools"
 release = _metadata["version"]
 version = _metadata["version"]
+user_agent = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36"
 
 extlinks = {
     "anaconda": ("https://www.anaconda.com/%s", "%s"),
@@ -44,6 +45,7 @@
     "miniforge": ("https://github.com/conda-forge/miniforge/%s", "%s"),
     "miniforge3": ("https://github.com/conda-forge/miniforge/%s", "%s"),
     "mypy": ("https://mypy.readthedocs.io/en/stable/%s", "%s"),
+    "noaa": ("https://www.noaa.gov/%s", "%s"),
     "pylint": ("https://pylint.readthedocs.io/en/v3.0.3/%s", "%s"),
     "pytest": ("https://docs.pytest.org/en/7.4.x/%s", "%s"),
     "rocoto": ("https://christopherwharrop.github.io/rocoto/%s", "%s"),

docs/index.rst

@@ -7,33 +7,33 @@
 Unified Workflow Tools
 ======================
 
-``uwtools`` is an open-source modern Python package that helps automate common tasks needed for many standard numerical weather prediction (NWP) workflows and provides drivers to automate the configuration and execution of :ufs:`Unified Forecast System (UFS)<>` components, providing flexibility, interoperability, and usability to various UFS Applications.
+``uwtools`` is a modern, open-source Python package that helps automate common tasks needed for many standard numerical weather prediction (NWP) workflows. It also provides drivers to automate the configuration and execution of :ufs:`Unified Forecast System (UFS)<>` components, providing flexibility, interoperability, and usability to various UFS Applications.
 
 If you're interested in contributing, check out the :doc:`Contributor Guide <sections/contributor_guide/index>`.
 
 For users who want to start using the toolbox and framework, take a peek at our :doc:`User Guide <sections/user_guide/index>`.
 
-.. contents:: On this page
+.. contents:: On This Page:
    :depth: 2
    :local:
 
 The Tools
 ---------
 
-The tools are accessible from both a command-line interface (CLI) and a Python API. The CLI automates many operations commonly needed in NWP workflows. The API supports all CLI operations, and additionally provides access to in-memory objects to facilitate more novel use cases. We hope these options will let you integrate the package into your pre-existing bash and Python scripts, and give you some handy tools to use in your day-to-day work with running NWP systems.
+The tools are accessible from both a command-line interface (CLI) and a Python API. The CLI automates many operations commonly needed in NWP workflows. The API supports all CLI operations and additionally provides access to in-memory objects to facilitate more novel use cases. We hope these options will let you integrate the package into your pre-existing bash and Python scripts, and give you some handy tools to use in your day-to-day work with running NWP systems.
 
 Configuration Management
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 | **CLI**: ``uw config -h``
 | **API**: ``import uwtools.api.config``
 
-The config tool suite helps you compare, transform, modify, and even validate your configuration. The package supports YAML, shell, Fortran namelist, and INI file formats. Configuration in any of these formats may express values using :jinja2:`Jinja2 syntax<templates>`. These values can reference others, or compute new values by evaluating mathematical expressions, building paths, manipulating strings, etc.
+The config tool suite helps you compare, transform, modify, and even validate your configuration. The package supports YAML, shell, Fortran namelist, and INI file formats. Configuration in any of these formats may use :jinja2:`Jinja2 syntax<templates>` to express values. These values can reference others, or compute new values by evaluating mathematical expressions, building paths, manipulating strings, etc.
 
 Compare Mode
 """"""""""""
 
-When the Linux diff tool just doesn't work for comparing unordered namelists with mixed-case keys, this is your go-to! It also works on the other configuration formats, but the Fortran namelists are the *real* catalyst behind this gem!
+When the Linux diff tool just doesn't work for comparing unordered namelists with mixed-case keys, this is your go-to! The Fortran namelists are the *real* catalyst behind this gem, but it also works on the other configuration formats.
 
 | :any:`CLI documentation with examples<cli_config_compare_examples>`
 
@@ -67,7 +67,7 @@ The ``render`` mode that gives you the full power of rendering a :jinja2:`Jinja2
 Translate Mode
 """"""""""""""
 
-This tool helps transform legacy configuration files templated with the atparse tool (common at NOAA) into :jinja2:`Jinja2 templates<templates>` for use with the ``uw config realize`` and ``uw template render`` tools, or their API equivalents.
+This tool helps transform legacy configuration files templated with the atparse tool (common at :noaa:`NOAA<>`) into :jinja2:`Jinja2 templates<templates>` for use with the ``uw config realize`` and ``uw template render`` tools, or their API equivalents.
 
 | :any:`CLI documentation with examples<cli_template_translate_examples>`
 
@@ -82,14 +82,14 @@ This tool is all about creating a configurable interface to the :rocoto:`Rocoto<
 Realize Mode
 """"""""""""
 
-This is where you put in your structured YAML that defines your workflow of choice and it pops out a verified Rocoto XML.
+This is where you put in your structured YAML that defines your workflow of choice, and it pops out a verified Rocoto XML.
 
 | :any:`CLI documentation with examples<cli_rocoto_realize_examples>`
 
 Validate Mode
 """""""""""""
 
-Do you already have a Rocoto XML, but don't want to run Rocoto to make sure it works? Use the validate mode to check to see if Rocoto will be happy.
+Do you already have a Rocoto XML but don't want to run Rocoto to make sure it works? Use the validate mode to check to see if Rocoto will be happy.
 
 | :any:`CLI documentation with examples<cli_rocoto_validate_examples>`
 
@@ -104,9 +104,9 @@ Forecast
 | **CLI**: ``uw forecast -h``
 | **API**: ``import uwtools.api.drivers.forecast``
 
-This driver is the first of its kind (with many others to come) and takes a few pieces of information from the user – the model, the time, and a structured YAML – and it runs a forecast via batch job or as an executable. That simple.
+This driver is the first of its kind (with many others to come) and takes a few pieces of information from the user --- the model, the time, and a structured YAML --- and runs a forecast via batch job or as an executable. That simple.
 
-We've helped by providing a JSON Schema that allows you to validate your YAML to ensure you’ve got it right!
+We've helped by providing a JSON Schema that allows you to validate your YAML to ensure you've got it right!
 
 Over time, we'll add many other drivers to support a variety of UFS components from pre-processing to post-processing, along with many data assimilation components.
 

docs/sections/contributor_guide/code_quality.rst

@@ -24,11 +24,11 @@ Configuration for these tools is provided by the file ``src/pyproject.toml``.
 
 The order of the targets above is intentional:
 
-   * ``make format`` will complain about certain kinds of syntax errors that would cause all the remaining code-quality tools to fail (and may change line numbers reported by other tools, if it ran after them).
+   * ``make format`` will complain about certain kinds of syntax errors that would cause all the remaining code-quality tools to fail (and that could change line numbers reported by other tools, if it ran after them).
    * ``make lint`` provides a good first check for obvious errors and anti-patterns in the code.
    * ``make typecheck`` offers a more nuanced look at interfaces between functions, methods, etc. and may spot issues missed by the linter.
    * ``make unittest`` provides higher-level semantic-correctness checks once code syntax and typing is deemed correct.
 
-All the above tests are executed by the CI system when code is merged to specific git branches, and again when a conda package is built for release. To ensure that these processes succeed, be sure to run all the tests in a development shell before opening a pull request, and throughout the PR's lifecycle as subsequent changes are made. CI will reject unformatted code, so also run ``make format`` and commit any changes it makes. A useful development idiom is to periodically run ``make format && make test`` to perform a full code-quality sweep through the code.
+All the above tests are executed by the CI system when code is merged to specific git branches and when a conda package is built for release. To ensure that these processes succeed, be sure to run all the tests in a development shell before opening a pull request, and throughout the PR's lifecycle as subsequent changes are made. CI will reject unformatted code, so also run ``make format`` and commit any changes it makes. A useful development idiom is to periodically run ``make format && make test`` to perform a full code-quality sweep through the code.
 
-The ``uwtools`` repository has standardized on 100% unit-test coverage, enforced by ``make unittest`` and its configuration in ``pyproject.toml``. Please help maintain this high standard.
+The ``uwtools`` repository has standardized 100% unit-test coverage, enforced by ``make unittest`` and its configuration in ``pyproject.toml``. Please help maintain this high standard.

docs/sections/contributor_guide/developer_setup.rst

@@ -23,7 +23,7 @@ If an existing conda (:miniforge:`Miniforge<>`, :miniconda:`Miniconda<>`, :anaco
 
 If the above is successful, you will be in a ``uwtools`` development shell. See below for usage information. You may exit the shell with ``exit`` or ``ctrl-d``.
 
-Future ``make devshell`` invocations will be almost instantaneous, as the underlying virtual environment will already exist. In general, all source code changes will be immediately live in the development shell, subject to execution, test, etc. But some changes – especially to the contents of the ``recipe/`` directory, or to the ``src/setup.py`` module – may require recreation of the development shell. If you know this is needed, or when in doubt:
+Future ``make devshell`` invocations will be almost instantaneous, as the underlying virtual environment will already exist. In general, all source code changes will be immediately live in the development shell, subject to execution, test, etc. But some changes --- especially to the contents of the ``recipe/`` directory or to the ``src/setup.py`` module --- may require recreation of the development shell. If you know this is needed, or when in doubt:
 
   #. Exit the development shell.
   #. Run ``make clean-devenv`` (or ``conda env remove -n DEV-uwtools``) to remove the old environment.
@@ -42,7 +42,7 @@ Using a ``bash`` Development Shell
 
 A development shell makes available several code-formatting and quality checkers, which should be periodically run during the development process. See :doc:`Code Quality <code_quality>` for full details.
 
-In addition to the ``make devshell`` command, other ``make`` targets are available for use *outside* a development shell, i.e. from the base conda environment (requires presence of the ``condev`` package):
+In addition to the ``make devshell`` command, other ``make`` targets are available for use *outside* a development shell, i.e., from the base conda environment (requires presence of the ``condev`` package):
 
 .. list-table::
    :widths: 15 85
@@ -62,7 +62,7 @@ These targets work from the code in its current state in the clone. ``make env``
 Building ``condev`` Locally
 ---------------------------
 
-As an alternative to installing :anaconda-condev:`pre-built package<>`, the ``condev`` package can be built locally, then installed into the local conda installation. Ensure that ``conda-build`` and ``conda-verify`` are installed in the base environment:
+As an alternative to installing the :anaconda-condev:`pre-built package<>`, the ``condev`` package can be built locally, then installed into the local conda installation. Ensure that ``conda-build`` and ``conda-verify`` are installed in the base environment:
 
 .. code-block:: text
 
@@ -74,7 +74,7 @@ As an alternative to installing :anaconda-condev:`pre-built package<>`, the ``co
 Files Derived from ``condev``
 -----------------------------
 
-The following files in this repo are derived from their counterparts in the :condev:`condev demo<tree/main/demo>` and are used by ``condev`` code when running certain make commands
+The following files in this repository are derived from their counterparts in the :condev:`condev demo<tree/main/demo>` and are used by ``condev`` code when running certain make commands
 
 .. code-block:: text
 

docs/sections/contributor_guide/documentation.rst

@@ -17,16 +17,16 @@ The ``make docs`` command will build the docs under ``docs/build/html``, after w
 
    file://<filesystem-path-to-your-clone>/docs/build/html/index.index.html
 
-Re-run ``make docs`` and refresh your browser after making and saving changes.
+Rerun ``make docs`` and refresh your browser after making and saving changes.
 
-If, at some point, you remove and recreate the conda development environment underlying your development shell, you will need to re-run the ``source install-deps`` command in the new environment/shell. Until then, the installed doc packages will persist and support docs generation.
+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.
 
 Viewing Online Documentation
 ----------------------------
 
-Online documentation generation and hosting for ``uwtools`` is provided by :rtd:`Read the Docs<>`. The green *View Docs* button near the upper right of that page links to the official docs for the project, as built for the ``main`` branch. Docs are also generated for the ``develop`` branch, and can be selected by changing **v: main** to **v: develop** via the small green pull-down menu located at the bottom of the navigation pane on the left of the page.
+Online documentation generation and hosting for ``uwtools`` is provided by :rtd:`Read the Docs<>`. The green *View Docs* button near the upper right of that page links to the official docs for the project, as built for the ``main`` branch. Docs are also generated for the ``develop`` branch and can be selected by changing **v: main** to **v: develop** via the small green pull-down menu located at the bottom of the navigation pane on the left of the page.
 
-Docs are also built and published when Pull Requests (PRs) targeting the ``develop`` or ``main`` branches are opened. Visit the :rtd:`Builds page<builds>` to see recent builds, including those made for PRs. Click a PR-related build marked *Passed*, then the small *View docs* link (**not** the large green *View Docs* button) to see the docs built specifically for that PR. If your PR includes documentation updates, it may be helpful to include the URL of this build in your PR's description so that reviewers can see the rendered HTML docs and not just the modified ``.rst`` files. Note that, if commits are pushed to the PR's source branch, Read the Docs will rebuild the PR docs: See the checks section near the bottom of a PR for current status, and for another link to the PR docs via the *Details* link.
+Docs are also built and published when Pull Requests (PRs) targeting the ``develop`` or ``main`` branches are opened. Visit the :rtd:`Builds page<builds>` to see recent builds, including those made for PRs. Click a PR-related build marked *Passed*, then the small *View docs* link (**not** the large green *View Docs* button) to see the docs built specifically for that PR. If your PR includes documentation updates, it may be helpful to include the URL of this build in your PR's description so that reviewers can see the rendered HTML docs and not just the modified ``.rst`` files. Note that if commits are pushed to the PR's source branch, Read the Docs will rebuild the PR docs. See the checks section near the bottom of a PR for current status, and for another link to the PR docs via the *Details* link.
 
 Documentation Guidelines
 ------------------------
@@ -44,9 +44,9 @@ Please follow these guidelines when contributing to the documentation:
 * The synopsis information printed by ``uw [mode [action]] --help`` is automatically wrapped and indented based on current terminal size. For visual consistency, please set your terminal width to 100 columns when running such commands to produce output to copy into the docs.
 * Follow the :rst:`RST Sections<basics.html#sections>` guidelines, underlining section headings with = characters, subsections with - characters, and subsubsections with ^ characters. If a further level of refinement is needed, use " to underline paragraph headers.
 * In [[sub]sub]section titles, capitalize all "principal" words. In practice this usually means all words but articles (a, an, the), logicals (and, etc.), and prepositions (for, of, etc.). Always fully capitalize acronyms (e.g., YAML).
-* Never capitalize proper names when their owners do not (e.g. write `"pandas" <https://pandas.pydata.org/>`_, not "Pandas", even at the start of a sentence) or when referring to a software artifact (e.g. write ``numpy`` when referring to the library, and "NumPy" when referring to the project).
+* Never capitalize proper names when their owners do not (e.g., write `"pandas" <https://pandas.pydata.org/>`_, not "Pandas", even at the start of a sentence) or when referring to a software artifact (e.g., write ``numpy`` when referring to the library, and "NumPy" when referring to the project).
 * When referring to YAML constructs, `block` refers to an entry whose values is a nested collection of key/value pairs, while `entry` is a single key/value pair.
-* When using the ``.. code-block::`` directive, align the actual code with the word ``code``. Also, when ``.. code-block::`` directives appear in bulleted or numberd lists, align them with the text following the space to the righ of the bullet/number. For example:
+* When using the ``.. code-block::`` directive, align the actual code with the word ``code``. Also, when ``.. code-block::`` directives appear in bulleted or numberd lists, align them with the text following the space to the right of the bullet/number. For example:
 
   .. code-block:: text
 

docs/sections/contributor_guide/fork_pr_model.rst

@@ -12,7 +12,7 @@ Contributions to the ``uwtools`` project are made via a :github-docs:`Fork<pull-
 #. :github-docs:`Make, commit, and push changes<get-started/exploring-projects-on-github/contributing-to-a-project#making-and-pushing-changes>` in your clone / to your fork. (Refer to the :doc:`Developer Setup <developer_setup>` page for setting up a development shell, formatting and testing your code, etc.)
 #. When your work is complete, :github-docs:`create a pull request<get-started/exploring-projects-on-github/contributing-to-a-project#making-a-pull-request>` to merge your changes.
 
-For future contributions, you may delete and then re-create your fork, or configure the official ``uwtools`` repo as :github-docs:`remote repository<pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork>` on your clone and :github-docs:`sync upstream changes<pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork>` to stay up-to-date with the official repo.
+For future contributions, you may delete and then recreate your fork or configure the official ``uwtools`` repository as a :github-docs:`remote repository<pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork>` on your clone and :github-docs:`sync upstream changes<pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork>` to stay up-to-date with the official repository.
 
 Specifics for ``uwtools``
 -------------------------