scripts: make west build -h fit on a screen

The west build --help output no longer fits in a single page.  Move
details and examples into the documentation, so the -h output doesn't
require scrolling around.

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>

doc/guides/west/build-flash-debug.rst

@@ -27,16 +27,31 @@ directly delegate to West.
 Building: ``west build``
 ************************
 
-.. tip:: Run ``west build -h`` for additional help.
+.. tip:: Run ``west build -h`` for a quick overview.
 
 The ``build`` command helps you build Zephyr applications from source. You can
 use :ref:`west config <west-config-cmd>` to configure its behavior.
 
+This command attempts to "do what you mean" when run from a Zephyr application
+source or build directory:
+
+- When you run ``west build`` in an existing build directory, the board, source
+  directory, etc. are obtained from the CMake cache, and that build directory
+  is re-compiled.
+
+- The same is true if a Zephyr build directory named :file:`build` exists in
+  your current working directory.
+
+- Otherwise, the source directory defaults to the current working directory, so
+  running ``west build`` from a Zephyr application's source directory compiles
+  it.
+
 Basics
 ======
 
-The easiest way to use it is to go to an application's root directory (i.e. the
-folder containing its :file:`CMakeLists.txt`) and then run::
+The easiest way to use ``west build`` is to go to an application's root
+directory (i.e. the folder containing the application's :file:`CMakeLists.txt`)
+and then run::
 
   west build -b <BOARD>
 
@@ -52,12 +67,13 @@ exactly the same name you would supply to CMake if you were to invoke it with:
 A build directory named :file:`build` will be created, and the application will
 be compiled there after ``west build`` runs CMake to create a build system in
 that directory. If you run ``west build`` with an existing build directory, the
-application is incrementally re-compiled without re-running CMake.
+application is incrementally re-compiled without re-running CMake (you can
+force CMake to run again with ``--cmake``).
 
-You don't need to give ``-b`` if you've already got an existing build
-directory; ``west build`` can figure out the board from the CMake cache. For
-new builds, the :envvar:`BOARD` environment variable and ``build.board``
-configuration option can also be used to set the board.
+You don't need to use the ``--board`` option if you've already got an existing
+build directory; ``west build`` can figure out the board from the CMake cache.
+For new builds, the ``--board`` option, :envvar:`BOARD` environment variable,
+or ``build.board`` configuration option are checked (in that order).
 
 To configure ``west build`` to build for the ``reel_board`` by default::
 
@@ -109,6 +125,7 @@ To let west decide for you if a pristine build is needed, use ``-p auto``::
    You can run ``west config build.pristine auto`` to make this setting
    permanent.
 
+
 .. _west-building-generator:
 
 To add additional arguments to the CMake invocation performed by ``west

scripts/west_commands/build.py

@@ -25,43 +25,8 @@
 BUILD_DESCRIPTION = '''\
 Convenience wrapper for building Zephyr applications.
 
-This command attempts to do what you mean when run from a Zephyr
-application source or a pre-existing build directory:
-
-- When the build directory ('./build' by default, see below) exists and is
-  already a Zephyr build directory, the source directory is obtained from the
-  CMake cache, and that build directory is re-compiled.
-
-- Otherwise, the source directory defaults to the current working
-  directory, so running "west build" from a Zephyr application's
-  source directory compiles it.
-
-The source and build directories can be explicitly set with the
---source-dir and --build-dir options. The build directory defaults to
-'build' if it is not auto-detected. The build directory is always
-created if it does not exist.
-
-The board to build for is taken from the CACHED_BOARD CMake cache
-variable, --board option, BOARD environment variable, or build.board
-configuration option, in decreasing order of precedence.
-
-This command runs CMake to generate a build system if one is not
-present in the build directory, then builds the application.
-Subsequent builds try to avoid re-running CMake; you can force it
-to run by setting --cmake.
-
-To pass additional options to CMake, give them as extra arguments
-after a '--'. For example, this sets an overlay config file:
-
-west build [...] -- -DOVERLAY_CONFIG=some.conf
-
-(Doing this forces a CMake run.)
-
 positional arguments:
-  source_dir            Explicitly set the source directory. If not given and
-                        rebuilding an existing Zephyr build directory, this is
-                        taken from the CMake cache. Otherwise, the current
-                        directory is assumed.
+  source_dir            Use this path as the source directory
   cmake_opt             Extra options to pass to CMake; implies -c
 '''
 
@@ -121,29 +86,23 @@ def do_add_parser(self, parser_adder):
         parser.add_argument('-s', '--source-dir', help=argparse.SUPPRESS)
         parser.add_argument('-d', '--build-dir',
                             help=BUILD_DIR_DESCRIPTION +
-                            "The directory is created if it doesn't exist.")
+                            " Always created if it doesn't exist.")
         parser.add_argument('-t', '--target',
-                            help='''Override the build system target (e.g.
-                            'clean', 'pristine', etc.)''')
+                            help='''Build system target to run''')
         parser.add_argument('-p', '--pristine', choices=['auto', 'always',
                             'never'], action=AlwaysIfMissing, nargs='?',
                             help='''Control whether the build folder is made
-                            pristine before building if a build system is
-                            present in the build dir. --pristine is the same as
-                            --pristine=always. If set to auto, the build folder
-                            will be made pristine only if required based on the
-                            existing build system and the options provided.
-                            This allows for reusing a build folder even if it
-                            contains build files for a different board or
-                            application.''')
+                            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 which would
-                            have run, without actually running them.''')
+                            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

scripts/west_commands/build_helpers.py

@@ -21,9 +21,9 @@
 '''Name of the default CMake generator.'''
 
 BUILD_DIR_DESCRIPTION = '''\
-Explicitly sets the build directory.  If not given and the current
-directory is a Zephyr build directory, it will be used; otherwise,
-"{}" is assumed.'''.format(DEFAULT_BUILD_DIR)
+Build directory. If missing and run in a Zephyr build directory, it is
+used; otherwise, it's "{}".'''.format(
+    DEFAULT_BUILD_DIR)
 
 
 def find_build_dir(dir):