Rebase of #629; allow use of page break to split docstring-based helptext

click/core.py

@@ -778,6 +778,10 @@ def __init__(self, name, context_settings=None, callback=None,
         #: should show up in the help page and execute.  Eager parameters
         #: will automatically be handled before non eager ones.
         self.params = params or []
+        # if a form feed (page break) is found in the help text, truncate help
+        # text to the content preceding the first form feed
+        if help and '\f' in help:
+            help = help.split('\f', 1)[0]
         self.help = help
         self.epilog = epilog
         self.options_metavar = options_metavar

docs/documentation.rst

@@ -78,6 +78,40 @@ And what it looks like:
 
 .. _doc-meta-variables:
 
+Truncating Help Texts
+---------------------
+
+Click gets command help text from function docstrings.  However if you
+already use docstrings to document function arguments you may not want
+to see :param: and :return: lines in your help text.
+
+You can use the ``\f`` escape marker to have Click truncate the help text
+after the marker.
+
+Example:
+
+.. click:example::
+
+    @click.command()
+    @click.pass_context
+    def cli(ctx):
+        """First paragraph.
+
+        This is a very long second
+        paragraph and not correctly
+        wrapped but it will be rewrapped.
+        \f
+
+        :param click.core.Context ctx: Click context.
+        """
+
+And what it looks like:
+
+.. click:run::
+
+    invoke(cli, args=['--help'])
+
+
 Meta Variables
 --------------
 

tests/test_formatting.py

@@ -268,3 +268,32 @@ def cmd(param):
         'Options:',
         '  --help  Show this message and exit.'
     ]
+
+
+def test_truncating_docstring(runner):
+    @click.command()
+    @click.pass_context
+    def cli(ctx):
+        """First paragraph.
+
+        This is a very long second
+        paragraph and not correctly
+        wrapped but it will be rewrapped.
+        \f
+
+        :param click.core.Context ctx: Click context.
+        """
+
+    result = runner.invoke(cli, ['--help'], terminal_width=60)
+    assert not result.exception
+    assert result.output.splitlines() == [
+        'Usage: cli [OPTIONS]',
+        '',
+        '  First paragraph.',
+        '',
+        '  This is a very long second paragraph and not correctly',
+        '  wrapped but it will be rewrapped.',
+        '',
+        'Options:',
+        '  --help  Show this message and exit.',
+    ]