Add support for epilogs

An epilog is text that's displayed after the argument help. It can be
useful to provide some broader context as to the command in question.

This change update the 'sphinxext' plugin to include this in its output.

Change-Id: I7f0bf8ba92dc34cc2e3e9fa2a93ec91ee2f9f8ac

cliff/command.py

@@ -30,6 +30,7 @@ class Command(object):
     deprecated = False
 
     _description = ''
+    _epilog = None
 
     def __init__(self, app, app_args, cmd_name=None):
         self.app = app
@@ -59,11 +60,16 @@ class Command(object):
             desc = ''
         return desc
 
+    def get_epilog(self):
+        """Return the command epilog."""
+        return self._epilog
+
     def get_parser(self, prog_name):
         """Return an :class:`argparse.ArgumentParser`.
         """
         parser = argparse.ArgumentParser(
             description=self.get_description(),
+            epilog=self.get_epilog(),
             prog=prog_name,
         )
         return parser

cliff/sphinxext.py

@@ -176,6 +176,7 @@ class AutoprogramCliffDirective(rst.Directive):
         command = command_class(None, None)
         parser = command.get_parser(command_name)
         description = command.get_description()
+        epilog = command.get_epilog()
 
         # Drop the automatically-added help action
         for action in parser._actions:
@@ -216,6 +217,17 @@ class AutoprogramCliffDirective(rst.Directive):
 
         self.state.nested_parse(result, 0, section)
 
+        # Epilog
+
+        # Like description, this is parsed as reStructuredText
+
+        if epilog:
+            result.append('', source_name)
+
+            for line in statemachine.string2lines(
+                    epilog, tab_width=4, convert_whitespace=True):
+                result.append(line, source_name)
+
         return [section]
 
     def run(self):