scripts: clean up west build/flash/debug help

Just changes to the west help output; no functional changes expected.

Make option descriptions lowercase to match the argparse module's
conventions. When multiple sentences are required, move them to parser
prolog/epilog or argument group description sections.

Clarify some points that have confused multiple people.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>

scripts/west_commands/build.py

@@ -24,14 +24,24 @@ west build [-h] [-b BOARD] [-d BUILD_DIR]
            [source_dir] -- [cmake_opt [cmake_opt ...]]
 '''
 
-BUILD_DESCRIPTION = '''\
+BUILD_DESCRIPTION = f'''\
 Convenience wrapper for building Zephyr applications.
 
+{FIND_BUILD_DIR_DESCRIPTION}
+
 positional arguments:
-  source_dir            Use this path as the source directory
+  source_dir            application source directory
-  cmake_opt             Extra options to pass to CMake; implies -c
+  cmake_opt             extra options to pass to cmake; implies -c
+                        (these must come after "--" as shown above)
 '''
 
+PRISTINE_DESCRIPTION = """\
+A "pristine" build directory is empty. The -p option controls
+whether the build directory is made pristine before the build
+is done. A bare '--pristine' with no value is the same as
+--pristine=always. Setting --pristine=auto uses heuristics to
+guess if a pristine build may be necessary."""
+
 def _banner(msg):
     log.inf('-- west build: ' + msg, colorize=True)
 
@@ -86,36 +96,34 @@ class Build(Forceable):
         # Remember to update scripts/west-completion.bash if you add or remove
         # flags
 
-        parser.add_argument('-b', '--board', help='Board to build for')
+        parser.add_argument('-b', '--board', help='board to build for')
         # Hidden option for backwards compatibility
         parser.add_argument('-s', '--source-dir', help=argparse.SUPPRESS)
         parser.add_argument('-d', '--build-dir',
-                            help='Build directory. ' +
+                            help='build directory to create or use')
-                            FIND_BUILD_DIR_DESCRIPTION +
-                            " Otherwise the default build directory is " +
-                            "created and used.")
-        parser.add_argument('-t', '--target',
-                            help='''Build system target ("usage"
-                            for more info; and "help" for a list)''')
-        parser.add_argument('-p', '--pristine', choices=['auto', 'always',
-                            'never'], action=AlwaysIfMissing, nargs='?',
-                            help='''Control whether the build folder is made
-                            pristine before running CMake. --pristine is the
-                            same as --pristine=always. If 'auto', it will
-                            be made pristine only if needed.''')
-        parser.add_argument('-c', '--cmake', action='store_true',
-                            help='Force CMake to run')
-        parser.add_argument('--cmake-only', action='store_true',
-                            help="Just run CMake; don't build. Implies -c.")
-        parser.add_argument('-n', '--just-print', '--dry-run', '--recon',
-                            dest='dry_run', action='store_true',
-                            help='''Just print the build commands; don't run
-                            them''')
-        parser.add_argument('-o', '--build-opt', default=[], action='append',
-                            help='''Options to pass to the build tool.
-                            May be given more than once to append multiple
-                            values.''')
         self.add_force_arg(parser)
+
+        group = parser.add_argument_group('cmake and build tool')
+        group.add_argument('-c', '--cmake', action='store_true',
+                           help='force a cmake run')
+        group.add_argument('--cmake-only', action='store_true',
+                           help="just run cmake; don't build (implies -c)")
+        group.add_argument('-t', '--target',
+                           help='''run this build system target (try "-t usage"
+                           or "-t help")''')
+        group.add_argument('-o', '--build-opt', default=[], action='append',
+                           help='''options to pass to the build tool
+                           (make or ninja); may be given more than once''')
+        group.add_argument('-n', '--just-print', '--dry-run', '--recon',
+                            dest='dry_run', action='store_true',
+                            help="just print build commands; don't run them")
+
+        group = parser.add_argument_group('pristine builds',
+                                          PRISTINE_DESCRIPTION)
+        group.add_argument('-p', '--pristine', choices=['auto', 'always',
+                            'never'], action=AlwaysIfMissing, nargs='?',
+                            help='pristine build folder setting')
+
         return parser
 
     def do_run(self, args, remainder):

scripts/west_commands/build_helpers.py

@@ -24,7 +24,7 @@ DEFAULT_CMAKE_GENERATOR = 'Ninja'
 '''Name of the default CMake generator.'''
 
 FIND_BUILD_DIR_DESCRIPTION = '''\
-If not given, the default build directory is {}/ unless the
+If the build directory is not given, the default is {}/ unless the
 build.dir-fmt configuration variable is set. The current directory is
 checked after that. If either is a Zephyr build directory, it is used.
 '''.format(DEFAULT_BUILD_DIR)

scripts/west_commands/debug.py

@@ -10,7 +10,7 @@ from textwrap import dedent
 
 from west.commands import WestCommand
 
-from run_common import desc_common, add_parser_common, do_run_common
+from run_common import add_parser_common, do_run_common
 
 
 class Debug(WestCommand):
@@ -23,8 +23,7 @@ class Debug(WestCommand):
             dedent('''
             Connect to the board, flash the program, and start a
             debugging session. Use "west attach" instead to attach
-            a debugger without reflashing.\n\n''') +
+            a debugger without reflashing.'''),
-            desc_common('debug'),
             accepts_unknown_args=True)
         self.runner_key = 'debug-runner'  # in runners.yaml
 
@@ -48,8 +47,7 @@ class DebugServer(WestCommand):
 
             The debug server binds to a known port, and allows client software
             started elsewhere to connect to it and debug the running
-            Zephyr image.\n\n''') +
+            Zephyr image.'''),
-            desc_common('debugserver'),
             accepts_unknown_args=True)
         self.runner_key = 'debug-runner'  # in runners.yaml
 
@@ -67,8 +65,7 @@ class Attach(WestCommand):
             'attach',
             # Keep this in sync with the string in west-commands.yml.
             'interactively debug a board',
-            "Like \"west debug\", but doesn't reflash the program.\n\n" +
+            "Like \"west debug\", but doesn't reflash the program.",
-            desc_common('attach'),
             accepts_unknown_args=True)
         self.runner_key = 'debug-runner'  # in runners.yaml
 

scripts/west_commands/flash.py

@@ -8,7 +8,7 @@
 
 from west.commands import WestCommand
 
-from run_common import desc_common, add_parser_common, do_run_common
+from run_common import add_parser_common, do_run_common
 
 
 class Flash(WestCommand):
@@ -18,8 +18,7 @@ class Flash(WestCommand):
             'flash',
             # Keep this in sync with the string in west-commands.yml.
             'flash and run a binary on a board',
-            'Permanently reprogram a board with a new binary.\n' +
+            "Permanently reprogram a board's flash with a new binary.",
-            desc_common('flash'),
             accepts_unknown_args=True)
         self.runner_key = 'flash-runner'  # in runners.yaml
 

scripts/west_commands/run_common.py

@@ -80,53 +80,52 @@ def add_parser_common(command, parser_adder=None, parser=None):
             command.name,
             formatter_class=argparse.RawDescriptionHelpFormatter,
             help=command.help,
-            description=command.description,
+            description=command.description)
-            epilog=FIND_BUILD_DIR_DESCRIPTION)
 
     # Remember to update scripts/west-completion.bash if you add or remove
     # flags
 
     parser.add_argument('-H', '--context', action='store_true',
-                        help='''Rebuild application and print context-sensitive
+                        help='print build directory specific help')
-                        help; this may be combined with --runner to restrict
-                        output to a given runner.''')
 
-    group = parser.add_argument_group(title='General options')
+    group = parser.add_argument_group('general options',
+                                      FIND_BUILD_DIR_DESCRIPTION)
 
     group.add_argument('-d', '--build-dir', metavar='DIR',
-                       help='zephyr build directory')
+                       help='application build directory')
+    # still supported for backwards compatibility, but questionably
+    # useful now that we do everything with runners.yaml
     group.add_argument('-c', '--cmake-cache', metavar='FILE',
-                       help='override the default CMake cache file')
+                       help=argparse.SUPPRESS)
     group.add_argument('-r', '--runner',
-                       help=f'overrides the default {command.name} runner')
+                       help='override default runner from --build-dir')
     group.add_argument('--skip-rebuild', action='store_true',
-                       help='do not rebuild the application first')
+                       help='do not refresh cmake dependencies first')
 
-    group = parser.add_argument_group(title='Common runner options')
+    group = parser.add_argument_group(
+        'runner configuration overrides',
+        textwrap.dedent(f'''\
+        Run "west {command.name} --context" for --build-dir specific options.
+        Not all runners respect --elf-file / --hex-file / --bin-file, nor use
+        gdb or openocd.'''))
 
-    group.add_argument('--board-dir', metavar='DIR',
+    # TODO: is this actually useful?
-                       help='zephyr board directory')
+    group.add_argument('--board-dir', metavar='DIR', help='board directory')
-    # FIXME: we should just have a single --file argument.
+    # FIXME: we should just have a single --file argument. The variation
+    # between runners is confusing people.
     group.add_argument('--elf-file', metavar='FILE', help='path to zephyr.elf')
     group.add_argument('--hex-file', metavar='FILE', help='path to zephyr.hex')
     group.add_argument('--bin-file', metavar='FILE', help='path to zephyr.bin')
-    # FIXME: these are runner-specific. Remove them from this location.
+    # FIXME: these are runner-specific and should be moved to where --context
-    group.add_argument('--gdb', help='path to GDB, if applicable')
+    # can find them instead.
-    group.add_argument('--openocd', help='path to OpenOCD, if applicable')
+    group.add_argument('--gdb', help='path to GDB')
+    group.add_argument('--openocd', help='path to openocd')
     group.add_argument(
         '--openocd-search', metavar='DIR',
-        help='path to add to OpenOCD search path, if applicable')
+        help='path to add to openocd search path, if applicable')
 
     return parser
 
-def desc_common(command_name):
-    return textwrap.dedent(f'''\
-    Only common "west {command_name}" options are listed here.
-    To get help on available runner-specific options, run:
-
-      west {command_name} --context -d BUILD_DIR
-    ''')
-
 def do_run_common(command, user_args, user_runner_args):
     # This is the main routine for all the "west flash", "west debug",
     # etc. commands.

scripts/west_commands/zephyr_ext_common.py

@@ -32,7 +32,7 @@ class Forceable(WestCommand):
     def add_force_arg(parser):
         '''Add a -f / --force option to the parser.'''
         parser.add_argument('-f', '--force', action='store_true',
-                            help='Ignore any errors and try to proceed')
+                            help='ignore any errors and try to proceed')
 
     def check_force(self, cond, msg):
         '''Abort if the command needs to be forced and hasn't been.