shortdoc should be formatted too, + generic replacement method (#3451)

redbot/core/commands/commands.py

@@ -93,6 +93,45 @@ class CogCommandMixin:
             checks=getattr(decorated, "__requires_checks__", []),
         )
 
+    def format_text_for_context(self, ctx: "Context", text: str) -> str:
+        """
+        This formats text based on values in context
+
+        The steps are (currently, roughly) the following:
+
+            - substitute ``[p]`` with ``ctx.clean_prefix``
+            - substitute ``[botname]`` with ``ctx.me.display_name``
+
+        More steps may be added at a later time.
+
+        Cog creators should only override this if they want
+        help text to be modified, and may also want to
+        look at `format_help_for_context` and (for commands only)
+        ``format_shortdoc_for_context``
+
+        Parameters
+        ----------
+        ctx: Context
+        text: str
+
+        Returns
+        -------
+        str
+            text which has had some portions replaced based on context
+        """
+        formatting_pattern = re.compile(r"\[p\]|\[botname\]")
+
+        def replacement(m: re.Match) -> str:
+            s = m.group(0)
+            if s == "[p]":
+                return ctx.clean_prefix
+            if s == "[botname]":
+                return ctx.me.display_name
+            # We shouldnt get here:
+            return s
+
+        return formatting_pattern.sub(replacement, text)
+
     def format_help_for_context(self, ctx: "Context") -> str:
         """
         This formats the help string based on values in context
@@ -123,18 +162,7 @@ class CogCommandMixin:
             # Short circuit out on an empty help string
             return help_str
 
-        formatting_pattern = re.compile(r"\[p\]|\[botname\]")
-
-        def replacement(m: re.Match) -> str:
-            s = m.group(0)
-            if s == "[p]":
-                return ctx.clean_prefix
-            if s == "[botname]":
-                return ctx.me.display_name
-            # We shouldnt get here:
-            return s
-
-        return formatting_pattern.sub(replacement, help_str)
+        return self.format_text_for_context(ctx, help_str)
 
     def allow_for(self, model_id: Union[int, str], guild_id: int) -> None:
         """Actively allow this command for the given model.
@@ -619,6 +647,28 @@ class Command(CogCommandMixin, DPYCommand):
         """
         return super().error(coro)
 
+    def format_shortdoc_for_context(self, ctx: "Context") -> str:
+        """
+        This formats the short version of the help 
+        tring based on values in context
+
+        See ``format_text_for_context`` for the actual implementation details
+
+        Cog creators may override this in their own command classes
+        as long as the method signature stays the same.
+
+        Parameters
+        ----------
+        ctx: Context
+
+        Returns
+        -------
+        str
+            Localized help with some formatting
+        """
+        sh = self.short_doc
+        return self.format_text_for_context(ctx, sh) if sh else sh
+
 
 class GroupMixin(discord.ext.commands.GroupMixin):
     """Mixin for `Group` and `Red` classes.

redbot/core/commands/help.py

@@ -224,7 +224,7 @@ class RedHelpFormatter:
                     return a_line[:67] + "..."
 
                 subtext = "\n".join(
-                    shorten_line(f"**{name}** {command.short_doc}")
+                    shorten_line(f"**{name}** {command.format_shortdoc_for_context(ctx)}")
                     for name, command in sorted(subcommands.items())
                 )
                 for i, page in enumerate(pagify(subtext, page_length=500, shorten_by=0)):
@@ -249,7 +249,7 @@ class RedHelpFormatter:
                     doc_max_width = 80 - max_width
                     for nm, com in sorted(cmds):
                         width_gap = discord.utils._string_width(nm) - len(nm)
-                        doc = com.short_doc
+                        doc = com.format_shortdoc_for_context(ctx)
                         if len(doc) > doc_max_width:
                             doc = doc[: doc_max_width - 3] + "..."
                         yield nm, doc, max_width - width_gap
@@ -399,7 +399,7 @@ class RedHelpFormatter:
                     return a_line[:67] + "..."
 
                 command_text = "\n".join(
-                    shorten_line(f"**{name}** {command.short_doc}")
+                    shorten_line(f"**{name}** {command.format_shortdoc_for_context(ctx)}")
                     for name, command in sorted(coms.items())
                 )
                 for i, page in enumerate(pagify(command_text, page_length=500, shorten_by=0)):
@@ -423,7 +423,7 @@ class RedHelpFormatter:
                     doc_max_width = 80 - max_width
                     for nm, com in sorted(cmds):
                         width_gap = discord.utils._string_width(nm) - len(nm)
-                        doc = com.short_doc
+                        doc = com.format_shortdoc_for_context(ctx)
                         if len(doc) > doc_max_width:
                             doc = doc[: doc_max_width - 3] + "..."
                         yield nm, doc, max_width - width_gap
@@ -466,7 +466,7 @@ class RedHelpFormatter:
                     return a_line[:67] + "..."
 
                 cog_text = "\n".join(
-                    shorten_line(f"**{name}** {command.short_doc}")
+                    shorten_line(f"**{name}** {command.format_shortdoc_for_context(ctx)}")
                     for name, command in sorted(data.items())
                 )
 
@@ -494,7 +494,7 @@ class RedHelpFormatter:
                 doc_max_width = 80 - max_width
                 for nm, com in cmds:
                     width_gap = discord.utils._string_width(nm) - len(nm)
-                    doc = com.short_doc
+                    doc = com.format_shortdoc_for_context(ctx)
                     if len(doc) > doc_max_width:
                         doc = doc[: doc_max_width - 3] + "..."
                     yield nm, doc, max_width - width_gap