cli: put headings in help text in bold

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

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/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_shell_examples,
+    format_help_headings,
+)
 from cylc.flow.scripts.common import cylc_header
 
 
@@ -174,7 +177,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 = format_help_headings(format_shell_examples(USAGE))
 USAGE = cparse(USAGE)
 
 # all sub-commands
@@ -447,7 +450,7 @@ def cli_help():
     if 'gui' in COMMANDS:
         commands.append('gui')
     print(USAGE)
-    print('Selected Sub-Commands:')
+    print(cparse('<bold>Selected Sub-Commands:</bold>'))
     print_command_list(
         # print a short list of the main cylc commands
         commands=commands,

cylc/flow/scripts/scan.py

@@ -72,16 +72,13 @@
     Options
 )
 from cylc.flow.print_tree import get_tree
-from cylc.flow.terminal import cli_function
+from cylc.flow.terminal import cli_function, DIM
 from cylc.flow.util import natural_sort_key
 from cylc.flow.workflow_files import ContactFileFields as Cont
 
 if TYPE_CHECKING:
     from optparse import Values
 
-# default grey colour (do not use "dim", it is not sufficiently portable)
-DIM = 'fg 248'
-
 # all supported workflow states
 FLOW_STATES = {
     'running',

cylc/flow/terminal.py

@@ -40,6 +40,9 @@
 # CLI exception message format
 EXC_EXIT = cparse('<red><bold>{name}: </bold>{exc}</red>')
 
+# default grey colour (do not use "dim", it is not sufficiently portable)
+DIM = 'fg 248'
+
 
 def is_terminal():
     """Determine if running in (and printing to) a terminal."""
@@ -174,7 +177,6 @@ def parse_dirty_json(stdout):
                 stdout = stdout.split('\n', 1)[1]
             except IndexError:
                 break
-    # raise ValueError(f'Invalid JSON: {orig}')
     raise ValueError(orig)