better usage messages & READMEs

5 files changed, 70 insertions, 16 deletions

diff --git a/cmake/build/README.md b/cmake/build/README.md
new file mode 100644
index 0000000..b63564d
--- /dev/null
+++ b/cmake/build/README.md
@@ -0,0 +1,13 @@
+CMake
+=====
+
+Build a CMake project.
+Consult the output of `build.py --help` for details.
+
+A simple usage example:
+
+    > python3 build.py --configuration Release --install path/to/somewhere -- ../examples/simple
+    ...
+
+    > ./path/to/somewhere/bin/foo
+    foo
diff --git a/cmake/build/build.py b/cmake/build/build.py
index c4af4ea..e256b72 100755
--- a/cmake/build/build.py
+++ b/cmake/build/build.py
@@ -5,10 +5,33 @@
 # For details, see https://github.com/egor-tensin/cmake-common.
 # Distributed under the MIT License.
 
-# This script is used basically to invoke the CMake executable in a
-# cross-platform way (provided the platform has Python 3, of course).
-# The motivation was to merge my Travis and AppVeyor build scripts (largely
-# similar, but written in bash and PowerShell, respectively).
+R'''Build a CMake project.
+
+This script is used basically to invoke the CMake executable in a
+cross-platform way (provided the platform has Python 3, of course).  The
+motivation was to merge my Travis and AppVeyor build scripts (largely similar,
+but written in bash and PowerShell, respectively).
+
+A simple usage example:
+
+    $ %(prog)s --configuration Release --install path/to/somewhere -- ../examples/simple
+    ...
+
+    $ ./path/to/somewhere/bin/foo
+    foo
+
+Picking the target platform is build system-specific.  On Visual Studio, pass
+the target platform using the `-A` flag like this:
+
+    > %(prog)s --install path\to\somewhere -- ..\examples\simple -A Win32
+    ...
+
+Using GCC-like compilers, the best way is to use CMake toolchain files (see
+cmake/toolchains in this repository for examples).
+
+    $ %(prog)s --install path/to/somewhere -- ../examples/simple -D CMAKE_TOOLCHAIN_FILE="$( pwd )/../toolchains/mingw-x86.cmake"
+    ...
+'''
 
 import argparse
 from contextlib import contextmanager
@@ -115,7 +138,10 @@ def _parse_args(argv=None):
         argv = sys.argv[1:]
     logging.info('Command line arguments: %s', argv)
 
-    parser = argparse.ArgumentParser(description='Build a CMake project')
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
     parser.add_argument('--build', metavar='DIR', dest='build_dir',
                         type=_parse_dir,
                         help='build directory (temporary directory unless specified)')
@@ -124,7 +150,7 @@ def _parse_args(argv=None):
                         help='install directory')
     parser.add_argument('--configuration', metavar='CONFIG',
                         type=_parse_configuration, default=Configuration.DEBUG,
-                        help='build configuration (i.e. Debug/Release)')
+                        help=f'build configuration ({"/".join(map(str, Configuration))})')
     parser.add_argument('src_dir', metavar='DIR',
                         type=_parse_dir,
                         help='source directory')
diff --git a/cmake/build/ci/appveyor.py b/cmake/build/ci/appveyor.py
index bb4d31d..ed656b3 100755
--- a/cmake/build/ci/appveyor.py
+++ b/cmake/build/ci/appveyor.py
@@ -5,9 +5,14 @@
 # For details, see https://github.com/egor-tensin/cmake-common.
 # Distributed under the MIT License.
 
-# This is similar to build.py, but auto-fills some parameters for build.py from
-# the AppVeyor-defined environment variables.
-# The project is built in C:\Projects\build.
+'''Build a CMake project on AppVeyor.
+
+This is similar to build.py, but auto-fills some parameters for build.py from
+the AppVeyor-defined environment variables.
+
+
+The project is built in C:\Projects\build.
+'''
 
 import argparse
 from enum import Enum
@@ -113,7 +118,10 @@ def _parse_args(argv=None):
         argv = sys.argv[1:]
     logging.info('Command line arguments: %s', argv)
 
-    parser = argparse.ArgumentParser(description='Build a CMake project on AppVeyor')
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
     parser.add_argument('--install', metavar='DIR', dest='install_dir',
                         help='install directory')
     parser.add_argument('cmake_args', nargs='*', metavar='CMAKE_ARG', default=[],
diff --git a/cmake/build/ci/travis.py b/cmake/build/ci/travis.py
index 3712bf9..ab93711 100755
--- a/cmake/build/ci/travis.py
+++ b/cmake/build/ci/travis.py
@@ -5,9 +5,13 @@
 # For details, see https://github.com/egor-tensin/cmake-common.
 # Distributed under the MIT License.
 
-# This is similar to build.py, but auto-fills some parameters for build.py from
-# the Travis-defined environment variables.
-# The project is built in $HOME/build.
+'''Build a CMake project on Travis.
+
+This is similar to build.py, but auto-fills some parameters for build.py from
+the Travis-defined environment variables.
+
+The project is built in $HOME/build.
+'''
 
 import argparse
 import logging
@@ -50,7 +54,10 @@ def _parse_args(argv=None):
         argv = sys.argv[1:]
     logging.info('Command line arguments: %s', argv)
 
-    parser = argparse.ArgumentParser(description='Build a CMake project on Travis')
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
     parser.add_argument('--install', metavar='DIR', dest='install_dir',
                         help='install directory')
     parser.add_argument('cmake_args', nargs='*', metavar='CMAKE_ARG', default=[],
diff --git a/cmake/toolchains/README.md b/cmake/toolchains/README.md
index 0e46391..9c58eb6 100644
--- a/cmake/toolchains/README.md
+++ b/cmake/toolchains/README.md
@@ -1,3 +1,3 @@
 Use the toolchain files by passing something like
-`-DCMAKE_TOOLCHAIN_FILE=path/to/cmake-common/toolchains/toolchain.cmake` to
-`cmake`.
+`-D CMAKE_TOOLCHAIN_FILE=PATH/TO/cmake-common/cmake/toolchains/TOOLCHAIN.cmake`
+to `cmake`.