diff --git a/.github/labeler.yml b/.github/labeler.yml index cecbff914..7b475ea3e 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -177,4 +177,7 @@ # Docs - docs/framework_utils.rst "Category: Warnings": + # Source - redbot/cogs/warnings/* + # Docs + - docs/cog_guides/warnings.rst diff --git a/docs/cog_guides/warnings.rst b/docs/cog_guides/warnings.rst new file mode 100644 index 000000000..a0264e247 --- /dev/null +++ b/docs/cog_guides/warnings.rst @@ -0,0 +1,403 @@ +.. _warnings: + +======== +Warnings +======== + +This is the cog guide for the warnings 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 warnings + +.. _warnings-usage: + +----- +Usage +----- + +Warn misbehaving users and take automated actions. + + +.. _warnings-commands: + +-------- +Commands +-------- + +.. _warnings-command-actionlist: + +^^^^^^^^^^ +actionlist +^^^^^^^^^^ + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]actionlist + +**Description** + +List all configured automated actions for Warnings. + +.. _warnings-command-mywarnings: + +^^^^^^^^^^ +mywarnings +^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]mywarnings + +**Description** + +List warnings for yourself. + +.. _warnings-command-reasonlist: + +^^^^^^^^^^ +reasonlist +^^^^^^^^^^ + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]reasonlist + +**Description** + +List all configured reasons for Warnings. + +.. _warnings-command-unwarn: + +^^^^^^ +unwarn +^^^^^^ + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]unwarn [reason] + +**Description** + +Remove a warning from a member. + +**Arguments** + +* ````: The member to remove the warning from. |member-input-quotes| +* ````: The warning ID to remove from the member. +* ``[reason]``: The reason for unwarning this member. + +.. _warnings-command-warn: + +^^^^ +warn +^^^^ + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]warn [points=1] + +**Description** + +Warn the user for the specified reason. + +**Arguments** + +* ````: The member to warn. |member-input-quotes| +* ``[points]``: The number of points the warning should be for. If no number is supplied, 1 point will be given. Pre-set warnings disregard this. +* ````: The reason for the warning. This can be a registered reason, or a custom reason if ``[p]warningset allowcustomreasons`` is set. + +.. _warnings-command-warnaction: + +^^^^^^^^^^ +warnaction +^^^^^^^^^^ + +.. note:: |guildowner-lock| + +**Syntax** + +.. code-block:: none + + [p]warnaction + +**Description** + +Manage automated actions for Warnings. + +Actions are essentially command macros. Any command can be run +when the action is initially triggered, and/or when the action +is lifted. + +Actions must be given a name and a points threshold. When a +user is warned enough so that their points go over this +threshold, the action will be executed. + +.. _warnings-command-warnaction-add: + +"""""""""""""" +warnaction add +"""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]warnaction add + +**Description** + +Create an automated action. + +Duplicate action names are not allowed. + +**Arguments** + +* ````: The name of the action. +* ````: The number of points for this action. + +.. _warnings-command-warnaction-delete: + +""""""""""""""""" +warnaction delete +""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]warnaction delete + +**Description** + +Delete the action with the specified name. + +**Arguments** + +* ````: The name of the action to delete. + +.. _warnings-command-warnings: + +^^^^^^^^ +warnings +^^^^^^^^ + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]warnings + +**Description** + +List the warnings for the specified member. + +**Arguments** + +* ````: The member to get the warnings for. |member-input| + +.. _warnings-command-warningset: + +^^^^^^^^^^ +warningset +^^^^^^^^^^ + +.. note:: |guildowner-lock| + +**Syntax** + +.. code-block:: none + + [p]warningset + +**Description** + +Manage settings for Warnings. + +.. _warnings-command-warningset-allowcustomreasons: + +""""""""""""""""""""""""""""" +warningset allowcustomreasons +""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]warningset allowcustomreasons + +**Description** + +Enable or disable custom reasons for a warning. + +**Arguments** + +* ````: |bool-input| + +.. _warnings-command-warningset-senddm: + +""""""""""""""""" +warningset senddm +""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]warningset senddm + +**Description** + +Set whether warnings should be sent to users in DMs. + +**Arguments** + +* ````: |bool-input| + +.. _warnings-command-warningset-showmoderator: + +"""""""""""""""""""""""" +warningset showmoderator +"""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]warningset showmoderator + +**Description** + +Decide whether the name of the moderator warning a user should be included in the DM to that user. + +**Arguments** + +* ````: |bool-input| + +.. _warnings-command-warningset-usewarnchannel: + +""""""""""""""""""""""""" +warningset usewarnchannel +""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]warningset usewarnchannel + +**Description** + +Set if warnings should be sent to a channel set with ``[p]warningset warnchannel``. + +**Arguments** + +* ````: |bool-input| + +.. _warnings-command-warningset-warnchannel: + +"""""""""""""""""""""" +warningset warnchannel +"""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]warningset warnchannel [channel] + +**Description** + +Set the channel where warnings should be sent to. + +**Arguments** + +* ``[channel]``: |channel-input| Leave empty to use the channel ``[p]warn`` command was called in. + +.. _warnings-command-warnreason: + +^^^^^^^^^^ +warnreason +^^^^^^^^^^ + +.. note:: |guildowner-lock| + +**Syntax** + +.. code-block:: none + + [p]warnreason + +**Description** + +Manage warning reasons. + +Reasons must be given a name, description and points value. The +name of the reason must be given when a user is warned. + +.. _warnings-command-warnreason-create: + +""""""""""""""""" +warnreason create +""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]warnreason create + +.. tip:: Alias: ``warnreason add`` + +**Description** + +Create a warning reason. + +**Arguments** + +* ````: The name for the new reason. +* ````: The number of points with the new reason. +* ````: The description of the new warn reason. + +.. _warnings-command-warnreason-delete: + +""""""""""""""""" +warnreason delete +""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]warnreason delete + +**Description** + +Delete a warning reason. + +**Arguments** + +* ````: The name of the reason to delete. diff --git a/docs/index.rst b/docs/index.rst index 9b5358197..564404bf6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -52,6 +52,7 @@ Welcome to Red - Discord Bot's documentation! cog_guides/reports cog_guides/streams cog_guides/trivia + cog_guides/warnings red_core_data_statement .. toctree:: diff --git a/redbot/cogs/warnings/warnings.py b/redbot/cogs/warnings/warnings.py index c196e27fb..c990d4af7 100644 --- a/redbot/cogs/warnings/warnings.py +++ b/redbot/cogs/warnings/warnings.py @@ -156,7 +156,6 @@ class Warnings(commands.Cog): @commands.guild_only() async def warnchannel(self, ctx: commands.Context, channel: discord.TextChannel = None): """Set the channel where warnings should be sent to. - Leave empty to use the channel `[p]warn` command was called in. """ guild = ctx.guild @@ -192,11 +191,9 @@ class Warnings(commands.Cog): @checks.guildowner_or_permissions(administrator=True) async def warnaction(self, ctx: commands.Context): """Manage automated actions for Warnings. - Actions are essentially command macros. Any command can be run when the action is initially triggered, and/or when the action is lifted. - Actions must be given a name and a points threshold. When a user is warned enough so that their points go over this threshold, the action will be executed. @@ -207,7 +204,6 @@ class Warnings(commands.Cog): @commands.guild_only() async def action_add(self, ctx: commands.Context, name: str, points: int): """Create an automated action. - Duplicate action names are not allowed. """ guild = ctx.guild @@ -259,7 +255,6 @@ class Warnings(commands.Cog): @checks.guildowner_or_permissions(administrator=True) async def warnreason(self, ctx: commands.Context): """Manage warning reasons. - Reasons must be given a name, description and points value. The name of the reason must be given when a user is warned. """ @@ -368,26 +363,25 @@ class Warnings(commands.Cog): async def warn( self, ctx: commands.Context, - user: discord.Member, + member: discord.Member, points: UserInputOptional[int] = 1, *, reason: str, ): """Warn the user for the specified reason. - `` number of points the warning should be for. If no number is supplied 1 point will be given. Pre-set warnings disregard this. - `` can be a registered reason if it exists or a custom one - is created by default. + `` is reason for the warning. This can be a registered reason, + or a custom reason if ``[p]warningset allowcustomreasons`` is set. """ guild = ctx.guild - if user == ctx.author: + if member == ctx.author: return await ctx.send(_("You cannot warn yourself.")) - if user.bot: + if member.bot: return await ctx.send(_("You cannot warn other bots.")) - if user == ctx.guild.owner: + if member == ctx.guild.owner: return await ctx.send(_("You cannot warn the server owner.")) - if user.top_role >= ctx.author.top_role and ctx.author != ctx.guild.owner: + if member.top_role >= ctx.author.top_role and ctx.author != ctx.guild.owner: return await ctx.send( _( "The person you're trying to warn is equal or higher than you in the discord hierarchy, you cannot warn them." @@ -421,7 +415,7 @@ class Warnings(commands.Cog): return await ctx.send(msg) if reason_type is None: return - member_settings = self.config.member(user) + member_settings = self.config.member(member) current_point_count = await member_settings.total_points() warning_to_add = { str(ctx.message.id): { @@ -443,7 +437,7 @@ class Warnings(commands.Cog): ) em.add_field(name=_("Points"), value=str(reason_type["points"])) try: - await user.send( + await member.send( _("You have received a warning in {guild_name}.").format( guild_name=ctx.guild.name ), @@ -457,13 +451,13 @@ class Warnings(commands.Cog): _( "A warning for {user} has been issued," " but I wasn't able to send them a warn message." - ).format(user=user.mention) + ).format(user=member.mention) ) async with member_settings.warnings() as user_warnings: user_warnings.update(warning_to_add) current_point_count += reason_type["points"] await member_settings.total_points.set(current_point_count) - await warning_points_add_check(self.config, ctx, user, current_point_count) + await warning_points_add_check(self.config, ctx, member, current_point_count) toggle_channel = guild_settings["toggle_channel"] if toggle_channel: @@ -480,7 +474,7 @@ class Warnings(commands.Cog): if warn_channel.permissions_for(guild.me).send_messages: with contextlib.suppress(discord.HTTPException): await warn_channel.send( - _("{user} has been warned.").format(user=user.mention), + _("{user} has been warned.").format(user=member.mention), embed=em, ) @@ -489,7 +483,7 @@ class Warnings(commands.Cog): await ctx.tick() else: await ctx.send( - _("{user} has been warned.").format(user=user.mention), embed=em + _("{user} has been warned.").format(user=member.mention), embed=em ) else: if not dm_failed: @@ -501,7 +495,7 @@ class Warnings(commands.Cog): description=reason_type["description"], points=reason_type["points"] ), prefix=ctx.clean_prefix, - user=user.id, + user=member.id, message=ctx.message.id, ) await modlog.create_case( @@ -509,7 +503,7 @@ class Warnings(commands.Cog): ctx.guild, ctx.message.created_at.replace(tzinfo=timezone.utc), "warning", - user, + member, ctx.message.author, reason_msg, until=None, @@ -519,18 +513,18 @@ class Warnings(commands.Cog): @commands.command() @commands.guild_only() @checks.admin() - async def warnings(self, ctx: commands.Context, user: Union[discord.Member, int]): + async def warnings(self, ctx: commands.Context, member: Union[discord.Member, int]): """List the warnings for the specified user.""" try: - userid: int = user.id + userid: int = member.id except AttributeError: - userid: int = user - user = ctx.guild.get_member(userid) - user = user or namedtuple("Member", "id guild")(userid, ctx.guild) + userid: int = member + member = ctx.guild.get_member(userid) + member = member or namedtuple("Member", "id guild")(userid, ctx.guild) msg = "" - member_settings = self.config.member(user) + member_settings = self.config.member(member) async with member_settings.warnings() as user_warnings: if not user_warnings.keys(): # no warnings for the user await ctx.send(_("That user has no warnings!")) @@ -554,7 +548,7 @@ class Warnings(commands.Cog): await ctx.send_interactive( pagify(msg, shorten_by=58), box_lang=_("Warnings for {user}").format( - user=user if isinstance(user, discord.Member) else user.id + user=member if isinstance(member, discord.Member) else member.id ), ) @@ -598,7 +592,7 @@ class Warnings(commands.Cog): async def unwarn( self, ctx: commands.Context, - user: Union[discord.Member, int], + member: Union[discord.Member, int], warn_id: str, *, reason: str = None, @@ -608,10 +602,10 @@ class Warnings(commands.Cog): guild = ctx.guild try: - user_id = user.id - member = user + user_id = member.id + member = member except AttributeError: - user_id = user + user_id = member member = guild.get_member(user_id) member = member or namedtuple("Member", "guild id")(guild, user_id)