From 8d512e206a45148f34b6fc52e9d038c47190fcb5 Mon Sep 17 00:00:00 2001 From: bobloy Date: Fri, 15 Jan 2021 21:10:45 -0500 Subject: [PATCH] [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 | 303 +++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + redbot/cogs/filter/filter.py | 65 ++++++-- 3 files changed, 355 insertions(+), 14 deletions(-) create mode 100644 docs/cog_guides/filter.rst diff --git a/docs/cog_guides/filter.rst b/docs/cog_guides/filter.rst new file mode 100644 index 000000000..ec7c3a650 --- /dev/null +++ b/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 + +**Description** + +Set the filter's autoban conditions. + +Users will be banned if they send ```` filtered words in +```` 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:** + +- ```` The amount of filtered words required to trigger a ban. +- ```` 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 + +**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:** + +- ```` The new nickname to assign. diff --git a/docs/index.rst b/docs/index.rst index 15c52b206..31dc65c2c 100644 --- a/docs/index.rst +++ b/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 diff --git a/redbot/cogs/filter/filter.py b/redbot/cogs/filter/filter.py index c9a888265..daf1769df 100644 --- a/redbot/cogs/filter/filter.py +++ b/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:** + + - `` 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): `` 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:** + + - `` The amount of filtered words required to trigger a ban. + - `` 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() @@ -169,8 +190,12 @@ class Filter(commands.Cog): Use double quotes to add sentences. Examples: - - `[p]filter channel add word1 word2 word3` - - `[p]filter channel add "This is a sentence"` + - `[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) @@ -187,8 +212,12 @@ class Filter(commands.Cog): Use double quotes to remove sentences. Examples: - - `[p]filter channel remove word1 word2 word3` - - `[p]filter channel remove "This is a sentence"` + - `[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) @@ -205,8 +234,12 @@ class Filter(commands.Cog): Use double quotes to add sentences. Examples: - - `[p]filter add word1 word2 word3` - - `[p]filter add "This is a sentence"` + - `[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) @@ -223,8 +256,12 @@ class Filter(commands.Cog): Use double quotes to remove sentences. Examples: - - `[p]filter remove word1 word2 word3` - - `[p]filter remove "This is a sentence"` + - `[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)