[Docs] Cleanup Cog Guide (#4488)

* Autogenerated doc and index spot

* Update command descriptions

* Use qualified name in titles and new command descriptions

* Add arguments to descriptions and cleanup self examples.

* Examples are bulleted and indented.

* Handle aliases (none), examples are bulleted and indented

* Switch to alphabetical

* Fix X typo

docs/cog_guides/cleanup.rst

@@ -0,0 +1,296 @@
+.. _cleanup:
+
+=======
+Cleanup
+=======
+
+This is the cog guide for the cleanup cog. You will
+find detailed docs about usage and commands.
+
+``[p]`` is considered as your prefix.
+
+.. note:: To use this cog, load it by typing this::
+
+        [p]load cleanup
+
+.. _cleanup-usage:
+
+-----
+Usage
+-----
+
+This cog contains commands used for "cleaning up" (deleting) messages.
+
+This is designed as a moderator tool and offers many convenient use cases.
+All cleanup commands only apply to the channel the command is executed in.
+
+Messages older than two weeks cannot be mass deleted.
+This is a limitation of the API.
+
+
+.. _cleanup-commands:
+
+--------
+Commands
+--------
+
+.. _cleanup-command-cleanup:
+
+^^^^^^^
+cleanup
+^^^^^^^
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup 
+
+**Description**
+
+Base command for deleting messages.
+
+.. _cleanup-command-cleanup-after:
+
+"""""""""""""
+cleanup after
+"""""""""""""
+
+.. note:: |mod-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup after <message_id> [delete_pinned=False]
+
+**Description**
+
+Delete all messages after a specified message.
+
+To get a message id, enable developer mode in Discord's
+settings, 'appearance' tab. Then right click a message
+and copy its id.
+
+**Arguments:**
+
+- ``<message_id>`` The id of the message to cleanup after. This message won't be deleted.
+- ``<delete_pinned>`` Whether to delete pinned messages or not. Defaults to False
+
+.. _cleanup-command-cleanup-before:
+
+""""""""""""""
+cleanup before
+""""""""""""""
+
+.. note:: |mod-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup before <message_id> <number> [delete_pinned=False]
+
+**Description**
+
+Deletes X messages before the specified message.
+
+To get a message id, enable developer mode in Discord's
+settings, 'appearance' tab. Then right click a message
+and copy its id.
+
+**Arguments:**
+
+- ``<message_id>`` The id of the message to cleanup before. This message won't be deleted.
+- ``<number>`` The max number of messages to cleanup. Must be a positive integer.
+- ``<delete_pinned>`` Whether to delete pinned messages or not. Defaults to False
+
+.. _cleanup-command-cleanup-between:
+
+"""""""""""""""
+cleanup between
+"""""""""""""""
+
+.. note:: |mod-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup between <one> <two> [delete_pinned=False]
+
+**Description**
+
+Delete the messages between Message One and Message Two, providing the messages IDs.
+
+The first message ID should be the older message and the second one the newer.
+
+Example:
+    - ``[p]cleanup between 123456789123456789 987654321987654321``
+
+**Arguments:**
+
+- ``<one>`` The id of the message to cleanup after. This message won't be deleted.
+- ``<two>`` The id of the message to cleanup before. This message won't be deleted.
+- ``<delete_pinned>`` Whether to delete pinned messages or not. Defaults to False
+
+.. _cleanup-command-cleanup-bot:
+
+"""""""""""
+cleanup bot
+"""""""""""
+
+.. note:: |mod-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup bot <number> [delete_pinned=False]
+
+**Description**
+
+Clean up command messages and messages from the bot.
+
+Can only cleanup custom commands and alias commands if those cogs are loaded.
+
+**Arguments:**
+
+- ``<number>`` The max number of messages to cleanup. Must be a positive integer.
+- ``<delete_pinned>`` Whether to delete pinned messages or not. Defaults to False
+
+.. _cleanup-command-cleanup-messages:
+
+""""""""""""""""
+cleanup messages
+""""""""""""""""
+
+.. note:: |mod-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup messages <number> [delete_pinned=False]
+
+**Description**
+
+Delete the last X messages.
+
+Example:
+    - ``[p]cleanup messages 26``
+
+**Arguments:**
+
+- ``<number>`` The max number of messages to cleanup. Must be a positive integer.
+- ``<delete_pinned>`` Whether to delete pinned messages or not. Defaults to False
+
+.. _cleanup-command-cleanup-self:
+
+""""""""""""
+cleanup self
+""""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup self <number> [match_pattern] [delete_pinned=False]
+
+**Description**
+
+Clean up messages owned by the bot.
+
+By default, all messages are cleaned. If a second argument is specified,
+it is used for pattern matching - only messages containing the given text will be deleted.
+
+Examples:
+    - ``[p]cleanup self 6``
+    - ``[p]cleanup self 10 Pong``
+    - ``[p]cleanup self 7 "" True``
+
+**Arguments:**
+
+- ``<number>`` The max number of messages to cleanup. Must be a positive integer.
+- ``<match_pattern>`` The text that messages must contain to be deleted. Use "" to skip this.
+- ``<delete_pinned>`` Whether to delete pinned messages or not. Defaults to False
+
+.. _cleanup-command-cleanup-spam:
+
+""""""""""""
+cleanup spam
+""""""""""""
+
+.. note:: |mod-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup spam [number=50]
+
+**Description**
+
+Deletes duplicate messages in the channel from the last X messages and keeps only one copy.
+
+Defaults to 50.
+
+**Arguments:**
+
+- ``<number>`` The number of messages to check for duplicates. Must be a positive integer.
+
+.. _cleanup-command-cleanup-text:
+
+""""""""""""
+cleanup text
+""""""""""""
+
+.. note:: |mod-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup text <text> <number> [delete_pinned=False]
+
+**Description**
+
+Delete the last X messages matching the specified text.
+
+Example:
+    - ``[p]cleanup text "test" 5``
+
+Remember to use double quotes.
+
+**Arguments:**
+
+- ``<number>`` The max number of messages to cleanup. Must be a positive integer.
+- ``<delete_pinned>`` Whether to delete pinned messages or not. Defaults to False
+
+.. _cleanup-command-cleanup-user:
+
+""""""""""""
+cleanup user
+""""""""""""
+
+.. note:: |mod-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]cleanup user <user> <number> [delete_pinned=False]
+
+**Description**
+
+Delete the last X messages from a specified user.
+
+Examples:
+    - ``[p]cleanup user @Twentysix 2``
+    - ``[p]cleanup user Red 6``
+
+**Arguments:**
+
+- ``<user>`` The user whose messages are to be cleaned up.
+- ``<number>`` The max number of messages to cleanup. Must be a positive integer.
+- ``<delete_pinned>`` Whether to delete pinned messages or not. Defaults to False

docs/index.rst

@@ -35,6 +35,7 @@ Welcome to Red - Discord Bot's documentation!
     cog_guides/admin
     cog_guides/alias
     cog_guides/bank
+    cog_guides/cleanup
     red_core_data_statement
 
 .. toctree::

redbot/cogs/cleanup/cleanup.py

@@ -20,7 +20,14 @@ log = logging.getLogger("red.cleanup")
 
 @cog_i18n(_)
 class Cleanup(commands.Cog):
-    """Commands for cleaning up messages."""
+    """This cog contains commands used for "cleaning up" (deleting) messages.
+
+    This is designed as a moderator tool and offers many convenient use cases.
+    All cleanup commands only apply to the channel the command is executed in.
+
+    Messages older than two weeks cannot be mass deleted.
+    This is a limitation of the API.
+    """
 
     def __init__(self, bot: Red):
         super().__init__()
@@ -117,7 +124,7 @@ class Cleanup(commands.Cog):
 
     @commands.group()
     async def cleanup(self, ctx: commands.Context):
-        """Delete messages."""
+        """Base command for deleting messages."""
         pass
 
     @cleanup.command()
@@ -130,9 +137,14 @@ class Cleanup(commands.Cog):
         """Delete the last X messages matching the specified text.
 
         Example:
-            `[p]cleanup text "test" 5`
+            - `[p]cleanup text "test" 5`
 
         Remember to use double quotes.
+
+        **Arguments:**
+
+        - `<number>` The max number of messages to cleanup. Must be a positive integer.
+        - `<delete_pinned>` Whether to delete pinned messages or not. Defaults to False
         """
 
         channel = ctx.channel
@@ -180,8 +192,14 @@ class Cleanup(commands.Cog):
         """Delete the last X messages from a specified user.
 
         Examples:
-            `[p]cleanup user @\u200bTwentysix 2`
-            `[p]cleanup user Red 6`
+            - `[p]cleanup user @Twentysix 2`
+            - `[p]cleanup user Red 6`
+
+        **Arguments:**
+
+        - `<user>` The user whose messages are to be cleaned up.
+        - `<number>` The max number of messages to cleanup. Must be a positive integer.
+        - `<delete_pinned>` Whether to delete pinned messages or not. Defaults to False
         """
         channel = ctx.channel
 
@@ -246,6 +264,11 @@ class Cleanup(commands.Cog):
         To get a message id, enable developer mode in Discord's
         settings, 'appearance' tab. Then right click a message
         and copy its id.
+
+        **Arguments:**
+
+        - `<message_id>` The id of the message to cleanup after. This message won't be deleted.
+        - `<delete_pinned>` Whether to delete pinned messages or not. Defaults to False
         """
 
         channel = ctx.channel
@@ -281,11 +304,17 @@ class Cleanup(commands.Cog):
         number: positive_int,
         delete_pinned: bool = False,
     ):
-        """Deletes X messages before specified message.
+        """Deletes X messages before the specified message.
 
         To get a message id, enable developer mode in Discord's
         settings, 'appearance' tab. Then right click a message
         and copy its id.
+
+        **Arguments:**
+
+        - `<message_id>` The id of the message to cleanup before. This message won't be deleted.
+        - `<number>` The max number of messages to cleanup. Must be a positive integer.
+        - `<delete_pinned>` Whether to delete pinned messages or not. Defaults to False
         """
 
         channel = ctx.channel
@@ -327,7 +356,13 @@ class Cleanup(commands.Cog):
         The first message ID should be the older message and the second one the newer.
 
         Example:
-            `[p]cleanup between 123456789123456789 987654321987654321`
+            - `[p]cleanup between 123456789123456789 987654321987654321`
+
+        **Arguments:**
+
+        - `<one>` The id of the message to cleanup after. This message won't be deleted.
+        - `<two>` The id of the message to cleanup before. This message won't be deleted.
+        - `<delete_pinned>` Whether to delete pinned messages or not. Defaults to False
         """
         channel = ctx.channel
         author = ctx.author
@@ -367,7 +402,12 @@ class Cleanup(commands.Cog):
         """Delete the last X messages.
 
         Example:
-            `[p]cleanup messages 26`
+            - `[p]cleanup messages 26`
+
+        **Arguments:**
+
+        - `<number>` The max number of messages to cleanup. Must be a positive integer.
+        - `<delete_pinned>` Whether to delete pinned messages or not. Defaults to False
         """
 
         channel = ctx.channel
@@ -397,7 +437,15 @@ class Cleanup(commands.Cog):
     async def cleanup_bot(
         self, ctx: commands.Context, number: positive_int, delete_pinned: bool = False
     ):
-        """Clean up command messages and messages from the bot."""
+        """Clean up command messages and messages from the bot.
+
+        Can only cleanup custom commands and alias commands if those cogs are loaded.
+
+        **Arguments:**
+
+        - `<number>` The max number of messages to cleanup. Must be a positive integer.
+        - `<delete_pinned>` Whether to delete pinned messages or not. Defaults to False
+        """
 
         channel = ctx.channel
         author = ctx.message.author
@@ -479,8 +527,19 @@ class Cleanup(commands.Cog):
     ):
         """Clean up messages owned by the bot.
 
-        By default, all messages are cleaned. If a third argument is specified,
+        By default, all messages are cleaned. If a second argument is specified,
         it is used for pattern matching - only messages containing the given text will be deleted.
+
+        Examples:
+            - `[p]cleanup self 6`
+            - `[p]cleanup self 10 Pong`
+            - `[p]cleanup self 7 "" True`
+
+        **Arguments:**
+
+        - `<number>` The max number of messages to cleanup. Must be a positive integer.
+        - `<match_pattern>` The text that messages must contain to be deleted. Use "" to skip this.
+        - `<delete_pinned>` Whether to delete pinned messages or not. Defaults to False
         """
         channel = ctx.channel
         author = ctx.message.author
@@ -551,6 +610,10 @@ class Cleanup(commands.Cog):
         """Deletes duplicate messages in the channel from the last X messages and keeps only one copy.
 
         Defaults to 50.
+
+        **Arguments:**
+
+        - `<number>` The number of messages to check for duplicates. Must be a positive integer.
         """
         msgs = []
         spam = []