cylc reinstall --dry-run (#4964)

* reinstall: add --dry-run option

* 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).

* cli: put headings in help text in bold

* Makes the CLI --help easier to skim by making section headings
  more obvious.

* reinstall: perform interactive --dry-run by default

* New behaviour:
  * In interactive mode:
    * Perform dry run.
    * Display proposed changes to the user.
    * Prompt for permission to continue.
    * Provide explanatory docs in the --help.
  * In non-interactive mode (unlikely use case for reinstall):
    * Just do it.
* Misc changes:
  * Use the globalcfg configured rsync command for `cylc install`
    (was using hardcoded `rsync`).
  * Improved reinstall docs.

* changelog

* Style fix.

Co-authored-by: Hilary James Oliver <[email protected]>

CHANGES.md

@@ -35,6 +35,10 @@ Fourth Release Candidate for Cylc 8 suitable for acceptance testing.
 
 ### Enhancements
 
+[#4964](https://github.com/cylc/cylc-flow/pull/4964) -
+`cylc reinstall` now displays the changes it would make when run
+interactively and has improved help / documentaiton.
+
 [#4836](https://github.com/cylc/cylc-flow/pull/4836) - The log directory has
 been tidied. Workflow logs are now found in `log/scheduler` rather than
 `log/workflow`, filenames now include `start`/`restart`. Other minor directory

cylc/flow/cfgspec/globalcfg.py

@@ -1286,8 +1286,10 @@ def default_for(
                  VDR.V_STRING,
                  'rsync',
                  desc='''
-                Command used for remote file installation. This supports POSIX
-                compliant rsync implementation e.g. GNU or BSD.
+                Command used for file installation.
+
+                This supports POSIX compliant rsync implementations e.g. GNU or
+                BSD.
 
                 .. versionadded:: 8.0.0
             ''')

cylc/flow/option_parsers.py

@@ -36,7 +36,7 @@
 from typing import Any, Dict, Optional, List, Tuple
 
 from cylc.flow import LOG
-from cylc.flow.terminal import supports_color
+from cylc.flow.terminal import supports_color, DIM
 import cylc.flow.flags
 from cylc.flow.loggingutil import (
     CylcLogFormatter,
@@ -70,9 +70,29 @@ def format_shell_examples(string):
     return cparse(
         re.sub(
             r'^(\s*(?:\$[^#]+)?)(#.*)$',
-            r'\1<dim>\2</dim>',
+            rf'\1<{DIM}>\2</{DIM}>',
             string,
-            flags=re.M
+            flags=re.M,
+        )
+    )
+
+
+def format_help_headings(string):
+    """Put "headings" in bold.
+
+    Where "headings" are lines with no indentation which are followed by a
+    colon e.g:
+
+    Examples:
+      ...
+
+    """
+    return cparse(
+        re.sub(
+            r'^(\w.*:)$',
+            r'<bold>\1</bold>',
+            string,
+            flags=re.M,
         )
     )
 
@@ -183,7 +203,9 @@ def _format(self, text):
             )
         ):
             # Add color formatting to examples text.
-            text = format_shell_examples(text)
+            text = format_shell_examples(
+                format_help_headings(text)
+            )
         else:
             # Strip any hardwired formatting
             text = cstrip(text)

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 any 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

@@ -26,7 +26,10 @@
 import pkg_resources
 
 from cylc.flow import __version__, iter_entry_points
-from cylc.flow.option_parsers import format_shell_examples
+from cylc.flow.option_parsers import (
+    format_help_headings,
+    format_shell_examples,
+)
 from cylc.flow.scripts.common import cylc_header
 
 
@@ -173,8 +176,7 @@ def get_version(long=False):
 
 # because this command is not served from behind cli_function like the
 # other cylc commands we have to manually patch in colour support
-USAGE = format_shell_examples(USAGE)
-USAGE = cparse(USAGE)
+USAGE = cparse(format_help_headings(format_shell_examples(USAGE)))
 
 # all sub-commands
 # {name: entry_point}

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