Document subcommands in --help output.

3 files changed, 37 insertions, 1 deletions

diff --git a/cliapp/app.py b/cliapp/app.py
index 3c16303..af579c3 100644
--- a/cliapp/app.py
+++ b/cliapp/app.py
@@ -87,7 +87,17 @@ class Application(object):
         self.fileno = 0
         self.global_lineno = 0
         self.lineno = 0
+        
+        if self._subcommands():
+            usage = self._make_subcommand_usage()
+            if description is None:
+                description = ''
+            description += '\n\n' + self._make_subcommand_description()
+        else:
+            usage = None
+        
         self.settings = cliapp.Settings(progname, version, 
+                                        usage=usage,
                                         description=description,
                                         epilog=epilog)
         
@@ -157,6 +167,27 @@ class Application(object):
     def _normalize_cmd(self, cmd):
         return 'cmd_%s' % cmd.replace('-', '_')
 
+    def _unnormalize_cmd(self, method):
+        assert method.startswith('cmd_')
+        return method[len('cmd_'):].replace('_', '-')
+
+    def _make_subcommand_usage(self):
+        lines = []
+        prefix = 'Usage:'
+        for method in self._subcommands():
+            cmd = self._unnormalize_cmd(method)
+            lines.append('%s %%prog [options] %s' % (prefix, cmd))
+            prefix = ' ' * len(prefix)
+        return '\n'.join(lines)
+
+    def _make_subcommand_description(self):
+        paras = []
+        for method in self._subcommands():
+            cmd = self._unnormalize_cmd(method)
+            doc = getattr(self, method).__doc__ or ''
+            paras.append('%s: %s' % (cmd, doc.strip()))
+        return '\n\n'.join(paras)
+
     def setup_logging(self): # pragma: no cover
         '''Set up logging.'''
         
diff --git a/cliapp/settings.py b/cliapp/settings.py
index 8a05a2e..4d3eca6 100644
--- a/cliapp/settings.py
+++ b/cliapp/settings.py
@@ -173,12 +173,14 @@ class Settings(object):
     
     '''
 
-    def __init__(self, progname, version, description=None, epilog=None):
+    def __init__(self, progname, version, usage=None, description=None, 
+                 epilog=None):
         self._settingses = dict()
         self._canonical_names = list()
 
         self.version = version
         self.progname = progname
+        self.usage = usage
         self.description = description
         self.epilog = epilog
         
@@ -291,6 +293,7 @@ class Settings(object):
 
         p = optparse.OptionParser(prog=self.progname, version=self.version,
                                   formatter=FormatHelpParagraphs(),
+                                  usage=self.usage,
                                   description=self.description,
                                   epilog=self.epilog)
         
diff --git a/example2.py b/example2.py
index d2b94a6..24d7579 100644
--- a/example2.py
+++ b/example2.py
@@ -28,10 +28,12 @@ import logging
 class ExampleApp(cliapp.Application):
 
     def cmd_greet(self, args):
+        '''Greet the user.'''
         for arg in args:
             self.output.write('greetings, %s\n' % arg)
             
     def cmd_insult(self, args):
+        '''Insult the user.'''
         for arg in args:
             self.output.write('you suck, %s\n' % arg)