Resolved Issue #161 - Ability to override usage

cement/core/controller.py

@@ -23,6 +23,7 @@ def controller_validator(klass, obj):
         'config_section',
         'config_defaults',
         'arguments',
+        'usage',
         'epilog',
         'stacked_on',
         'hide',
@@ -243,6 +244,14 @@ class CementBaseController(handler.CementBaseHandler):
         The text that is displayed at the bottom when '--help' is passed.
         """
         
+        usage = None
+        """
+        The text that is displayed at the top when '--help' is passed.  
+        Although the default is `None`, Cement will set this to a generic
+        usage based on the `prog`, `controller` name, etc if nothing else is
+        passed.
+        """
+        
         argument_formatter = argparse.RawDescriptionHelpFormatter
         """
         The argument formatter class to use to display --help output.
@@ -532,6 +541,9 @@ class CementBaseController(handler.CementBaseHandler):
     def _usage_text(self):
         """Returns the usage text displayed when '--help' is passed."""
         
+        if self._meta.usage is not None:
+            return self._meta.usage
+            
         if self == self.app._meta.base_controller:
             txt = "%s <CMD> -opt1 --opt2=VAL [arg1] [arg2] ..." % \
                 self.app.args.prog

tests/core/controller_tests.py

@@ -64,7 +64,9 @@ class TestBaseController2(controller.CementBaseController):
         config_defaults = {}
         arguments = []
         hide = False
-    
+        epilog = 'Test Epilog'
+        usage = 'Test Usage'
+        
     @controller.expose()
     def my_command(self):
         pass
@@ -381,3 +383,10 @@ class ControllerTestCase(test.CementTestCase):
         except exc.FrameworkError as e:
             self.ok(e.msg.find('collides'))
             raise
+
+    def test_usage_text(self):
+        self.app.setup()
+        contr = TestBaseController2()
+        contr._setup(self.app)
+        self.eq(contr._usage_text, 'Test Usage')
+