From ef86b066fbc1f8a19bc0f5229aa093342e7e124f Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephen@that.guru>
Date: Thu, 23 Jul 2020 12:13:38 +0100
Subject: [PATCH] Add support for epilogs

Signed-off-by: Stephen Finucane <stephen@that.guru>
Closes: #51
---
 sphinx_click/ext.py     | 22 ++++++++++++++++++++++
 tests/test_formatter.py | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/sphinx_click/ext.py b/sphinx_click/ext.py
index f58736c..eabdb8e 100644
--- a/sphinx_click/ext.py
+++ b/sphinx_click/ext.py
@@ -225,6 +225,23 @@ def _format_subcommand(command):
             yield _indent(line)
 
 
+def _format_epilog(ctx):
+    """Format the epilog for a given `click.Command`.
+
+    We parse this as reStructuredText, allowing users to embed rich
+    information in their help messages if they so choose.
+    """
+    epilog_string = ctx.command.epilog
+    if not epilog_string:
+        return
+
+    for line in statemachine.string2lines(
+        epilog_string, tab_width=4, convert_whitespace=True
+    ):
+        yield line
+    yield ''
+
+
 def _get_lazyload_commands(multicommand):
     commands = {}
     for command in multicommand.list_commands(multicommand):
@@ -295,6 +312,11 @@ def _format_command(ctx, show_nested, commands=None):
     for line in lines:
         yield line
 
+    # description
+
+    for line in _format_epilog(ctx):
+        yield line
+
     # if we're nesting commands, we need to do this slightly differently
     if show_nested:
         return
diff --git a/tests/test_formatter.py b/tests/test_formatter.py
index a1ca045..a5756f6 100644
--- a/tests/test_formatter.py
+++ b/tests/test_formatter.py
@@ -112,6 +112,39 @@ def foobar(bar):
             '\n'.join(output),
         )
 
+    def test_help_epilog(self):
+        """Validate formatting of explicit help and epilog strings."""
+
+        @click.command(help='A sample command.', epilog='A sample epilog.')
+        @click.option('--param', help='A sample option')
+        def foobar(bar):
+            pass
+
+        ctx = click.Context(foobar, info_name='foobar')
+        output = list(ext._format_command(ctx, show_nested=False))
+
+        self.assertEqual(
+            textwrap.dedent(
+                """
+        A sample command.
+
+        .. program:: foobar
+        .. code-block:: shell
+
+            foobar [OPTIONS]
+
+        .. rubric:: Options
+
+        .. option:: --param <param>
+
+            A sample option
+
+        A sample epilog.
+        """
+            ).lstrip(),
+            '\n'.join(output),
+        )
+
     @unittest.skipIf(
         ext.CLICK_VERSION < (7, 0),
         'Allowing show_default to be a string was added in Click 7.0',