diff --git a/docs/cog_customcom.rst b/docs/cog_customcom.rst index 83cd3eda6..3b6d7c0f4 100644 --- a/docs/cog_customcom.rst +++ b/docs/cog_customcom.rst @@ -1,4 +1,5 @@ .. CustomCommands Cog Reference +.. _cog_customcom: ============================ CustomCommands Cog Reference diff --git a/docs/cog_guides/customcommands.rst b/docs/cog_guides/customcommands.rst new file mode 100644 index 000000000..2172ca7f1 --- /dev/null +++ b/docs/cog_guides/customcommands.rst @@ -0,0 +1,294 @@ +.. _customcommands: + +============== +CustomCommands +============== + +This is the cog guide for the customcommands 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 customcom + +.. _customcommands-usage: + +----- +Usage +----- + +This cog contains commands for creating and managing custom commands that display text. + +These are useful for storing information members might need, like FAQ answers or invite links. +Custom commands can be used by anyone by default, so be careful with pings. +Commands can only be lowercase, and will not respond to any uppercase letters. + + +.. _customcommands-commands: + +-------- +Commands +-------- + +.. _customcommands-command-customcom: + +^^^^^^^^^ +customcom +^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]customcom + +.. tip:: Alias: ``cc`` + +**Description** + +Base command for Custom Commands management. + +.. _customcommands-command-customcom-cooldown: + +"""""""""""""""""" +customcom cooldown +"""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]customcom cooldown [cooldown] [per=member] + +**Description** + +Set, edit, or view the cooldown for a custom command. + +You may set cooldowns per member, channel, or guild. Multiple +cooldowns may be set. All cooldowns must be cooled to call the +custom command. + +Examples: + - ``[p]customcom cooldown pingrole`` + - ``[p]customcom cooldown yourcommand 30`` + - ``[p]cc cooldown mycommand 30 guild`` + +**Arguments:** + +- ```` The custom command to check or set the cooldown. +- ```` The number of seconds to wait before allowing the command to be invoked again. If omitted, will instead return the current cooldown settings. +- ```` The group to apply the cooldown on. Defaults to per member. Valid choices are server, guild, user, and member. + +.. _customcommands-command-customcom-create: + +"""""""""""""""" +customcom create +"""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]customcom create + +.. tip:: Alias: ``customcom add`` + +**Description** + +Create custom commands. + +If a type is not specified, a simple CC will be created. +CCs can be enhanced with arguments, see the guide +here: https://docs.discord.red/en/stable/cog_customcom.html. + +.. _customcommands-command-customcom-create-random: + +""""""""""""""""""""""" +customcom create random +""""""""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]customcom create random + +**Description** + +Create a CC where it will randomly choose a response! + +Note: This command is interactive. + +**Arguments:** + +- ```` The command executed to return the text. Cast to lowercase. + +.. _customcommands-command-customcom-create-simple: + +""""""""""""""""""""""" +customcom create simple +""""""""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]customcom create simple + +**Description** + +Add a simple custom command. + +Example: + - ``[p]customcom create simple yourcommand Text you want`` + +**Arguments:** + +- ```` The command executed to return the text. Cast to lowercase. +- ```` The text to return when executing the command. See guide for enhanced usage. + +.. _customcommands-command-customcom-delete: + +"""""""""""""""" +customcom delete +"""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]customcom delete + +.. tip:: Aliases: ``customcom del``, ``customcom remove`` + +**Description** + +Delete a custom command. + +Example: + - ``[p]customcom delete yourcommand`` + +**Arguments:** + +- ```` The custom command to delete. + +.. _customcommands-command-customcom-edit: + +"""""""""""""" +customcom edit +"""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]customcom edit [text] + +**Description** + +Edit a custom command. + +Example: + - ``[p]customcom edit yourcommand Text you want`` + +**Arguments:** + +- ```` The custom command to edit. +- ```` The new text to return when executing the command. + +.. _customcommands-command-customcom-list: + +"""""""""""""" +customcom list +"""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]customcom list + +**Description** + +List all available custom commands. + +The list displays a preview of each command's response, with +markdown escaped and newlines replaced with spaces. + +.. _customcommands-command-customcom-raw: + +""""""""""""" +customcom raw +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]customcom raw + +**Description** + +Get the raw response of a custom command, to get the proper markdown. + +This is helpful for copy and pasting. + +**Arguments:** + +- ```` The custom command to get the raw response of. + +.. _customcommands-command-customcom-search: + +"""""""""""""""" +customcom search +"""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]customcom search + +**Description** + +Searches through custom commands, according to the query. + +Uses fuzzywuzzy searching to find close matches. + +**Arguments:** + +- ```` The query to search for. Can be multiple words. + +.. _customcommands-command-customcom-show: + +"""""""""""""" +customcom show +"""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]customcom show + +**Description** + +Shows a custom command's responses and its settings. + +**Arguments:** + +- ```` The custom command to show. diff --git a/docs/index.rst b/docs/index.rst index b222021db..aac54cecb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,6 +36,7 @@ Welcome to Red - Discord Bot's documentation! cog_guides/alias cog_guides/bank cog_guides/cleanup + cog_guides/customcommands red_core_data_statement .. toctree:: diff --git a/redbot/cogs/customcom/customcom.py b/redbot/cogs/customcom/customcom.py index 1407bda31..d1758187c 100644 --- a/redbot/cogs/customcom/customcom.py +++ b/redbot/cogs/customcom/customcom.py @@ -214,7 +214,12 @@ class CommandObj: @cog_i18n(_) class CustomCommands(commands.Cog): - """Creates commands used to display text.""" + """This cog contains commands for creating and managing custom commands that display text. + + These are useful for storing information members might need, like FAQ answers or invite links. + Custom commands can be used by anyone by default, so be careful with pings. + Commands can only be lowercase, and will not respond to any uppercase letters. + """ def __init__(self, bot): super().__init__() @@ -239,14 +244,18 @@ class CustomCommands(commands.Cog): @commands.group(aliases=["cc"]) @commands.guild_only() async def customcom(self, ctx: commands.Context): - """Custom commands management.""" + """Base command for Custom Commands management.""" pass @customcom.command(name="raw") async def cc_raw(self, ctx: commands.Context, command: str.lower): """Get the raw response of a custom command, to get the proper markdown. - This is helpful for copy and pasting.""" + This is helpful for copy and pasting. + + **Arguments:** + + - `` The custom command to get the raw response of.""" commands = await self.config.guild(ctx.guild).commands() if command not in commands: return await ctx.send("That command doesn't exist.") @@ -286,7 +295,15 @@ class CustomCommands(commands.Cog): @customcom.command(name="search") @commands.guild_only() async def cc_search(self, ctx: commands.Context, *, query): - """Searches through custom commands, according to the query.""" + """ + Searches through custom commands, according to the query. + + Uses fuzzywuzzy searching to find close matches. + + **Arguments:** + + - `` The query to search for. Can be multiple words. + """ cc_commands = await CommandObj.get_commands(self.config.guild(ctx.guild)) extracted = process.extract(query, list(cc_commands.keys())) accepted = [] @@ -327,6 +344,10 @@ class CustomCommands(commands.Cog): """Create a CC where it will randomly choose a response! Note: This command is interactive. + + **Arguments:** + + - `` The command executed to return the text. Cast to lowercase. """ if any(char.isspace() for char in command): # Haha, nice try @@ -355,7 +376,12 @@ class CustomCommands(commands.Cog): """Add a simple custom command. Example: - - `[p]customcom create simple yourcommand Text you want` + - `[p]customcom create simple yourcommand Text you want` + + **Arguments:** + + - `` The command executed to return the text. Cast to lowercase. + - `` The text to return when executing the command. See guide for enhanced usage. """ if any(char.isspace() for char in command): # Haha, nice try @@ -387,8 +413,16 @@ class CustomCommands(commands.Cog): cooldowns may be set. All cooldowns must be cooled to call the custom command. - Example: - - `[p]customcom cooldown yourcommand 30` + Examples: + - `[p]customcom cooldown pingrole` + - `[p]customcom cooldown yourcommand 30` + - `[p]cc cooldown mycommand 30 guild` + + **Arguments:** + + - `` The custom command to check or set the cooldown. + - `` The number of seconds to wait before allowing the command to be invoked again. If omitted, will instead return the current cooldown settings. + - `` The group to apply the cooldown on. Defaults to per member. Valid choices are server, guild, user, and member. """ if cooldown is None: try: @@ -425,7 +459,11 @@ class CustomCommands(commands.Cog): """Delete a custom command. Example: - - `[p]customcom delete yourcommand` + - `[p]customcom delete yourcommand` + + **Arguments:** + + - `` The custom command to delete. """ try: await self.commandobj.delete(ctx=ctx, command=command) @@ -439,7 +477,12 @@ class CustomCommands(commands.Cog): """Edit a custom command. Example: - - `[p]customcom edit yourcommand Text you want` + - `[p]customcom edit yourcommand Text you want` + + **Arguments:** + + - `` The custom command to edit. + - `` The new text to return when executing the command. """ try: await self.commandobj.edit(ctx=ctx, command=command, response=text) @@ -497,7 +540,12 @@ class CustomCommands(commands.Cog): @customcom.command(name="show") async def cc_show(self, ctx, command_name: str): - """Shows a custom command's responses and its settings.""" + """Shows a custom command's responses and its settings. + + **Arguments:** + + - `` The custom command to show. + """ try: cmd = await self.commandobj.get_full(ctx.message, command_name)