add documentation for multirun mode (#431)

clean up some of the existing documentation

doc/sphinx/ref_cli.rst

@@ -8,9 +8,16 @@ Command-line options
 Running the package
 -------------------
 
-If you followed the :ref:`recommended installation method<ref-conda-install>` for installing the framework with the `conda <https://docs.conda.io/en/latest/>`__ package manager, the installation process will have created a driver script named ``mdtf`` in the top level of the code directory. This script should always be used as the entry point for running the package.
+If you followed the :ref:`recommended installation method<ref-conda-install>` for installing the framework
+the `conda <https://docs.conda.io/en/latest/>`__ package manager, the installation process will have created
+a driver script named ``mdtf`` in the top level of the code directory.
+This script should always be used as the entry point for running the package.
 
-This script is minimal and shouldn't conflict with customized shell environments: it only sets the conda environment for the framework and calls `mdtf_framework.py <https://github.com/NOAA-GFDL/MDTF-diagnostics/blob/main/mdtf_framework.py>`__, the python script which should be used as the entry point if a different installation method was used. In all cases the command-line options are as described here.
+This script is minimal and shouldn't conflict with customized shell environments:
+it only sets the conda environment for the framework and calls
+`mdtf_framework.py <https://github.com/NOAA-GFDL/MDTF-diagnostics/blob/main/mdtf_framework.py>`__,
+the python script which should be used as the entry point if a different installation method was used. In all cases
+the command-line options are as described here.
 
 Usage
 -----
@@ -20,19 +27,28 @@ Usage
     mdtf [options] [CASE_ROOT_DIR]
     mdtf info [TOPIC]
 
-The first form of the command runs the package's diagnostics on model data files in the directory ``CASE_ROOT_DIR``. The options, described below, can be set on the command line or in an input file specified with the ``-f``/``--input-file`` flag. An example of such an input file is provided at `src/default_tests.jsonc <https://github.com/NOAA-GFDL/MDTF-diagnostics/blob/main/src/default_tests.jsonc>`__.
+The first form of the command runs the package's diagnostics on model data files in the directory ``CASE_ROOT_DIR``.
+The options, described below, can be set on the command line or in an input file specified with the
+``-f``/``--input-file`` flag. An example of such an input file is provided at
+`src/default_tests.jsonc <https://github.com/NOAA-GFDL/MDTF-diagnostics/blob/main/src/default_tests.jsonc>`__.
 
-The second form of the command prints information about the installed diagnostics. To get a list of topics recognized by the command, run :console:`% mdtf info`.
+The second form of the command prints information about the installed diagnostics.
+To get a list of topics recognized by the command, run :console:`% mdtf info`.
 
 
 .. _ref-cli-options:
 
 Command-line options
 --------------------
 
-For long command line flags, words may be separated with hyphens (GNU standard) or with underscores (python variable name convention). For example, ``--file-transfer-timeout`` and ``--file_transfer_timeout`` are both recognized by the package as synonyms for the same setting.
+For long command line flags, words may be separated with hyphens (GNU standard) or with underscores
+(python variable name convention). For example, ``--file-transfer-timeout`` and ``--file_transfer_timeout``
+are both recognized by the package as synonyms for the same setting.
 
-If you're using site-specific functionality (via the ``--site`` flag, described below), additional options may be available beyond what is listed here: see the :doc:`site-specific documentation<site_toc>` for your site. In addition, your choice of site may set default values for these options; the default values and the location of the configuration file defining them are listed as part of running :console:`% mdtf --site <site_name> --help`.
+If you're using site-specific functionality (via the ``--site`` flag, described below),
+additional options may be available beyond what is listed here: see the :doc:`site-specific documentation<site_toc>`
+for your site. In addition, your choice of site may set default values for these options; the default values and the
+location of the configuration file defining them are listed as part of running :console:`% mdtf --site <site_name> --help`.
 
 General options
 +++++++++++++++

doc/sphinx/ref_data_sources.rst

@@ -3,17 +3,27 @@
 Model data sources
 ==================
 
-This section details how to select the input model data for the package to analyze. The command-line option for this functionality is the ``--data-manager`` flag, which selects a "data source": a code plug-in that implements all functionality needed to obtain model data needed by the PODs, based on user input:
+This section details how to select the input model data for the package to analyze.
+The command-line option for this functionality is the ``--data-manager`` flag, which selects a "data source":
+a code plug-in that implements all functionality needed to obtain model data needed by the PODs, based on user input:
 
 * An interface to query the remote store of data for the variables requested by the PODs, whether in the form of a file naming convention or an organized data catalog/database;
 * (Optional) heuristics for refining the query results in order to guarantee that all data selected came from the same model run;
 * The data transfer protocol to use for transferring the selected data to a local filesystem, for processing by the framework and by the PODs.
 
 Each data source may define its own specific command-line options, which are documented here. 
 
-The choice of data source determines where and how the data needed by the diagnostics is obtained, but doesn't specify anything about the data's contents. For that purpose we allow the user to specify a "variable naming :ref:`convention<ref-data-conventions>`" with the ``--convention`` flag. Also consult the :doc:`requirements<ref_data>` that input model data must satisfy in terms of file formats.
+The choice of data source determines where and how the data needed by the diagnostics is obtained,
+but doesn't specify anything about the data's contents. For that purpose we allow the user to specify a
+"variable naming :ref:`convention<ref-data-conventions>`" with the ``--convention`` flag.
+Also consult the :doc:`requirements<ref_data>` that input model data must satisfy in terms of file formats.
 
-There are currently three data sources implemented in the package, described below. If you're using site-specific functionality (via the ``--site`` flag), additional options may be available; see the :doc:`site-specific documentation<site_toc>` for your site. If you would like the package to support obtaining data from a source that hasn't currently been implemented, please make a request in the appropriate GitHub `discussion thread <https://github.com/NOAA-GFDL/MDTF-diagnostics/discussions/175>`__.
+There are currently three data sources implemented in the package, described below.
+If you're using site-specific functionality (via the ``--site`` flag), additional options may be available;
+see the :doc:`site-specific documentation<site_toc>` for your site.
+If you would like the package to support obtaining data from a source that hasn't currently been implemented,
+please make a request in the appropriate GitHub
+`discussion thread <https://github.com/NOAA-GFDL/MDTF-diagnostics/discussions/175>`__.
 
 .. _ref-data-source-localfile:
 
@@ -22,7 +32,10 @@ Sample model data source
 
 Selected via ``--data-manager="LocalFile"``. This is the default value for <*data-manager*>.
 
-This data source lets the package run on the sample model data provided with the package and installed by the user at <*MODEL_DATA_ROOT*>. Any additional data added by the user to this location (either by copying files, or through symlinks) will also be recognized, provided that it takes the form of one netCDF file per variable and that it follows the following file and subdirectory naming convention :
+This data source lets the package run on the sample model data provided with the package and installed by the user
+at <*MODEL_DATA_ROOT*>. Any additional data added by the user to this location
+(either by copying files, or through symlinks) will also be recognized, provided that it takes the form of one netCDF
+file per variable and that it follows the following file and subdirectory naming convention :
 
 <*MODEL_DATA_ROOT*>/<*dataset_name*>/<*frequency*>/<*dataset_name*>.<*variable_name*>.<*frequency*>.nc,