Better help messages

gitlab_docker_autodep/main.py

@@ -12,6 +12,10 @@ from .rebuild import rebuild_deps
 from .server import run_app
 
 
+def _fmtdesc(s):
+    return s.strip()
+
+
 def main():
     parser = argparse.ArgumentParser(
         description='Rebuild Docker images on a Gitlab instance.')
@@ -47,8 +51,22 @@ def main():
         'list-projects',
         parents=[common_parser],
         help='list projects',
-        description='List all projects and their branches on the Gitlab '
-        'instance.')
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=_fmtdesc('''
+List all projects and their branches on the Gitlab instance.
+
+The output is a list of project paths with all their branches, separated
+by a colon, one per line. Since the Gitlab 'search' API is quite
+coarse, you can then filter the output for specific projects or branches
+using 'grep', e.g.:
+
+    gitlab-deps list-projects | grep ^path/to/my/group/
+
+or
+
+    gitlab-deps list-projects | grep ':master$'
+
+'''))
     list_projects_parser.add_argument(
         '--search',
         help='Search query used to filter project list on the server side')
@@ -58,11 +76,25 @@ def main():
         'deps',
         parents=[common_parser],
         help='build dependency map',
-        description='Generate a map of dependencies between projects on a '
-        'Gitlab instance.')
-    deps_parser.add_argument(
-        '--docker', action='store_true',
-        help='Output dependencies between Docker images, not Gitlab projects')
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=_fmtdesc('''
+Generate a map of dependencies between projects on a
+Gitlab instance.
+
+The input (on standard input) must consist of a list of projects along
+with their branches, separated by a colon, one per line. If the branch
+is unspecified, 'master' is assumed.
+
+The output consists of pairs of project / dependency (so, these are
+'forward' dependencies), for all projects/branches specified in the
+input.
+
+To obtain a list of reverse dependencies, one can simply swap the
+columns in the output, e.g.:
+
+    gitlab-deps deps < project.list | awk '{print $2, $1}'
+
+'''))
 
     # Setup pipeline hooks on the specified projects.
     set_hooks_parser = subparsers.add_parser(