Add support for epilogs

Signed-off-by: Stephen Finucane <stephen@that.guru>
Closes: #51

Author: stephenfin

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

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',