Store raw help string for commands

Some tools, such as sphinx-click [1], may wish to access the full help
string for a command including any text after the form feed character
(which indicates truncation [2]). Make this possible by storing the
help string without truncation and instead truncate when we use this
string (i.e. truncate on load, not on store).

[1] https://github.com/click-contrib/sphinx-click/issues/56
[2] https://click.palletsprojects.com/en/latest/documentation/#truncating-help-texts

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

3 files changed, 27 insertions, 7 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 35307d4..ebf14e6 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -33,6 +33,8 @@ Version 8.1.0
     processed. :issue:`1985`
 -   A flag option with ``required=True`` requires that the flag is
     passed instead of choosing the implicit default value. :issue:`1978`
+-   Store untruncated help string in ``Command.help``, and perform
+    truncation when formatting. :issue:`2149`
 
 
 Version 8.0.4
diff --git a/src/click/core.py b/src/click/core.py
index 1ab2b20..95a4761 100644
--- a/src/click/core.py
+++ b/src/click/core.py
@@ -1156,6 +1156,10 @@ class Command(BaseCommand):
                              the command is deprecated.
 
     .. versionchanged:: 8.1
+        ``help`` is stored untruncated, the formatter applied
+        truncation later.
+
+    .. versionchanged:: 8.1
         Indentation in ``help`` is cleaned here instead of only in the
         ``@command`` decorator. ``epilog`` and ``short_help`` are also
         cleaned.
@@ -1197,12 +1201,6 @@ class Command(BaseCommand):
         if help:
             help = inspect.cleandoc(help)
 
-            # Discard help text after a first form feed (page break)
-            # character, to allow writing longer documentation in
-            # docstrings that does not show in help output.
-            if "\f" in help:
-                help = help.partition("\f")[0]
-
         if epilog:
             epilog = inspect.cleandoc(epilog)
 
@@ -1222,7 +1220,9 @@ class Command(BaseCommand):
         info_dict = super().to_info_dict(ctx)
         info_dict.update(
             params=[param.to_info_dict() for param in self.get_params(ctx)],
-            help=self.help,
+            # truncate help text to the content preceding the first form feed,
+            # if any
+            help=self.help.split("\f", 1)[0] if self.help else self.help,
             epilog=self.epilog,
             short_help=self.short_help,
             hidden=self.hidden,
@@ -1347,6 +1347,10 @@ class Command(BaseCommand):
         """Writes the help text to the formatter if it exists."""
         text = self.help or ""
 
+        # truncate the help text to the content preceding the first form feed,
+        # if any
+        text = text.split("\f", 1)[0]
+
         if self.deprecated:
             text = _("(Deprecated) {text}").format(text=text)
 
diff --git a/tests/test_commands.py b/tests/test_commands.py
index fa2773d..bf6a5db 100644
--- a/tests/test_commands.py
+++ b/tests/test_commands.py
@@ -95,6 +95,20 @@ def test_auto_shorthelp(runner):
     )
 
 
+def test_help_truncation(runner):
+    @click.command()
+    def cli():
+        """This is a command with truncated help.
+        \f
+
+        This text should be truncated.
+        """
+
+    result = runner.invoke(cli, ["--help"])
+    assert result.exit_code == 0
+    assert "This is a command with truncated help." in result.output
+
+
 def test_no_args_is_help(runner):
     @click.command(no_args_is_help=True)
     def cli():