Repository: pallets/click

Issue:
Deprecated notice in help text can be hard to see
The current `(DEPRECATED)` deprecation notice added to help text can be hard to see plainly since it can't consider the existing format of the help text.

For example:  I use sphinx style formatting in my help text and if this help text ends with a Note block like below:

```python
def encrypt(ctx, **kwargs):
    """Encrypt archives.

    .. Note::

        Here is a notice.
    """
```

Then a deprecation notice would append to the Note block, making it look like part of the Note and not that the command itself is deprecated.

```shell
Usage: cmd encrypt [OPTIONS]

  Encrypt archives.

  .. Note::

      Here is a notice. (DEPRECATED)
```

I would have expected the deprecation notice to be at the top of my help text making it clear to the user that this command is deprecated.  Or at the least a couple a new lines added to differentiate the notice from any existing help text.

Environment:

- Python version: Python 3.7.9
- Click version: click==7.1.2



Discussion:
This is something you could change by sub-classing `Command` and overriding the `format_help_text` method [here.](https://github.com/pallets/click/blob/1b1578dbbc706538914221352edc84d532cdd3a4/src/click/core.py#L1220)


@davidism I'm an MLH Fellow. I'm working on this Issue, notified here.

Resolving patch:
diff --git a/src/click/core.py b/src/click/core.py
--- a/src/click/core.py
+++ b/src/click/core.py
@@ -40,14 +40,6 @@
 SUBCOMMAND_METAVAR = "COMMAND [ARGS]..."
 SUBCOMMANDS_METAVAR = "COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]..."
 
-DEPRECATED_HELP_NOTICE = " (DEPRECATED)"
-DEPRECATED_INVOKE_NOTICE = "DeprecationWarning: The command {name} is deprecated."
-
-
-def _maybe_show_deprecated_notice(cmd):
-    if cmd.deprecated:
-        echo(style(DEPRECATED_INVOKE_NOTICE.format(name=cmd.name), fg="red"), err=True)
-
 
 def _fast_exit(code):
     """Low-level exit that skips Python's cleanup but speeds up exit by
@@ -1193,12 +1185,15 @@ def get_short_help_str(self, limit=45):
         """Gets short help for the command or makes it by shortening the
         long help string.
         """
-        return (
-            self.short_help
-            or self.help
-            and make_default_short_help(self.help, limit)
-            or ""
-        )
+        text = self.short_help or ""
+
+        if not text and self.help:
+            text = make_default_short_help(self.help, limit)
+
+        if self.deprecated:
+            text = f"(Deprecated) {text}"
+
+        return text.strip()
 
     def format_help(self, ctx, formatter):
         """Writes the help into the formatter if it exists.
@@ -1219,17 +1214,16 @@ def format_help(self, ctx, formatter):
 
     def format_help_text(self, ctx, formatter):
         """Writes the help text to the formatter if it exists."""
-        if self.help:
-            formatter.write_paragraph()
-            with formatter.indentation():
-                help_text = self.help
-                if self.deprecated:
-                    help_text += DEPRECATED_HELP_NOTICE
-                formatter.write_text(help_text)
-        elif self.deprecated:
+        text = self.help or ""
+
+        if self.deprecated:
+            text = f"(Deprecated) {text}"
+
+        if text:
             formatter.write_paragraph()
+
             with formatter.indentation():
-                formatter.write_text(DEPRECATED_HELP_NOTICE)
+                formatter.write_text(text)
 
     def format_options(self, ctx, formatter):
         """Writes all the options into the formatter if they exist."""
@@ -1275,7 +1269,15 @@ def invoke(self, ctx):
         """Given a context, this invokes the attached callback (if it exists)
         in the right way.
         """
-        _maybe_show_deprecated_notice(self)
+        if self.deprecated:
+            echo(
+                style(
+                    f"DeprecationWarning: The command {self.name!r} is deprecated.",
+                    fg="red",
+                ),
+                err=True,
+            )
+
         if self.callback is not None:
             return ctx.invoke(self.callback, **ctx.params)
 


Test patch:
diff --git a/tests/test_commands.py b/tests/test_commands.py
--- a/tests/test_commands.py
+++ b/tests/test_commands.py
@@ -297,14 +297,14 @@ def cmd_with_help():
         pass
 
     result = runner.invoke(cmd_with_help, ["--help"])
-    assert "(DEPRECATED)" in result.output
+    assert "(Deprecated)" in result.output
 
     @click.command(deprecated=True)
     def cmd_without_help():
         pass
 
     result = runner.invoke(cmd_without_help, ["--help"])
-    assert "(DEPRECATED)" in result.output
+    assert "(Deprecated)" in result.output
 
 
 def test_deprecated_in_invocation(runner):