uid: update cli docs with automatic multi workflow/task instructions

cylc/flow/option_parsers.py

@@ -22,6 +22,7 @@
 import re
 from ansimarkup import parse as cparse
 import sys
+from textwrap import dedent
 from typing import Any, Dict, Optional, List, Tuple
 
 from cylc.flow import LOG, RSYNC_LOG
@@ -121,45 +122,41 @@ class CylcOptionParser(OptionParser):
 
     """Common options for all cylc CLI commands."""
 
-    # TODO v
-
-    # Shared text for commands which can, & cannot, glob on cycle points:
-    MULTI_USAGE_TEMPLATE = """{0}
-
-For example, to match:{1}"""
-    # Help text either including or excluding globbing on cycle points:
-    WITH_CYCLE_GLOBS = """
-One or more TASK_GLOBs can be given to match task instances in the current task
-pool, by task or family name pattern, cycle point pattern, and task state.
-* [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE]
-* [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE]
-* TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE]
-* FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE]"""
-    WITHOUT_CYCLE_GLOBS = """
-TASK_GLOB matches task or family names at a given cycle point.
-* CYCLE-POINT/TASK-NAME-GLOB
-* CYCLE-POINT/FAMILY-NAME-GLOB
-* TASK-NAME-GLOB.CYCLE-POINT
-* FAMILY-NAME-GLOB.CYCLE-POINT"""
-    WITH_CYCLE_EXAMPLES = """
-* all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z'
-* all tasks in the submitted status: ':submitted'
-* running 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:running' or
-  '*0000Z/foo*:running'
-* waiting tasks in 'BAR' family: '*/BAR:waiting' or 'BAR.*:waiting'
-* submitted tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:submitted' or
-  'BA[RZ].*:submitted'"""
-    WITHOUT_CYCLE_EXAMPLES = """
-* all tasks: '20200202T0000Z/*' or '*.20200202T0000Z'
-* all tasks named model_N for some character N: '20200202T0000Z/model_?' or
-  'model_?.20200202T0000Z'
-* all tasks in 'BAR' family: '20200202T0000Z/BAR' or 'BAR.20200202T0000Z'
-* all tasks in 'BAR' or 'BAZ' families: '20200202T0000Z/BA[RZ]' or
-  'BA[RZ].20200202T0000Z'"""
-    MULTITASKCYCLE_USAGE = MULTI_USAGE_TEMPLATE.format(
-        WITH_CYCLE_GLOBS, WITH_CYCLE_EXAMPLES)
-    MULTITASK_USAGE = MULTI_USAGE_TEMPLATE.format(
-        WITHOUT_CYCLE_GLOBS, WITHOUT_CYCLE_EXAMPLES)
+    MULTITASK_USAGE = cparse(dedent('''
+        This command can operate on multiple tasks, globs and selectors may
+        be used:
+            Multiple Tasks:
+                <dim># Operate on two tasks</dim>
+                workflow //cycle-1/task-1 //cycle-2/task-2
+
+            Globs (note: globs should be quoted and only match active tasks):
+                <dim># Match any the active task "foo" in all cycles</dim>
+                '//*/foo'
+
+                <dim># Match the tasks "foo-1" and "foo-2"</dim>
+                '//*/foo-[12]'
+
+            Selectors (note: selectors only match active tasks):
+                <dim># match all failed tasks in cycle "1"</dim>
+                //1:failed
+
+            See `cylc help id` for more details.
+    '''))
+    MULTIWORKFLOW_USAGE = cparse(dedent('''
+        This command can operate on multiple workflows, globs may also be used:
+            Multiple Workflows:
+                <dim># Operate on two workflows</dim>
+                workflow-1 workflow-2
+
+            Globs (note: globs should be quoted):
+                <dim># Match all workflows</dim>
+                '*'
+
+                <dim># Match the workflows foo-1, foo-2</dim>
+                'foo-[12]'
+
+            See `cylc help id` for more details.
+    '''))
 
     def __init__(
         self,
@@ -168,7 +165,7 @@ def __init__(
         comms: bool = False,
         jset: bool = False,
         multitask: bool = False,
-        multitask_nocycles: bool = False,
+        multiworkflow: bool = False,
         prep: bool = False,
         auto_add: bool = True,
         icp: bool = False,
@@ -191,10 +188,11 @@ def __init__(
             # (This catches both '--color=never' and '--color never'.)
             usage = format_shell_examples(usage)
 
+        if multiworkflow:
+            usage += self.MULTIWORKFLOW_USAGE
         if multitask:
-            usage += self.MULTITASKCYCLE_USAGE
-        elif multitask_nocycles:  # glob on task names but not cycle points
             usage += self.MULTITASK_USAGE
+
         args = ""
         self.n_compulsory_args = 0
         self.n_optional_args = 0

cylc/flow/scripts/broadcast.py

@@ -230,7 +230,8 @@ def get_option_parser():
     parser = COP(
         __doc__,
         comms=True,
-        argdoc=[('ID [ID ...]', 'Workflow ID(s)')],
+        multiworkflow=True,
+        argdoc=[('WORKFLOW_ID [WORKFLOW_ID ...]', 'Workflow ID(s)')],
     )
 
     parser.add_option(

cylc/flow/scripts/clean.py

@@ -77,6 +77,7 @@
 def get_option_parser():
     parser = COP(
         __doc__,
+        multiworkflow=True,
         argdoc=[('WORKFLOW_ID [WORKFLOW_ID ...]', 'Workflow IDs')],
         segregated_log=True,
     )

cylc/flow/scripts/client.py

@@ -44,7 +44,7 @@
 
 def get_option_parser():
     parser = COP(__doc__, comms=True, argdoc=[
-        ('ID', 'Workflow ID'),
+        ('WORKFLOW_ID', 'Workflow ID'),
         ('METHOD', 'Network API function name')])
 
     parser.add_option(

cylc/flow/scripts/config.py

@@ -68,7 +68,7 @@
 def get_option_parser():
     parser = COP(
         __doc__,
-        argdoc=[("[ID]", "Workflow ID or path to source")],
+        argdoc=[("[WORKFLOW_ID]", "Workflow ID or path to source")],
         jset=True, icp=True
     )
 

cylc/flow/scripts/cylc.py

@@ -64,10 +64,10 @@ def get_version(long=False):
 Command Abbreviation:
   # Commands can be abbreviated as long as there is no ambiguity in
   # the abbreviated command:
-  $ cylc trigger WORKFLOW TASK    # trigger TASK in WORKFLOW
-  $ cylc trig WORKFLOW TASK       # ditto
-  $ cylc tr WORKFLOW TASK         # ditto
-  $ cylc t                        # Error: ambiguous command
+  $ cylc trigger WORKFLOW//CYCLE/TASK    # trigger TASK in WORKFLOW
+  $ cylc trig WORKFLOW//CYCLE/TASK       # ditto
+  $ cylc tr WORKFLOW//CYCLE/TASK         # ditto
+  $ cylc t                               # Error: ambiguous command
 
 Cylc IDs:
   Cylc IDs take the form:

cylc/flow/scripts/diff.py

@@ -118,8 +118,8 @@ def get_option_parser():
     parser = COP(
         __doc__, jset=True, prep=True, icp=True,
         argdoc=[
-            ('ID_1', 'Workflow ID or path to source'),
-            ('ID_2', 'Workflow ID or path to source')
+            ('WORKFLOW_ID_1', 'Workflow ID or path to source'),
+            ('WORKFLOW_ID_2', 'Workflow ID or path to source')
         ]
     )
 

cylc/flow/scripts/dump.py

@@ -22,17 +22,17 @@
 
 For command line monitoring:
 * `cylc tui`
-* `watch cylc dump WORKFLOW` works for small simple workflows
+* `watch cylc dump WORKFLOW_ID` works for small simple workflows
 
 For more information about a specific task, such as the current state of
 its prerequisites and outputs, see 'cylc show'.
 
 Examples:
   # Display the state of all running tasks, sorted by cycle point:
-  $ cylc dump --tasks --sort WORKFLOW | grep running
+  $ cylc dump --tasks --sort WORKFLOW_ID | grep running
 
   # Display the state of all tasks in a particular cycle point:
-  $ cylc dump -t WORKFLOW | grep 2010082406"""
+  $ cylc dump -t WORKFLOW_ID | grep 2010082406"""
 
 from graphene.utils.str_converters import to_snake_case
 import json
@@ -147,7 +147,7 @@ def get_option_parser():
     parser = COP(
         __doc__,
         comms=True,
-        argdoc=[('ID', 'Workflow ID')],
+        argdoc=[('WORKFLOW_ID', 'Workflow ID')],
     )
     parser.add_option(
         "-g", "--global", help="Global information only.",

cylc/flow/scripts/ext_trigger.py

@@ -25,9 +25,9 @@
 message as a signal that an external prerequisite has
 been satisfied and trigger the task accordingly.
 
-The ID argument should be unique to each external
+The WORKFLOW_ID argument should be unique to each external
 trigger event. When an incoming message satisfies
-a task's external trigger the message ID is broadcast
+a task's external trigger the message TRIGGER_ID is broadcast
 to all downstream tasks in the cycle point as
 ``$CYLC_EXT_TRIGGER_ID``.  Tasks can use
 ``$CYLC_EXT_TRIGGER_ID``, for example,  to
@@ -81,9 +81,9 @@ def get_option_parser():
         __doc__,
         comms=True,
         argdoc=[
-            ("WORKFLOW", "Workflow ID"),
+            ("WORKFLOW_ID", "Workflow ID"),
             ("MSG", "External trigger message"),
-            ("ID", "Unique trigger ID"),
+            ("TRIGGER_ID", "Unique trigger ID"),
         ],
     )
 

cylc/flow/scripts/get_workflow_contact.py

@@ -33,7 +33,7 @@
 
 
 def get_option_parser():
-    return COP(__doc__, argdoc=[('WORKFLOW', 'Workflow ID')])
+    return COP(__doc__, argdoc=[('WORKFLOW_ID', 'Workflow ID')])
 
 
 @cli_function(get_option_parser)

cylc/flow/scripts/get_workflow_version.py

@@ -51,7 +51,8 @@ def get_option_parser():
     parser = COP(
         __doc__,
         comms=True,
-        argdoc=[('ID ...', 'Workflow IDs')],
+        multiworkflow=True,
+        argdoc=[('WORKFLOW_ID ...', 'Workflow IDs')],
     )
     return parser
 

cylc/flow/scripts/graph.py

@@ -190,7 +190,7 @@ def get_option_parser():
         jset=True,
         prep=True,
         argdoc=[
-            ('[WORKFLOW]', 'Workflow ID or path to source'),
+            ('[WORKFLOW_ID]', 'Workflow ID or path to source'),
             ('[START]', 'Graph start; defaults to initial cycle point'),
             (
                 '[STOP]',

cylc/flow/scripts/hold.py

@@ -52,9 +52,6 @@
 Note: To pause a workflow (immediately preventing all job submission), use
 'cylc pause' instead.
 
-Note: globs and ":<state>" selectors will only match active tasks;
-to hold future tasks when they spawn, use exact identifiers e.g. "mytask.1234".
-
 See also 'cylc release'.
 """
 
@@ -105,6 +102,7 @@ def get_option_parser() -> COP:
         __doc__,
         comms=True,
         multitask=True,
+        multiworkflow=True,
         argdoc=[('ID [ID ...]', 'Cycle/Family/Task ID(s)')],
     )
 

cylc/flow/scripts/kill.py

@@ -64,6 +64,7 @@ def get_option_parser():
         __doc__,
         comms=True,
         multitask=True,
+        multiworkflow=True,
         argdoc=[('ID [ID ...]', 'Cycle/Family/Task ID(s)')],
     )
 

cylc/flow/scripts/list.py

@@ -49,7 +49,7 @@ def get_option_parser():
         jset=True,
         prep=True,
         icp=True,
-        argdoc=[('WORKFLOW', 'Workflow ID or path to source')],
+        argdoc=[('WORKFLOW_ID', 'Workflow ID or path to source')],
     )
 
     parser.add_option(

cylc/flow/scripts/message.py

@@ -92,7 +92,7 @@ def get_option_parser():
         comms=True,
         argdoc=[
             # TODO
-            ('[WORKFLOW]', 'Workflow ID'),
+            ('[WORKFLOW_ID]', 'Workflow ID'),
             ('[TASK-JOB]', 'Task job identifier CYCLE/TASK_NAME/SUBMIT_NUM'),
             ('[[SEVERITY:]MESSAGE ...]', 'Messages')])
     parser.add_option(

cylc/flow/scripts/pause.py

@@ -62,7 +62,8 @@ def get_option_parser():
         __doc__,
         comms=True,
         multitask=True,
-        argdoc=[('ID [ID ...]', 'Workflow ID(s)')],
+        multiworkflow=True,
+        argdoc=[('WORKFLOW_ID [WORKFLOW_ID ...]', 'Workflow ID(s)')],
     )
     return parser
 

cylc/flow/scripts/ping.py

@@ -65,6 +65,8 @@ def get_option_parser():
     parser = COP(
         __doc__,
         comms=True,
+        multitask=True,
+        multiworkflow=True,
         argdoc=[('ID [ID ...]', 'Cycle/Family/Task ID(s)')],
     )
 

cylc/flow/scripts/poll.py

@@ -65,6 +65,7 @@ def get_option_parser():
         __doc__,
         comms=True,
         multitask=True,
+        multiworkflow=True,
         argdoc=[('ID [ID ...]', 'Cycle/Family/Task ID(s)')],
     )
     return parser

cylc/flow/scripts/reinstall.py

@@ -58,7 +58,7 @@
 
 def get_option_parser():
     parser = COP(
-        __doc__, comms=True, argdoc=[('[WORKFLOW]', 'Workflow ID')]
+        __doc__, comms=True, argdoc=[('[WORKFLOW_ID]', 'Workflow ID')]
     )
 
     parser.add_cylc_rose_options()

cylc/flow/scripts/release.py

@@ -35,9 +35,6 @@
 
 Held tasks do not submit their jobs even if ready to run.
 
-Note: globs and ":<state>" selectors will only match active tasks;
-to release future tasks, use exact identifiers e.g. "1234/mytask".
-
 See also 'cylc hold'.
 """
 
@@ -86,6 +83,7 @@ def get_option_parser() -> COP:
         __doc__,
         comms=True,
         multitask=True,
+        multiworkflow=True,
         argdoc=[('ID [ID ...]', 'Cycle/Family/Task ID(s)')],
     )
 

cylc/flow/scripts/reload.py

@@ -41,8 +41,8 @@
 running at reload time.
 
 If the workflow was started with Jinja2 template variables set on the command
-line (cylc play --set 'FOO="bar"' WORKFLOW) the same template settings apply to
-the reload (only changes to the flow.cylc file itself are reloaded).
+line (cylc play --set 'FOO="bar"' WORKFLOW_ID) the same template settings apply
+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."""
@@ -76,7 +76,8 @@ def get_option_parser():
     parser = COP(
         __doc__,
         comms=True,
-        argdoc=[('ID [ID ...]', 'Workflow ID(s)')],
+        multiworklow=True,
+        argdoc=[('WORKFLOW_ID [WORKFLOW_ID ...]', 'Workflow ID(s)')],
     )
     return parser
 

cylc/flow/scripts/remove.py

@@ -53,6 +53,7 @@ def get_option_parser():
         __doc__,
         comms=True,
         multitask=True,
+        multiworkflow=True,
         argdoc=[('ID [ID ...]', 'Cycle/Family/Task ID(s)')],
     )
 

cylc/flow/scripts/report_timings.py

@@ -89,7 +89,7 @@ def smart_open(filename=None):
 def get_option_parser():
     parser = COP(
         __doc__,
-        argdoc=[('WORKFLOW', 'Workflow ID')]
+        argdoc=[('WORKFLOW_ID', 'Workflow ID')]
     )
     parser.add_option(
         "-r", "--raw",