Split out CDash options to a separate help document (#13704)

Prevent `spack help install` from getting too cluttered with CDash-specific documentation.

lib/spack/spack/cmd/install.py

@@ -150,39 +150,63 @@ def setup_parser(subparser):
         default=None,
         help="filename for the log file. if not passed a default will be used"
     )
+    subparser.add_argument(
+        '--help-cdash',
+        action='store_true',
+        help="Show usage instructions for CDash reporting"
+    )
+    add_cdash_args(subparser, False)
+    arguments.add_common_arguments(subparser, ['yes_to_all'])
+
+
+def add_cdash_args(subparser, add_help):
+    cdash_help = {}
+    if add_help:
+        cdash_help['upload-url'] = "CDash URL where reports will be uploaded"
+        cdash_help['build'] = """The name of the build that will be reported to CDash.
+Defaults to spec of the package to install."""
+        cdash_help['site'] = """The site name that will be reported to CDash.
+Defaults to current system hostname."""
+        cdash_help['track'] = """Results will be reported to this group on CDash.
+Defaults to Experimental."""
+        cdash_help['buildstamp'] = """Instead of letting the CDash reporter prepare the
+buildstamp which, when combined with build name, site and project,
+uniquely identifies the build, provide this argument to identify
+the build yourself.  Format: %%Y%%m%%d-%%H%%M-[cdash-track]"""
+    else:
+        cdash_help['upload-url'] = argparse.SUPPRESS
+        cdash_help['build'] = argparse.SUPPRESS
+        cdash_help['site'] = argparse.SUPPRESS
+        cdash_help['track'] = argparse.SUPPRESS
+        cdash_help['buildstamp'] = argparse.SUPPRESS
+
     subparser.add_argument(
         '--cdash-upload-url',
         default=None,
-        help="CDash URL where reports will be uploaded"
+        help=cdash_help['upload-url']
     )
     subparser.add_argument(
         '--cdash-build',
         default=None,
-        help="""The name of the build that will be reported to CDash.
-Defaults to spec of the package to install."""
+        help=cdash_help['build']
     )
     subparser.add_argument(
         '--cdash-site',
         default=None,
-        help="""The site name that will be reported to CDash.
-Defaults to current system hostname."""
+        help=cdash_help['site']
     )
+
     cdash_subgroup = subparser.add_mutually_exclusive_group()
     cdash_subgroup.add_argument(
         '--cdash-track',
         default='Experimental',
-        help="""Results will be reported to this group on CDash.
-Defaults to Experimental."""
+        help=cdash_help['track']
     )
     cdash_subgroup.add_argument(
         '--cdash-buildstamp',
         default=None,
-        help="""Instead of letting the CDash reporter prepare the
-buildstamp which, when combined with build name, site and project,
-uniquely identifies the build, provide this argument to identify
-the build yourself.  Format: %%Y%%m%%d-%%H%%M-[cdash-track]"""
+        help=cdash_help['buildstamp']
     )
-    arguments.add_common_arguments(subparser, ['yes_to_all'])
 
 
 def default_log_file(spec):
@@ -221,6 +245,12 @@ def install_spec(cli_args, kwargs, abstract_spec, spec):
 
 
 def install(parser, args, **kwargs):
+    if args.help_cdash:
+        parser = argparse.ArgumentParser()
+        add_cdash_args(parser, True)
+        parser.print_help()
+        return
+
     if not args.package and not args.specfiles:
         # if there are no args but an active environment or spack.yaml file
         # then install the packages from it.

lib/spack/spack/test/cmd/install.py

@@ -664,3 +664,18 @@ def test_install_only_dependencies_of_all_in_env(
             assert not os.path.exists(root.prefix)
             for dep in root.traverse(root=False):
                 assert os.path.exists(dep.prefix)
+
+
+def test_install_help_does_not_show_cdash_options(capsys):
+    """Make sure `spack install --help` does not describe CDash arguments"""
+    with pytest.raises(SystemExit):
+        install('--help')
+        captured = capsys.readouterr()
+        assert 'CDash URL' not in captured.out
+
+
+def test_install_help_cdash(capsys):
+    """Make sure `spack install --help-cdash` describes CDash arguments"""
+    install_cmd = SpackCommand('install')
+    out = install_cmd('--help-cdash')
+    assert 'CDash URL' in out

share/spack/spack-completion.bash

@@ -641,7 +641,7 @@ function _spack_install {
                     -v --verbose --fake --only-concrete -f --file --clean
                     --dirty --test --run-tests --log-format --log-file
                     --cdash-upload-url --cdash-build --cdash-site --cdash-track
-                    --cdash-buildstamp -y --yes-to-all" -- "$cur"
+                    --cdash-buildstamp --help-cdash -y --yes-to-all" -- "$cur"
     else
         compgen -W "$(_all_packages)" -- "$cur"
     fi