From f7e3ac45097ea424dfd4fab426471979b1f60275 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <sfinucan@redhat.com>
Date: Thu, 6 Apr 2017 13:26:25 +0100
Subject: [PATCH] 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   |  6 ++++++
 cliff/sphinxext.py | 12 ++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/cliff/command.py b/cliff/command.py
index 8430563..7ad07fc 100644
--- a/cliff/command.py
+++ b/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
diff --git a/cliff/sphinxext.py b/cliff/sphinxext.py
index 4a37a2a..cb3543f 100644
--- a/cliff/sphinxext.py
+++ b/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):