Repository: ESMCI/cime

Issue:
Document what users can put in their ~/.cime/config
We have lots of cool functionality that no ones knows about.


Discussion:
Could this be done for CESM2.0? I added it to that milestone, but take it off if it really can't.

Resolving patch:
diff --git a/doc/source/conf.py b/doc/source/conf.py
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -95,6 +95,8 @@
 #html_theme = 'alabaster'
 #html_theme = 'bizstyle'
 html_theme = 'classic'
+#html_theme = 'sphinx_rtd_theme'
+#html_theme = 'sphinxdoc'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/scripts/lib/CIME/utils.py b/scripts/lib/CIME/utils.py
--- a/scripts/lib/CIME/utils.py
+++ b/scripts/lib/CIME/utils.py
@@ -1624,14 +1624,14 @@ def _check_for_invalid_args(args):
             if " " in arg or arg.startswith("--"):
                 continue
             if arg.startswith("-") and len(arg) > 2:
-                sys.stderr.write( "WARNING: The {} argument is depricated. Multi-character arguments should begin with \"--\" and single character with \"-\"\n  Use --help for a complete list of available options\n".format(arg))
+                sys.stderr.write( "WARNING: The {} argument is deprecated. Multi-character arguments should begin with \"--\" and single character with \"-\"\n  Use --help for a complete list of available options\n".format(arg))
 
 def add_mail_type_args(parser):
-    parser.add_argument("--mail-user", help="email to be used for batch notification.")
+    parser.add_argument("--mail-user", help="Email to be used for batch notification.")
 
     parser.add_argument("-M", "--mail-type", action="append",
-                        help="when to send user email. Options are: never, all, begin, end, fail."
-                        "You can specify multiple types with either comma-separate args or multiple -M flags")
+                        help="When to send user email. Options are: never, all, begin, end, fail.\n"
+                        "You can specify multiple types with either comma-separated args or multiple -M flags.")
 
 def resolve_mail_type_args(args):
     if args.mail_type is not None:


Test patch:
diff --git a/doc/source/users_guide/testing.rst b/doc/source/users_guide/testing.rst
--- a/doc/source/users_guide/testing.rst
+++ b/doc/source/users_guide/testing.rst
@@ -6,8 +6,8 @@ Testing with create_test
 
 
 **create_test** is the tool we use to test cime-driven models. It can be used as an easy way to
-run a single basic test or an entire suite of tests.  create_test runs a test suite in parallel 
-for improved performance.  create_test is the driver behind the automated nightly testing of 
+run a single basic test or an entire suite of tests.  create_test runs a test suite in parallel
+for improved performance.  create_test is the driver behind the automated nightly testing of
 cime-driven models.
 
 Tests come in form::
@@ -25,24 +25,24 @@ a test.
 ======================= =====================================================================================
 TESTTYPE                Description
 ======================= =====================================================================================
-   ERS                  Exact restart from startup (default 6 days + 5 days) 
-                         Do an 11 day initial test - write a restart at day 6.    (file suffix: base) 
+   ERS                  Exact restart from startup (default 6 days + 5 days)
+                         Do an 11 day initial test - write a restart at day 6.    (file suffix: base)
 
-                         Do a 5 day restart test, starting from restart at day 6. (file suffix: rest) 
+                         Do a 5 day restart test, starting from restart at day 6. (file suffix: rest)
 
                          Compare component history files '.base' and '.rest' at day 11.
    ERS2                 Exact restart from startup  (default 6 days + 5 days).
                          Do an 11 day initial test without making restarts.     (file suffix: base)
- 
+
                          Do an 11 day restart test stopping at day 6 with a restart, then resuming from restart at day 6. (file suffix: rest)
- 
+
                          Compare component history files ".base" and ".rest" at day 11.
    ERT                  Exact restart from startup, default 2 month + 1 month (ERS with info DBUG = 1).
    IRT                  Exact restart from startup, (default 4 days + 7 days) with restart from interim file.
    ERIO                 Exact restart from startup with different PIO methods, (default 6 days + 5 days).
    ERR                  Exact restart from startup with resubmit, (default 4 days + 3 days).
    ERRI                 Exact restart from startup with resubmit, (default 4 days + 3 days). Tests incomplete logs option for st_archive.
-   ERI                  hybrid/branch/exact restart test, default (by default STOP_N is 22 days) 
+   ERI                  hybrid/branch/exact restart test, default (by default STOP_N is 22 days)
 
                         (1) ref1case
 
@@ -56,7 +56,7 @@ TESTTYPE                Description
 
                             Do a hybrid run for default 19 days running with ref1 restarts from day 3,
 
-                            and writing restarts at day 10. 
+                            and writing restarts at day 10.
 
                             ref2case is a clone of the main case.
 
@@ -71,7 +71,7 @@ TESTTYPE                Description
                             Short term archiving is off.
 
                         (4) case (Suffix base)
-       
+
                             Do a restart run from the branch run restarts for 4 days.
 
                             Compare component history files '.base' and '.hybrid' at day 19.
@@ -289,6 +289,8 @@ comment at the top of this file indicating that you add a test with
 this format: test>.<grid>.<compset>, and then there is a second
 argument for mods.
 
+.. _scripts_regression_tests:
+
 ========================
 Scripts regression tests
 ========================
diff --git a/scripts/create_test b/scripts/create_test
--- a/scripts/create_test
+++ b/scripts/create_test
@@ -1,20 +1,37 @@
 #!/usr/bin/env python
 
 """
-Script to run CIME tests.
-
-Runs single tests or test suites based on either the input list or the testname or based
-on an xml testlist if the xml suboption is provided.
-
-If this tool is missing any feature that you need, please notify jgfouca@sandia.gov.
+Script to create, build and run CIME tests. This script can:
+
+1) Run a single test, or more than one test
+   ./create_test TESTNAME
+   ./create_test TESTNAME1 TESTNAME2 ...
+2) Run a test suite from a text file with one test per line
+   ./create_test -f TESTFILE
+3) Run an E3SM test suite:
+  Below, a suite name, SUITE, is defined in $CIMEROOT/scripts/lib/get_tests.py
+  - Run a single suite
+   ./create_test SUITE
+  - Run two suites
+   ./create_test SUITE1 SUITE2
+  - Run all tests in a suite except for one
+   ./create_test SUITE ^TESTNAME
+  - Run all tests in a suite except for tests that are in another suite
+   ./create_test SUITE1 ^SUITE2
+4) Run a CESM test suite(s):
+   ./create_test --xml-category XML_CATEGORY [--xml-machine XML_MACHINE] [--xml-compiler XML_COMPILER] [ --xml-testlist XML_TESTLIST]
+
+If this tool is missing any feature that you need, please add an issue on
+https://github.com/ESMCI/cime
 """
 from Tools.standard_script_setup import *
 
 import get_tests
 from CIME.test_scheduler import TestScheduler, RUN_PHASE
-from CIME.utils import expect, convert_to_seconds, compute_total_time, convert_to_babylonian_time, run_cmd_no_fail, get_cime_config
-from CIME.XML.machines import Machines
-from CIME.case import Case
+from CIME.utils          import expect, convert_to_seconds, compute_total_time, convert_to_babylonian_time, run_cmd_no_fail, get_cime_config
+from CIME.XML.machines   import Machines
+from CIME.case           import Case
+from argparse            import RawTextHelpFormatter
 
 import argparse, math, glob
 
@@ -23,50 +40,11 @@ logger = logging.getLogger(__name__)
 ###############################################################################
 def parse_command_line(args, description):
 ###############################################################################
-    model = CIME.utils.get_model()
 
-    if model == "cesm":
-        help_str = \
-"""
-{0} --xml-category [CATEGORY] [--xml-machine ...] [--xml-compiler ...] [ --xml-testlist ...]
-OR
-{0} --help
-
-\033[1mEXAMPLES:\033[0m
-    \033[1;32m# Run all tests in the xml prealpha category and cheyenne machine \033[0m
-    > {0} --xml-machine cheyenne --xml-category prealpha
-""".format(os.path.basename(args[0]))
-
-    else:
-        help_str = \
-"""
-{0} <TEST|SUITE> [<TEST|SUITE> ...] [--verbose]
-OR
-{0} --help
-
-\033[1mEXAMPLES:\033[0m
-    \033[1;32m# Run single test \033[0m
-    > {0} <TESTNAME>
-
-    \033[1;32m# Run test suite \033[0m
-    > {0} <SUITE>
-
-    \033[1;32m# Run two tests \033[0m
-    > {0} <TESTNAME1> <TESTNAME2>
-
-    \033[1;32m# Run two suites \033[0m
-    > {0} <SUITE1> <SUITE2>
-
-    \033[1;32m# Run all tests in a suite except for one \033[0m
-    > {0} <SUITE> ^<TESTNAME>
-
-    \033[1;32m# Run all tests in a suite except for tests that are in another suite \033[0m
-    > {0} <SUITE1> ^<SUITE2>
-""".format(os.path.basename(args[0]))
+    model = CIME.utils.get_model()
 
-    parser = argparse.ArgumentParser(usage=help_str,
-                                     description=description,
-                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+    parser = argparse.ArgumentParser(description=description,
+                                     formatter_class=RawTextHelpFormatter)
 
     CIME.utils.setup_standard_logging_options(parser)
 
@@ -82,7 +60,8 @@ OR
                         help="Do not setup generated tests, implies --no-build and --no-run")
 
     parser.add_argument("-u", "--use-existing", action="store_true",
-                        help="Use pre-existing case directories they will pick up at the latest PEND state or re-run the first failed state. Requires test-id")
+                        help="Use pre-existing case directories they will pick up at the "
+                        "\nlatest PEND state or re-run the first failed state. Requires test-id")
 
     default = get_default_setting(config, "SAVE_TIMING", False, check_main=False)
 
@@ -92,21 +71,21 @@ OR
 
     parser.add_argument("--no-batch", action="store_true",
                         help="Do not submit jobs to batch system, run locally."
-                        " If false, will default to machine setting.")
+                        "\nIf false, this will default to machine setting.")
 
     default = get_default_setting(config, "SINGLE_SUBMIT", False, check_main=False)
 
     parser.add_argument("--single-submit", action="store_true",
                         default=default,
-                        help="Use a single interactive allocation to run all the tests. "
-                        "Can drastically reduce queue waiting. Only makes sense on batch machines.")
+                        help="Use a single interactive allocation to run all the tests. This can "
+                        "\ndrastically reduce queue waiting but only makes sense on batch machines.")
 
     default = get_default_setting(config, "TEST_ROOT", None, check_main=False)
 
     parser.add_argument("-r", "--test-root",
                         default=default,
-                        help="Where test cases will be created."
-                        " Will default to output root as defined in the config_machines file")
+                        help="Where test cases will be created. The default is output root"
+                        "\nas defined in the config_machines file")
 
     default = get_default_setting(config, "OUTPUT_ROOT", None, check_main=False)
 
@@ -118,62 +97,59 @@ OR
 
     parser.add_argument("--baseline-root",
                         default=default,
-                        help="Specifies an root directory for baseline"
-                        "datasets used for Bit-for-bit generate/compare"
-                        "testing.")
+                        help="Specifies a root directory for baseline datasets that will "
+                        "\nbe used for Bit-for-bit generate and/or compare testing.")
 
     default = get_default_setting(config, "CLEAN", False, check_main=False)
 
     parser.add_argument("--clean", action="store_true",
                         default=default,
-                        help="Specifies if tests should be cleaned after run. If set, "
-                        "all object executables, and data files will"
-                        " be removed after tests are run")
+                        help="Specifies if tests should be cleaned after run. If set, all object"
+                        "\nexecutables and data files will be removed after the tests are run.")
 
     default = get_default_setting(config, "MACHINE", None, check_main=True)
 
     parser.add_argument("-m", "--machine",
                         default=default,
-                        help="The machine for which to build tests, this machine must be defined"
-                        " in the config_machines.xml file for the given model. "
-                        "Default is to match the name of the machine in the test name or "
-                        "the name of the machine this script is run on to the "
-                        "NODENAME_REGEX field in config_machines.xml. This option is highly "
-                        "unsafe and should only be used if you know what you're doing.")
+                        help="The machine for creating and building tests. This machine must be defined"
+                        "\nin the config_machines.xml file for the given model. The default is to "
+                        "\nto match the name of the machine in the test name or the name of the "
+                        "\nmachine this script is run on to the NODENAME_REGEX field in "
+                        "\nconfig_machines.xml. WARNING: This option is highly unsafe and should "
+                        "\nonly be used if you are an expert.")
 
     default = get_default_setting(config, "MPILIB", None, check_main=True)
 
     parser.add_argument("--mpilib",
                         default=default,
-                        help="Specify the mpilib. "
-                        "To see list of supported mpilibs for each machine, use the utility query_config in this directory. "
-                        "The default is the first listing in MPILIBS in config_machines.xml")
+                        help="Specify the mpilib. To see list of supported MPI libraries for each machine, "
+                        "\ninvoke ./query_config. The default is the first listing .")
 
     if model == "cesm":
         parser.add_argument("-c", "--compare",
-                            help="While testing, compare baselines"
-                            "  against the given compare directory ")
+                            help="While testing, compare baselines against the given compare directory. ")
 
         parser.add_argument("-g", "--generate",
-                            help="While testing, generate baselines"
-                            " to the given generate directory; "
-                            "this can also be done after the fact with bless_test_results")
+                            help="While testing, generate baselines in the given generate directory. "
+                            "\nNOTE: this can also be done after the fact with bless_test_results")
 
         parser.add_argument("--xml-machine",
-                            help="Use this machine key in the lookup in testlist.xml, default is all if any --xml- argument is used")
+                            help="Use this machine key in the lookup in testlist.xml. "
+                            "\nThe default is all if any --xml- argument is used.")
 
         parser.add_argument("--xml-compiler",
-                            help="Use this compiler key in the lookup in testlist.xml, default is all if any --xml- argument is used")
+                            help="Use this compiler key in the lookup in testlist.xml. "
+                            "\nThe default is all if any --xml- argument is used.")
 
         parser.add_argument("--xml-category",
-                            help="Use this category key in the lookup in testlist.xml, default is all if any --xml- argument is used")
+                            help="Use this category key in the lookup in testlist.xml. "
+                            "\nThe default is all if any --xml- argument is used.")
 
         parser.add_argument("--xml-testlist",
-                            help="Use this testlist to lookup tests, default specified in config_files.xml")
+                            help="Use this testlist to lookup tests.The default is specified in config_files.xml")
 
         parser.add_argument("testargs", nargs="*",
-                            help="Tests to run."
-                            " Testname form is TEST.GRID.COMPSET[.MACHINE_COMPILER]")
+                            help="Tests to run. Testname form is TEST.GRID.COMPSET[.MACHINE_COMPILER]")
 
     else:
 
@@ -182,53 +158,51 @@ OR
                             " Testname form is TEST.GRID.COMPSET[.MACHINE_COMPILER]")
 
         parser.add_argument("-b", "--baseline-name",
-                            help="If comparing or generating baselines,"
-                            " use this directory under baseline root. "
-                            "Default will be current branch name.")
+                            help="If comparing or generating baselines, use this directory under baseline root. "
+                            "\nDefault will be current branch name.")
 
         parser.add_argument("-c", "--compare", action="store_true",
                             help="While testing, compare baselines")
 
         parser.add_argument("-g", "--generate", action="store_true",
-                            help="While testing, generate baselines; "
-                            "this can also be done after the fact with bless_test_results")
+                            help="While testing, generate baselines. "
+                            "\nNOTE: this can also be done after the fact with bless_test_results")
 
     default = get_default_setting(config, "COMPILER", None, check_main=True)
 
     parser.add_argument("--compiler",
                         default=default,
-                        help="Compiler to use to build cime.  Default will be the name in"
-                        " the Testnames or the default defined for the machine.")
+                        help="Compiler for building cime. Default will be the name in the "
+                        "\nTestname or the default defined for the machine.")
 
     parser.add_argument("-n", "--namelists-only", action="store_true",
                         help="Only perform namelist actions for tests")
 
     parser.add_argument("-p", "--project",
                         help="Specify a project id for the case (optional)."
-                        "Used for accounting when on a batch system."
-                        "The default is user-specified environment variable PROJECT")
+                        "\nUsed for accounting when on a batch system."
+                        "\nThe default is user-specified environment variable PROJECT")
 
     parser.add_argument("-t", "--test-id",
-                        help="Specify an 'id' for the test. This is simply a "
-                        "string that is appended to the end of a test name. "
-                        "If no test-id is specified, then a time stamp plus random "
-                        "string will be used (ensuring a high probability of uniqueness). "
-                        "If test-id is specified, it is the user's responsibility to ensure "
-                        "that each run of create_test uses a unique test-id. "
-                        "(All sorts of problems can occur if you use the same test-id twice "
-                        "on the same file system, even if the test lists are completely different.)")
+                        help="Specify an 'id' for the test. This is simply a string that is appended "
+                        "\nto the end of a test name. If no test-id is specified, a time stamp plus a "
+                        "\nrandom string will be used (ensuring a high probability of uniqueness). "
+                        "\nIf a test-id is specified, it is the user's responsibility to ensure that "
+                        "\neach run of create_test uses a unique test-id. WARNING: problems will occur "
+                        "\nif you use the same test-id twice on the same file system, even if the test "
+                        "\nlists are completely different.")
 
     default = get_default_setting(config, "PARALLEL_JOBS", None, check_main=False)
 
     parser.add_argument("-j", "--parallel-jobs", type=int, default=default,
-                        help="Number of tasks create_test should perform simultaneously. Default "
-                        "will be min(num_cores, num_tests).")
+                        help="Number of tasks create_test should perform simultaneously. The default "
+                        "\n is min(num_cores, num_tests).")
 
     default = get_default_setting(config, "PROC_POOL", None, check_main=False)
 
     parser.add_argument("--proc-pool", type=int, default=default,
-                        help="The size of the processor pool that create_test can use. Default "
-                        "is MAX_MPITASKS_PER_NODE + 25 percent.")
+                        help="The size of the processor pool that create_test can use. The default is "
+                        "\nMAX_MPITASKS_PER_NODE + 25 percent.")
 
     default = os.getenv("CIME_GLOBAL_WALLTIME")
     if default is None:
@@ -236,7 +210,7 @@ OR
 
     parser.add_argument("--walltime", default=default,
                         help="Set the wallclock limit for all tests in the suite. "
-                        "Can use env var CIME_GLOBAL_WALLTIME to set this for all test.")
+                        "\nUse the variable CIME_GLOBAL_WALLTIME to set this for all tests.")
 
     default = get_default_setting(config, "JOB_QUEUE", None, check_main=True)
 
@@ -250,10 +224,9 @@ OR
 
     parser.add_argument("-o", "--allow-baseline-overwrite", action="store_true",
                         default=default,
-                        help="If the --generate option is given, then by default "
-                        "an attempt to overwrite an existing baseline directory "
-                        "will raise an error. Specifying this option allows "
-                        "existing baseline directories to be silently overwritten.")
+                        help="If the --generate option is given, then an attempt to overwrite "
+                        "\nan existing baseline directory will raise an error. WARNING: Specifying this "
+                        "\noption will allow existing baseline directories to be silently overwritten.")
 
     default = get_default_setting(config, "WAIT", False, check_main=False)
 
@@ -292,9 +265,8 @@ OR
     default = get_default_setting(config, "PESFILE", None, check_main=True)
 
     parser.add_argument("--pesfile",default=default,
-                        help="Full pathname of an optional pes specification "
-                        "file. The file can follow either the config_pes.xml or "
-                        "the env_mach_pes.xml format.")
+                        help="Full pathname of an optional pes specification file. The file"
+                        "\ncan follow either the config_pes.xml or the env_mach_pes.xml format.")
 
     default = get_default_setting(config, "RETRY", 0, check_main=False)