From f309cd3d3772aeddb77242a0e1a89cfcc985af01 Mon Sep 17 00:00:00 2001 From: JustaSqu1d <89910983+JustaSqu1d@users.noreply.github.com> Date: Wed, 5 Jun 2024 06:49:48 -0700 Subject: [PATCH] docs: add more information about application commands (#467) * docs: add option decorator * docs: slash command groups in cogs * docs: minor grammar fix * fix: spelling mistake --- docs/extensions/tasks/tasks.mdx | 2 +- .../application-commands/slash-commands.mdx | 45 +++++++++++++++---- docs/popular-topics/cogs.mdx | 23 ++++++++-- 3 files changed, 58 insertions(+), 12 deletions(-) diff --git a/docs/extensions/tasks/tasks.mdx b/docs/extensions/tasks/tasks.mdx index c98aa485..fea4db3e 100644 --- a/docs/extensions/tasks/tasks.mdx +++ b/docs/extensions/tasks/tasks.mdx @@ -35,7 +35,7 @@ doing very useful stuff. doing very useful stuff. ``` -For a more useful example here's a task in a cog context ripped straight from the [docs](https://docs.pycord.dev/en/stable/ext/tasks/index.html#recepies): +For a more useful example here's a task in a cog context ripped straight from the [docs](https://docs.pycord.dev/en/stable/ext/tasks/index.html#recipes): ```py from discord.ext import tasks, commands diff --git a/docs/interactions/application-commands/slash-commands.mdx b/docs/interactions/application-commands/slash-commands.mdx index 00438192..1aff47b1 100644 --- a/docs/interactions/application-commands/slash-commands.mdx +++ b/docs/interactions/application-commands/slash-commands.mdx @@ -119,6 +119,14 @@ Here's what the registered subcommands will look like in the Slash Command Menu: You'll notice that there's the name of the Slash Command Group and then the name of the subcommand separated by a space. +::: + +:::info Cogs + +If you are looking to add Slash Command Groups to cogs, please look at our [Cogs page](../../popular-topics/cogs)! + +::: + ## Sub-groups We've made a subcommand group, but did you know that you could create a group inside another? @@ -143,12 +151,14 @@ The command created above can be invoked by typing `/math advanced square_root`. Whenever you're using Slash Commands, you might notice that you can specify parameters that the user has to set or can optionally set. These are called Options. -Since you want different inputs from Options, you'll have to specify the type for that Option. There are a few ways of doing this. +Options can also include a description to provide more information. [You can learn more about Options in our documentation!](https://docs.pycord.dev/en/stable/api/application_commands.html#discord.Option) + +Since you want different inputs from Options, you'll have to specify the type for that Option; there are a few ways of doing this. -You could use Type Annotations and let Pycord figure out the option type, like shown below. +You could use Type Annotations and let Pycord figure out the option type or explicitly specified using the [`SlashCommandOptionType`](https://docs.pycord.dev/en/stable/api/enums.html#discord.SlashCommandOptionType) enum. ```python import discord @@ -162,6 +172,16 @@ async def add(ctx, first: discord.Option(int), second: discord.Option(int)): sum = first + second await ctx.respond(f"The sum of {first} and {second} is {sum}.") +@bot.command() +# this explicitly tells pycord what types the options are instead +async def join( + ctx, + first: discord.Option(discord.SlashCommandOptionType.string), + second: discord.Option(discord.SlashCommandOptionType.string) +): + joined = first + second + await ctx.respond(f"When you join \"{first}\" and \"{second}\", you get: \"{joined}\".") + bot.run("TOKEN") ``` @@ -174,12 +194,20 @@ bot.run("TOKEN") The sum of 1 and 1 is 2. + +
+ + join + +
+ When you join "Py" and "cord", you get: "Pycord". + - + -You could also explicitly declare the type using the [`SlashCommandOptionType`](https://docs.pycord.dev/en/stable/api/enums.html#discord.SlashCommandOptionType) enum. +Instead of Type Annotations, you can also use the option decorator. This is usually done to have type-hinting. ```python title="Slash Command Type" import discord @@ -187,11 +215,12 @@ import discord bot = discord.Bot() @bot.command() -# this explicitly tells pycord what types the options are instead of it figuring it out by itself +@discord.option("first", type=discord.SlashCommandOptionType.string) # type = str also works +@discord.option("second", type=discord.SlashCommandOptionType.string) # type = str also works async def join( ctx, - first: discord.Option(discord.SlashCommandOptionType.string), - second: discord.Option(discord.SlashCommandOptionType.string) + first: str, + second: str, ): joined = first + second await ctx.respond(f"When you join \"{first}\" and \"{second}\", you get: \"{joined}\".") @@ -206,7 +235,7 @@ bot.run("TOKEN") join - When you join "Hello" and "World!", you get: "Hello World!" + When you join "Py" and "cord", you get: "Pycord". diff --git a/docs/popular-topics/cogs.mdx b/docs/popular-topics/cogs.mdx index 62e38dc9..28b34933 100644 --- a/docs/popular-topics/cogs.mdx +++ b/docs/popular-topics/cogs.mdx @@ -8,9 +8,9 @@ to avoid making your bot's files messy and cluttered. ## Getting Started -First, you'll need to create a folder to store your cogs, eg. `cogs/`. +First, you'll need to create a folder to store your cogs, e.g. `cogs/`. -Then, create a file inside the folder, eg. `cogs/greetings.py`. By convention, the file name should +Then, create a file inside the folder, e.g. `cogs/greetings.py`. By convention, the file name should be the same as the name of the cog or module. We can then create the cog. @@ -37,6 +37,23 @@ class Greetings(commands.Cog): # create a class for our cog that inherits from c async def greet(self, ctx, member: discord.Member): await ctx.respond(f'{ctx.author.mention} says hello to {member.mention}!') + math = discord.SlashCommandGroup("math", "Spooky math stuff") # create a Slash Command Group called "math" + advanced_math = math.create_subgroup( + "advanced", + "super hard math commands!" + ) + + @math.command() + async def add(self, a: int, b: int): + c = a + b + await ctx.respond(f"{a} + {b} is {c}.") + + @advanced_math.command() + async def midpoint(self, x1: float, y1: float, x2: float, y2: float): + mid_x = (x1 + x2)/2 + mid_y = (y1 + y2)/2 + await ctx.respond(f"The midpoint between those coordinates is ({mid_x}, {mid_y}).") + @commands.Cog.listener() # we can add event listeners to our cog async def on_member_join(self, member): # this is called when a member joins the server # you must enable the proper intents @@ -56,7 +73,7 @@ bot.load_extension('cogs.greetings') ``` This loads the file `cogs/greetings.py` and adds it to the bot. -The argument of `load_extension` should be your cog's path (eg. cogs/greetings.py) without the file +The argument of `load_extension` should be your cog's path (e.g. cogs/greetings.py) without the file extension and with the `/` replaced with `.` If you have multiple cogs, you can add them all at once by adding the following code: