From 93c371dadb23d72017ff3bfd892b8d32d0d2bc96 Mon Sep 17 00:00:00 2001
From: Robert Pooley <rpooley@uber.com>
Date: Wed, 10 Aug 2016 19:15:01 +0000
Subject: [PATCH 1/2] Add ability to truncate help text in docstrings.

I use docstrings in all of my functions to document function arguments
so it makes me sad that I couldn't exclude :param: and other tags from
my command help texts.

Here I am introducing the ability for Click to truncate help text in
docstrings using the \f form feed escaped character. I chose it
randomly.
---
 click/core.py            |  2 ++
 docs/documentation.rst   | 34 ++++++++++++++++++++++++++++++++++
 tests/test_formatting.py | 29 +++++++++++++++++++++++++++++
 3 files changed, 65 insertions(+)

diff --git a/click/core.py b/click/core.py
index 525b09111..165f798b3 100644
--- a/click/core.py
+++ b/click/core.py
@@ -778,6 +778,8 @@ 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 help and '\f' in help:
+            help = help.split('\f', 1)[0]
         self.help = help
         self.epilog = epilog
         self.options_metavar = options_metavar
diff --git a/docs/documentation.rst b/docs/documentation.rst
index c9788b2f0..6d582e00b 100644
--- a/docs/documentation.rst
+++ b/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
 --------------
 
diff --git a/tests/test_formatting.py b/tests/test_formatting.py
index 0c0607328..2005f98b5 100644
--- a/tests/test_formatting.py
+++ b/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.',
+    ]

From f9e0dbef6a1fb1e72bc4c1f29bfbfd4cbe2af7f5 Mon Sep 17 00:00:00 2001
From: Stephen Rosen <sirosen@globus.org>
Date: Wed, 15 Aug 2018 00:54:22 +0000
Subject: [PATCH 2/2] Add requested comment for clarity

closes #629
---
 click/core.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/click/core.py b/click/core.py
index 165f798b3..9d1065e38 100644
--- a/click/core.py
+++ b/click/core.py
@@ -778,6 +778,8 @@ 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