cli: improve command descriptions

* Shorten/simplify the first line of a couple of command descriptions.
* Add `cylc clean` and `cylc gui` to the list of "selected sub-commands"
  which are listed by default in the `cylc help` page.
* Ensure there is one newline after each description (fixes spacing
  issue with the auto-added ID help).

cylc/flow/scripts/broadcast.py

@@ -77,7 +77,8 @@
 
 Broadcast cannot change [runtime] inheritance.
 
-See also 'cylc reload' - reload a modified workflow definition at run time."""
+See also 'cylc reload' - reload a modified workflow definition at run time.
+"""
 
 from ansimarkup import parse as cparse
 from functools import partial

cylc/flow/scripts/check_versions.py

@@ -31,7 +31,8 @@
 
 Use -v/--verbose to see the command invoked to determine the remote version
 (all remote cylc command invocations will be of the same form, which may be
-site dependent -- see cylc global config documentation."""
+site dependent -- see cylc global config documentation.
+"""
 
 import sys
 from typing import TYPE_CHECKING

cylc/flow/scripts/clean.py

@@ -18,7 +18,10 @@
 
 """cylc clean [OPTIONS] ARGS
 
-Remove a stopped workflow from the local scheduler filesystem and remote hosts.
+Delete a stopped workflow.
+
+Remove workflow files from the local scheduler filesystem and and remote hosts
+the workflow was installed on.
 
 NOTE: this command is intended for workflows installed with `cylc install`. If
 this is run for a workflow that was instead written directly in ~/cylc-run and
@@ -54,7 +57,6 @@
 
   # Only remove the workflow on remote install targets
   $ cylc clean foo/bar --remote-only
-
 """
 
 import asyncio

cylc/flow/scripts/cycle_point.py

@@ -51,7 +51,8 @@
   $ export CYLC_TASK_CYCLE_POINT=2010-08
   $ export MYTEMPLATE=foo-CCYY-MM.nc
   $ cylc cycle-point --offset-years=2 --template=MYTEMPLATE
-  foo-2012-08.nc"""
+  foo-2012-08.nc
+"""
 
 import os
 import sys

cylc/flow/scripts/cylc.py

@@ -430,24 +430,28 @@ def cli_help():
     # modern terminal)
     from colorama import init as color_init
     color_init(autoreset=True, strip=False)
+    commands = [
+        'clean',
+        'hold',
+        'install',
+        'kill',
+        'pause',
+        'play',
+        'release',
+        'scan',
+        'stop',
+        'trigger',
+        'tui',
+        'validate',
+    ]
+    if 'gui' in COMMANDS:
+        commands.append('gui')
     print(USAGE)
     print('Selected Sub-Commands:')
     print_command_list(
         # print a short list of the main cylc commands
-        commands=[
-            'hold',
-            'install',
-            'kill',
-            'pause',
-            'play',
-            'release',
-            'scan',
-            'stop',
-            'trigger',
-            'tui',
-            'validate'
-        ],
-        indent=2
+        commands=commands,
+        indent=2,
     )
     print('\nTo see all commands run: cylc help all')
     sys.exit(0)

cylc/flow/scripts/diff.py

@@ -26,7 +26,8 @@
 after inlining has occurred.
 
 Files in the workflow bin directory and other sub-directories of the
-run directory are not currently differenced."""
+run directory are not currently differenced.
+"""
 
 import sys
 from typing import TYPE_CHECKING

cylc/flow/scripts/dump.py

@@ -32,7 +32,8 @@
   $ cylc dump --tasks --sort WORKFLOW_ID | grep running
 
   # Display the state of all tasks in a particular cycle point:
-  $ cylc dump -t WORKFLOW_ID | grep 2010082406"""
+  $ cylc dump -t WORKFLOW_ID | grep 2010082406
+"""
 
 from graphene.utils.str_converters import to_snake_case
 import json

cylc/flow/scripts/ext_trigger.py

@@ -36,7 +36,8 @@
 
 Use the retry options in case the target workflow is down or out of contact.
 
-Note: to manually trigger a task use 'cylc trigger', not this command."""
+Note: to manually trigger a task use 'cylc trigger', not this command.
+"""
 
 from time import sleep
 from typing import TYPE_CHECKING

cylc/flow/scripts/get_resources.py

@@ -36,7 +36,8 @@
     $ cylc get-resources tutorial/runtime-tutorial
 
     # copy all of the tutorials to your "source" directory:
-    $ cylc get-resources tutorial"""
+    $ cylc get-resources tutorial
+"""
 
 import sys
 

cylc/flow/scripts/get_workflow_contact.py

@@ -18,7 +18,8 @@
 
 """cylc get-workflow-contact [OPTIONS] ARGS
 
-Print contact information of a running workflow."""
+Print contact information of a running workflow.
+"""
 
 from typing import TYPE_CHECKING
 

cylc/flow/scripts/install.py

@@ -78,7 +78,6 @@
 
 The same workflow can be installed with multiple names; this results in
 multiple workflow run directories that link to the same workflow definition.
-
 """
 
 from pathlib import Path

cylc/flow/scripts/jobs_kill.py

@@ -21,8 +21,8 @@
 Read job status files to obtain the names of the job runners and the job IDs
 in the runners. Invoke the relevant job runner commands to ask the job runners
 to terminate the jobs.
-
 """
+
 from cylc.flow.job_runner_mgr import JobRunnerManager
 from cylc.flow.option_parsers import CylcOptionParser as COP
 from cylc.flow.terminal import cli_function

cylc/flow/scripts/jobs_poll.py

@@ -20,8 +20,8 @@
 
 Read job status files to obtain the statuses of the jobs. If necessary, Invoke
 the relevant job runner commands to ask the job runners for more statuses.
-
 """
+
 from cylc.flow.job_runner_mgr import JobRunnerManager
 from cylc.flow.option_parsers import CylcOptionParser as COP
 from cylc.flow.terminal import cli_function

cylc/flow/scripts/jobs_submit.py

@@ -20,8 +20,8 @@
 
 Submit task jobs to relevant job runners.
 On a remote job host, this command reads the job files from STDIN.
-
 """
+
 from cylc.flow.option_parsers import CylcOptionParser as COP
 from cylc.flow.terminal import cli_function
 from cylc.flow.job_runner_mgr import JobRunnerManager

cylc/flow/scripts/list.py

@@ -27,7 +27,8 @@
 groupings that are collapsible in cylc visualisation tools.
 
 To visualize the full multiple inheritance hierarchy use:
-  $ cylc graph -n"""
+  $ cylc graph -n
+"""
 
 import os
 import sys

cylc/flow/scripts/reload.py

@@ -50,7 +50,8 @@
 to the reload (only changes to the flow.cylc file itself are reloaded).
 
 If the modified workflow definition does not parse, failure to reload will
-be reported but no harm will be done to the running workflow."""
+be reported but no harm will be done to the running workflow.
+"""
 
 from functools import partial
 from typing import TYPE_CHECKING

cylc/flow/scripts/remote_init.py

@@ -33,7 +33,6 @@
         - Print task_remote_cmd.REMOTE_INIT_DONE
     1:
         On failure.
-
 """
 
 from cylc.flow.option_parsers import CylcOptionParser as COP

cylc/flow/scripts/remote_tidy.py

@@ -21,7 +21,6 @@
 Remove ".service/contact" from a task remote (i.e. a [owner@]host).
 Remove ".service" directory on the remote if emptied.
 Remove authentication keys.
-
 """
 
 from cylc.flow.option_parsers import CylcOptionParser as COP

cylc/flow/scripts/report_timings.py

@@ -46,7 +46,6 @@
 
 For long-running or large workflows (i.e. workflows with many task events),
 the database query to obtain the timing information may take some time.
-
 """
 
 import collections

cylc/flow/scripts/set_outputs.py

@@ -18,7 +18,9 @@
 
 """cylc set-outputs [OPTIONS] ARGS
 
-Artificially mark task outputs as completed and spawn downstream tasks that
+Artificially satisfy task outputs.
+
+Mark task outputs as completed and spawn downstream tasks that
 depend on those outputs. By default it marks tasks as succeeded.
 
 This allows you to manually intervene with Cylc's scheduling algorithm by
@@ -43,7 +45,6 @@
   $ cylc set-outputs --flow=3 --output=x my_flow//1/foo
 
 Use --output multiple times to spawn off of several outputs at once.
-
 """
 
 from functools import partial

cylc/flow/scripts/stop.py

@@ -59,7 +59,8 @@
 --now is used.
 
 This command exits immediately unless --max-polls is greater than zero, in
-which case it polls to wait for workflow shutdown."""
+which case it polls to wait for workflow shutdown.
+"""
 
 from functools import partial
 import sys

cylc/flow/scripts/trigger.py

@@ -19,11 +19,9 @@
 
 Trigger tasks - i.e. tell them to run even if they are not ready.
 
-Triggering an unqueued waiting task queues it, regardless of prerequisites.
-
-Triggering a queued waiting task submits it, regardless of queue limiting.
-
-Triggering a submitted or running task has no effect (already triggered).
+* Triggering an unqueued waiting task queues it, regardless of prerequisites.
+* Triggering a queued waiting task submits it, regardless of queue limiting.
+* Triggering a submitted or running task has no effect (already triggered).
 
 Incomplete and active-waiting tasks in the n=0 window already belong to a flow.
 Triggering them queues them to run (or rerun) in the same flow;

cylc/flow/scripts/validate.py

@@ -22,7 +22,8 @@
 
 If the workflow definition uses include-files reported line numbers
 will correspond to the inlined version seen by the parser; use
-'cylc view -i,--inline WORKFLOW' for comparison."""
+'cylc view -i,--inline WORKFLOW' for comparison.
+"""
 
 from ansimarkup import parse as cparse
 from optparse import Values