Skip to content

Commit 6cbfd88

Browse files
eunwoo1104eunwoo1104
authored
Merge pull request #114 from goverfl0w/new-docs
Friendly Documentation, for the better.
2 parents 1f6ce42 + 42322a4 commit 6cbfd88

File tree

3 files changed

+236
-94
lines changed

3 files changed

+236
-94
lines changed

‎docs/gettingstarted.rst‎

Lines changed: 217 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,242 @@
11
Getting Started
22
===============
33

4-
Now that things have been explained through the `quickstart`_ page for you
5-
to begin making slash commands for your bot, now it is time to discuss some
6-
of the much more rather advanced or complicated aspects of slash commands.
7-
Our first discussion will be covering over the implementation of options in
8-
your commands.
4+
Where do we start?
5+
******************
6+
7+
Before we begin getting started on everything else, it is recommended to
8+
check out the `quickstart`_ page first to get a basic grip on making
9+
slash commands for your bot.
10+
11+
Making a slash command.
12+
***********************
13+
14+
The basics.
15+
-----------
916

1017
First, let's explain by how commands are parsed through the Discord Bot API.
18+
1119
As you may know, Discord relies a lot on the interaction of HTTP Requests and
1220
JSON tables. As is with the case here, commands are the exact same way with
1321
having JSON tables to structure the design of it for Discord to understand. We
14-
can apply this information likewise with how options are to be designed in the
15-
Python code. Below attached is from the *Discord Developer Portal* on Slash
16-
Commands for showing how options are designed.
17-
18-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
19-
| **Field** | **Type** | **Description** |
20-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
21-
| type | int | value of ApplicationCommandOptionType |
22-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
23-
| name | string | 1-32 character name matching ``^[\w-]{1,32}$`` |
24-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
25-
| description | string | 1-100 character description |
26-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
27-
| default? | bool | the first required option for the user to complete--only one option can be default |
28-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
29-
| required? | bool | if the parameter is required or optional--default ``false`` |
30-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
31-
| choices? | array of `ApplicationCommandOptionChoice`_ | choices for ``string`` and ``int`` types for the user to pick from |
32-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
33-
| options? | array of `ApplicationCommandOption`_ | if the option is a subcommand or subcommand group type, this nested options will be the parameters |
34-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
35-
36-
This table shows us the way that Discord handles the structure of options for
22+
can apply this information likewise with how slash commands are to be designed
23+
in the Python code. Below attached is from the *Discord Developer Portal* on Slash
24+
Commands for showing how they are designed.
25+
26+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
27+
| **Field** | **Type** | **Description** |
28+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
29+
| name | string | 1-32 character name matching ``^[\w-]{1,32}$``. |
30+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
31+
| description | string | 1-100 character description. |
32+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
33+
| options? | array of `ApplicationCommandOption`_ | if the option is a subcommand or subcommand group type, this nested options will be the parameters. |
34+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
35+
36+
This table shows us the way that Discord handles the structure of commands for
3737
slash commands through their Bot API. For visualization purposes, we'll quickly
3838
make a JSON example (although we won't be using it) in order to explain how this
3939
works:
4040

4141
.. code-block:: python
4242
4343
{
44-
"name": "argone",
45-
"description": "description of first argument",
46-
"type": 3, # STRING type,
47-
"required": True
44+
"name": "test",
45+
"description": "This is just a test command, nothing more.",
4846
}
4947
50-
With this very basic understanding in mind, now we are able to begin programming
51-
a simple Python script that will allow us to utilize this ability through one of
52-
the many subclasses offered in *discord-py-slash-command*.
48+
Now that we have a basic understanding of how the JSON table works, we can
49+
take this knowledge and convert it into a decorator method for the Python
50+
code as shown below:
51+
52+
.. code-block:: python
53+
54+
@slash.slash(name="test",
55+
description="This is just a test command, nothing more.")
56+
async def test(ctx):
57+
await ctx.respond()
58+
await ctx.send(content="Hello World!")
59+
60+
Now that we've gone over how Discord handles the declaration of slash commands
61+
through their Bot API, let's go over what some of the other things mean within
62+
the *logical* part of our code, the command function:
63+
64+
- ``ctx.respond()``: This is a way for us to handle responses. In short, the API
65+
requires some way to "acknowledge" an interaction response that we want to send off.
66+
67+
(An alias of this would be ``ctx.ack()``)
68+
69+
Giving some options for variety.
70+
--------------------------------
71+
72+
The next thing that we will begin to talk about is the implementation of options,
73+
otherwise well-known as "arguments" in discord.py commands.
74+
75+
The JSON structure of options are designed up to be similar to the same premise
76+
of how a slash command is declared. Below is the given table of how an option
77+
JSON would appear as:
78+
79+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
80+
| **Field** | **Type** | **Description** |
81+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
82+
| type | int | value of `ApplicationCommandOptionType`_. |
83+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
84+
| name | string | 1-32 character name matching ``^[\w-]{1,32}$``. |
85+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
86+
| description | string | 1-100 character description. |
87+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
88+
| default? | bool | the first required option for the user to complete--only one option can be default. |
89+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
90+
| required? | bool | if the parameter is required or optional--default ``false``. |
91+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
92+
| choices? | array of `ApplicationCommandOptionChoice`_ | choices for ``string`` and ``int`` types for the user to pick from. |
93+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
94+
| options? | array of `ApplicationCommandOption`_ | if the option is a subcommand or subcommand group type, this nested options will be the parameters. |
95+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
96+
97+
Now we have an idea of how options are declared. With this in mind, let's quickly make a JSON
98+
example in order to visualize this concept even further:
99+
100+
.. code-block:: python
101+
102+
{
103+
"name": "test",
104+
"description": "This is just a test command, nothing more.",
105+
"options": [
106+
{
107+
"name": "optone",
108+
"description": "This is the first option we have.",
109+
"type": 3,
110+
"required": "false"
111+
}
112+
]
113+
}
114+
115+
While the table in the basics mentions an array in particular called ``ApplicationCommandOptionType``,
116+
there isn't that much of an explanation on how this works. Let's put this into better laymen
117+
terms on what this means with a table below showing all of these values:
118+
119+
+-------------------+-----------+
120+
| **Name** | **Value** |
121+
+-------------------+-----------+
122+
| SUB_COMMAND | 1 |
123+
+-------------------+-----------+
124+
| SUB_COMMAND_GROUP | 2 |
125+
+-------------------+-----------+
126+
| STRING | 3 |
127+
+-------------------+-----------+
128+
| INTEGER | 4 |
129+
+-------------------+-----------+
130+
| BOOLEAN | 5 |
131+
+-------------------+-----------+
132+
| USER | 6 |
133+
+-------------------+-----------+
134+
| CHANNEL | 7 |
135+
+-------------------+-----------+
136+
| ROLE | 8 |
137+
+-------------------+-----------+
138+
139+
The purpose of having the ``ApplicationCommandOptionType`` value passed into our option JSON structure
140+
is so that we can help the Discord UI understand what kind of value we're inputting here. For instance,
141+
if we're wanting to put in a string response, we'll pass the ID 3 so that the UI of Discord chat bar
142+
knows to format it visually this way. If we're looking for a user, then we'll pass ID 6 so that it presents
143+
us with a list of users in our server instead, making it easier on our lives.
144+
145+
This is not to be confused, however, with formatting the response type itself. This is merely a method so
146+
that the API wrapper can help us with passing the correct type or instance variable with the arguments of the
147+
command function's code.
148+
149+
Now, we can finally visualize this by coding an example of this being used in the Python code shown below.
150+
151+
.. code-block:: python
152+
153+
from discord_slash.manage_commands import create_option
154+
155+
@slash.slash(name="test",
156+
description="This is just a test command, nothing more.",
157+
options=[
158+
create_option(
159+
name="optone",
160+
description="This is the first option we have.",
161+
option_type=3,
162+
required=False
163+
)
164+
])
165+
async def test(ctx, optone: str):
166+
await ctx.respond()
167+
await ctx.send(content=f"I got you, you said {optone}!")
168+
169+
Additionally, we could also declare the type of our command's option through this method shown here:
170+
171+
.. code-block:: python
172+
173+
from discord_slash.model import SubCommandOptionType
174+
175+
(...)
176+
177+
option_type=SubCommandOptionType.STRING
178+
179+
More in the option? Give them a choice.
180+
---------------------------------------
181+
182+
Alas, there is also a way to give even more information to options with Discord's Slash Commands:
183+
a choice. Not like something that you're given at birth of when you become of legal age as an adult,
184+
we're not here to give you *that* kind of life advice, but the choice of what value you want your
185+
option to rather pass. Below is a table that shows the JSON structure of how choices are represented
186+
for an option:
187+
188+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
189+
| **Field** | **Type** | **Description** |
190+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
191+
| name | string | 1-32 character choice name. |
192+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
193+
| value | string or int | value of the choice, up to 100 characters if string. |
194+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
195+
196+
This time, only 2 fields are able to be passed for this. Below is a JSON example of how this would
197+
be designed:
198+
199+
.. code-block:: python
200+
201+
{
202+
"name": "ChoiceOne",
203+
"value": "Hello command, this is my value!"
204+
}
205+
206+
To make it really simple, the ``name`` field is only to be used for how you want the choice to be presented
207+
through Discord's UI. It's the "appearance" of how you want your choice shown, not the actual returned value
208+
of it. Hence, this is why ``value`` is the second field passed for that, which can be either in the form of
209+
a string or integer. Below is an implementation of this design in the Python code:
53210

54211
.. code-block:: python
55212
56-
import discord
57-
from discord_slash import SlashCommand
58-
from discord_slash.utils import manage_commands # Allows us to manage the command settings.
59-
60-
client = discord.Client(intents=discord.Intents.all())
61-
slash = SlashCommand(client, sync_commands=True)
62-
63-
guild_ids = [789032594456576001]
64-
65-
@client.event
66-
async def on_ready():
67-
print("Ready!")
68-
69-
@slash.slash(
70-
name="test",
71-
description="this returns the bot latency",
72-
options=[manage_commands.create_option(
73-
name = "argone",
74-
description = "description of first argument",
75-
option_type = 3,
76-
required = True
77-
)],
78-
guild_ids=guild_ids
79-
)
80-
async def _test(ctx, argone: str):
81-
await ctx.respond()
82-
await ctx.send(f"You responded with {argone}.")
83-
84-
client.run("your_bot_token_here")
213+
from discord_slash.manage_commands import create_option, create_choice
85214
86-
The main changes that you need to know about are with the lines calling the import
87-
of ``manage_commands``, as well as the ``options = [] ...`` code within the ``@slash.slash()``
88-
context coroutine. This will now create a new option called "argone" when shown for
89-
the slash command.
215+
@slash.slash(name="test",
216+
description="This is just a test command, nothing more.",
217+
options=[
218+
create_option(
219+
name="optone",
220+
description="This is the first option we have.",
221+
option_type=3,
222+
required=False,
223+
choices=[
224+
create_choice(
225+
name="ChoiceOne",
226+
value="DOGE!"
227+
),
228+
create_choice(
229+
name="ChoiceTwo",
230+
value="NO DOGE"
231+
)
232+
]
233+
)
234+
])
235+
async def test(ctx, optone: str):
236+
await ctx.respond()
237+
await ctx.send(content=f"Wow, you actually chose {optone}? :(")
90238
91239
.. _quickstart: https://discord-py-slash-command.readthedocs.io/en/latest/quickstart.html
240+
.. _ApplicationCommandOptionType: https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoptiontype
92241
.. _ApplicationCommandOptionChoice: https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoptionchoice
93242
.. _ApplicationCommandOption: https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoption

‎docs/index.rst‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,13 @@
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
6-
Welcome to discord-py-slash-command's official documentation!
7-
=============================================================
6+
Welcome
7+
=======
88

9-
discord-py-slash-command is a simple discord.py library extension
10-
for using Discord's new Slash Command feature.
9+
Hello there! Welcome to the official documentation of our library
10+
extension made for discord.py: being able to use Discord Slash Commands.
1111

12-
Before going into the advanced sections that guide you through
13-
added more complex stuff documentation-wise, it is highly recommended
12+
Before we start going into the advanced stuff, it is highly recommended
1413
to check out the `quickstart`_ page first from here or below in the contents.
1514

1615
If there are any questions that you have about the documentation

0 commit comments

Comments
 (0)