[Docs] Filter Cog Guide (#4579)

* Add filter to index

* Initial generated docs

* Start on docstrings

* More docstrings

* Some more docstrings

* Rest of the doc strings

* Regenerate docs

* Remove unnecessary language. Move to one line.

* Regenerate docs

* Update redbot/cogs/filter/filter.py

Co-authored-by: Flame442 <34169552+Flame442@users.noreply.github.com>

* Update redbot/cogs/filter/filter.py

Co-authored-by: Flame442 <34169552+Flame442@users.noreply.github.com>

* Update redbot/cogs/filter/filter.py

Co-authored-by: Flame442 <34169552+Flame442@users.noreply.github.com>

* Update docs/cog_guides/filter.rst

Co-authored-by: Flame442 <34169552+Flame442@users.noreply.github.com>

* Update docs/cog_guides/filter.rst

Co-authored-by: Flame442 <34169552+Flame442@users.noreply.github.com>

* Update docs/cog_guides/filter.rst

Co-authored-by: Flame442 <34169552+Flame442@users.noreply.github.com>

Co-authored-by: Flame442 <34169552+Flame442@users.noreply.github.com>
Co-authored-by: jack1142 <6032823+jack1142@users.noreply.github.com>

docs/cog_guides/filter.rst

@@ -0,0 +1,303 @@
+.. _filter:
+
+======
+Filter
+======
+
+This is the cog guide for the filter 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 filter
+
+.. _filter-usage:
+
+-----
+Usage
+-----
+
+This cog is designed for "filtering" unwanted words and phrases from a server.
+
+It provides tools to manage a list of words or sentences, and to customize automatic actions to be taken against users who use those words in channels or in their name/nickname.
+
+This can be used to prevent inappropriate language, off-topic discussions, invite links, and more.
+
+
+.. _filter-commands:
+
+--------
+Commands
+--------
+
+.. _filter-command-filter:
+
+^^^^^^
+filter
+^^^^^^
+
+.. note:: |mod-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filter 
+
+**Description**
+
+Base command to add or remove words from the server filter.
+
+Use double quotes to add or remove sentences.
+
+.. _filter-command-filter-add:
+
+""""""""""
+filter add
+""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filter add [words...]
+
+**Description**
+
+Add words to the filter.
+
+Use double quotes to add sentences.
+
+Examples:
+    - ``[p]filter add word1 word2 word3``
+    - ``[p]filter add "This is a sentence"``
+
+**Arguments:**
+
+- ``[words...]`` The words or sentences to filter.
+
+.. _filter-command-filter-channel:
+
+""""""""""""""
+filter channel
+""""""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filter channel 
+
+**Description**
+
+Base command to add or remove words from the channel filter.
+
+Use double quotes to add or remove sentences.
+
+.. _filter-command-filter-channel-add:
+
+""""""""""""""""""
+filter channel add
+""""""""""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filter channel add [words...]
+
+**Description**
+
+Add words to the filter.
+
+Use double quotes to add sentences.
+
+Examples:
+    - ``[p]filter channel add word1 word2 word3``
+    - ``[p]filter channel add "This is a sentence"``
+
+**Arguments:**
+
+- ``[words...]`` The words or sentences to filter.
+
+.. _filter-command-filter-channel-list:
+
+"""""""""""""""""""
+filter channel list
+"""""""""""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filter channel list 
+
+**Description**
+
+Send a list of the channel's filtered words.
+
+.. _filter-command-filter-channel-remove:
+
+"""""""""""""""""""""
+filter channel remove
+"""""""""""""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filter channel remove [words...]
+
+**Description**
+
+Remove words from the filter.
+
+Use double quotes to remove sentences.
+
+Examples:
+    - ``[p]filter channel remove word1 word2 word3``
+    - ``[p]filter channel remove "This is a sentence"``
+
+**Arguments:**
+
+- ``[words...]`` The words or sentences to no longer filter.
+
+.. _filter-command-filter-delete:
+
+"""""""""""""
+filter delete
+"""""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filter delete [words...]
+
+.. tip:: Aliases: ``filter remove``, ``filter del``
+
+**Description**
+
+Remove words from the filter.
+
+Use double quotes to remove sentences.
+
+Examples:
+    - ``[p]filter remove word1 word2 word3``
+    - ``[p]filter remove "This is a sentence"``
+
+**Arguments:**
+
+- ``[words...]`` The words or sentences to no longer filter.
+
+.. _filter-command-filter-list:
+
+"""""""""""
+filter list
+"""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filter list 
+
+**Description**
+
+Send a list of this server's filtered words.
+
+.. _filter-command-filter-names:
+
+""""""""""""
+filter names
+""""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filter names 
+
+**Description**
+
+Toggle name and nickname filtering.
+
+This is disabled by default.
+
+.. _filter-command-filterset:
+
+^^^^^^^^^
+filterset
+^^^^^^^^^
+
+.. note:: |admin-lock|
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filterset 
+
+**Description**
+
+Base command to manage filter settings.
+
+.. _filter-command-filterset-ban:
+
+"""""""""""""
+filterset ban
+"""""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filterset ban <count> <timeframe>
+
+**Description**
+
+Set the filter's autoban conditions.
+
+Users will be banned if they send ``<count>`` filtered words in
+``<timeframe>`` seconds.
+
+Set both to zero to disable autoban.
+
+Examples:
+    - ``[p]filterset ban 5 5`` - Ban users who say 5 filtered words in 5 seconds.
+    - ``[p]filterset ban 2 20`` - Ban users who say 2 filtered words in 20 seconds.
+
+**Arguments:**
+
+- ``<count>`` The amount of filtered words required to trigger a ban.
+- ``<timeframe>`` The period of time in which too many filtered words will trigger a ban.
+
+.. _filter-command-filterset-defaultname:
+
+"""""""""""""""""""""
+filterset defaultname
+"""""""""""""""""""""
+
+**Syntax**
+
+.. code-block:: none
+
+    [p]filterset defaultname <name>
+
+**Description**
+
+Set the nickname for users with a filtered name.
+
+Note that this has no effect if filtering names is disabled
+(to toggle, run ``[p]filter names``).
+
+The default name used is *John Doe*.
+
+Example:
+    - ``[p]filterset defaultname Missingno``
+
+**Arguments:**
+
+- ``<name>`` The new nickname to assign.

docs/index.rst

@@ -40,6 +40,7 @@ Welcome to Red - Discord Bot's documentation!
     cog_guides/customcommands
     cog_guides/downloader
     cog_guides/economy
+    cog_guides/filter
     cog_guides/streams
     red_core_data_statement
 

redbot/cogs/filter/filter.py

@@ -14,7 +14,12 @@ _ = Translator("Filter", __file__)
 
 @cog_i18n(_)
 class Filter(commands.Cog):
-    """Filter unwanted words and phrases from text channels."""
+    """This cog is designed for "filtering" unwanted words and phrases from a server.
+
+    It provides tools to manage a list of words or sentences, and to customize automatic actions to be taken against users who use those words in channels or in their name/nickname.
+
+    This can be used to prevent inappropriate language, off-topic discussions, invite links, and more.
+    """
 
     def __init__(self, bot: Red):
         super().__init__()
@@ -66,7 +71,7 @@ class Filter(commands.Cog):
     @commands.guild_only()
     @checks.admin_or_permissions(manage_guild=True)
     async def filterset(self, ctx: commands.Context):
-        """Manage filter settings."""
+        """Base command to manage filter settings."""
         pass
 
     @filterset.command(name="defaultname")
@@ -77,6 +82,13 @@ class Filter(commands.Cog):
         (to toggle, run `[p]filter names`).
 
         The default name used is *John Doe*.
+
+        Example:
+            - `[p]filterset defaultname Missingno`
+
+        **Arguments:**
+
+        - `<name>` The new nickname to assign.
         """
         guild = ctx.guild
         await self.config.guild(guild).filter_default_name.set(name)
@@ -90,6 +102,15 @@ class Filter(commands.Cog):
         `<timeframe>` seconds.
 
         Set both to zero to disable autoban.
+
+        Examples:
+            - `[p]filterset ban 5 5` - Ban users who say 5 filtered words in 5 seconds.
+            - `[p]filterset ban 2 20` - Ban users who say 2 filtered words in 20 seconds.
+
+        **Arguments:**
+
+        - `<count>` The amount of filtered words required to trigger a ban.
+        - `<timeframe>` The period of time in which too many filtered words will trigger a ban.
         """
         if (count <= 0) != (timeframe <= 0):
             await ctx.send(
@@ -114,7 +135,7 @@ class Filter(commands.Cog):
     @commands.guild_only()
     @checks.mod_or_permissions(manage_messages=True)
     async def _filter(self, ctx: commands.Context):
-        """Add or remove words from server filter.
+        """Base command to add or remove words from the server filter.
 
         Use double quotes to add or remove sentences.
         """
@@ -122,7 +143,7 @@ class Filter(commands.Cog):
 
     @_filter.command(name="list")
     async def _global_list(self, ctx: commands.Context):
-        """Send a list of this servers filtered words."""
+        """Send a list of this server's filtered words."""
         server = ctx.guild
         author = ctx.author
         word_list = await self.config.guild(server).filter()
@@ -139,7 +160,7 @@ class Filter(commands.Cog):
 
     @_filter.group(name="channel")
     async def _filter_channel(self, ctx: commands.Context):
-        """Add or remove words from channel filter.
+        """Base command to add or remove words from the channel filter.
 
         Use double quotes to add or remove sentences.
         """
@@ -147,7 +168,7 @@ class Filter(commands.Cog):
 
     @_filter_channel.command(name="list")
     async def _channel_list(self, ctx: commands.Context):
-        """Send the list of the channel's filtered words."""
+        """Send a list of the channel's filtered words."""
         channel = ctx.channel
         author = ctx.author
         word_list = await self.config.channel(channel).filter()
@@ -171,6 +192,10 @@ class Filter(commands.Cog):
         Examples:
             - `[p]filter channel add word1 word2 word3`
             - `[p]filter channel add "This is a sentence"`
+
+        **Arguments:**
+
+        - `[words...]` The words or sentences to filter.
         """
         channel = ctx.channel
         added = await self.add_to_filter(channel, words)
@@ -189,6 +214,10 @@ class Filter(commands.Cog):
         Examples:
             - `[p]filter channel remove word1 word2 word3`
             - `[p]filter channel remove "This is a sentence"`
+
+        **Arguments:**
+
+        - `[words...]` The words or sentences to no longer filter.
         """
         channel = ctx.channel
         removed = await self.remove_from_filter(channel, words)
@@ -207,6 +236,10 @@ class Filter(commands.Cog):
         Examples:
             - `[p]filter add word1 word2 word3`
             - `[p]filter add "This is a sentence"`
+
+        **Arguments:**
+
+        - `[words...]` The words or sentences to filter.
         """
         server = ctx.guild
         added = await self.add_to_filter(server, words)
@@ -225,6 +258,10 @@ class Filter(commands.Cog):
         Examples:
             - `[p]filter remove word1 word2 word3`
             - `[p]filter remove "This is a sentence"`
+
+        **Arguments:**
+
+        - `[words...]` The words or sentences to no longer filter.
         """
         server = ctx.guild
         removed = await self.remove_from_filter(server, words)