Skip to content

Commit 71f730d

Browse files
Paillat-devPaillat-dev
committed
📖 Add guide for defining help pages in Botkit
1 parent 5ecd5ee commit 71f730d

File tree

2 files changed

+275
-12
lines changed

2 files changed

+275
-12
lines changed

‎guides/defining-help-pages.md

+239
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# Defining Help Pages in Botkit
2+
3+
This guide will walk you through the process of defining help pages for your Botkit
4+
extensions. Help pages provide users with information about your bot's commands,
5+
features, and usage examples.
6+
7+
## Prerequisites
8+
9+
Before you begin, ensure you have:
10+
11+
1. A basic understanding of YAML syntax
12+
2. Familiarity with the Botkit extension system
13+
3. An existing Botkit extension that you want to document
14+
15+
## Understanding the Help System
16+
17+
The Botkit help system organizes documentation into categories and pages. Each category
18+
contains multiple pages, and each page documents a specific command or feature.
19+
20+
### Key Components
21+
22+
The help system consists of several key components:
23+
24+
1. **Categories**: Groups of related help pages (e.g., "Moderation", "Fun", "Utility")
25+
2. **Pages**: Individual documentation pages for specific commands or features
26+
3. **Translations**: Multi-language support for help content
27+
28+
## Help Page Structure
29+
30+
Help pages are defined using YAML files. Each YAML file represents a category and
31+
contains definitions for all pages within that category.
32+
33+
### Class Structure
34+
35+
The help system uses the following classes to represent help content:
36+
37+
- `HelpTranslation`: The root class containing all categories
38+
- `HelpCategoryTranslation`: Represents a category of help pages
39+
- `HelpPageTranslation`: Represents an individual help page
40+
41+
## Creating Help Pages
42+
43+
### Step 1: Create a YAML File
44+
45+
Create a YAML file for your help category in the `src/extensions/help/pages/` directory.
46+
For example, if you're documenting moderation commands, you might create
47+
`moderation.yml`:
48+
49+
```bash
50+
touch src/extensions/help/pages/moderation.yml
51+
```
52+
53+
### Step 2: Define the Category
54+
55+
Open the YAML file and define the category structure:
56+
57+
```yaml
58+
name:
59+
en-US: Moderation
60+
es-ES: Moderación
61+
description:
62+
en-US: Commands for server moderation
63+
es-ES: Comandos para moderación del servidor
64+
order: 1 # Lower numbers appear first in the category list
65+
pages:
66+
# Pages will be defined here
67+
```
68+
69+
The `name` and `description` fields support multiple languages, and the `order` field
70+
determines the position of this category in the list.
71+
72+
### Step 3: Define Pages
73+
74+
Within the `pages` section, define each help page:
75+
76+
```yaml
77+
pages:
78+
ban:
79+
title:
80+
en-US: Ban Command
81+
es-ES: Comando de Prohibición
82+
description:
83+
en-US: Bans a user from the server
84+
es-ES: Prohíbe a un usuario del servidor
85+
category:
86+
en-US: Moderation
87+
es-ES: Moderación
88+
quick_tips:
89+
- en-US: You can specify a reason for the ban
90+
es-ES: Puedes especificar una razón para la prohibición
91+
- en-US: Banned users can be unbanned later
92+
es-ES: Los usuarios prohibidos pueden ser readmitidos más tarde
93+
examples:
94+
- en-US: "/ban @user Spamming"
95+
es-ES: "/ban @usuario Spam"
96+
- en-US: "/ban @user"
97+
es-ES: "/ban @usuario"
98+
related_commands:
99+
- ban
100+
```
101+
102+
Each page includes:
103+
104+
- `title`: The name of the command or feature
105+
- `description`: A brief description of what it does
106+
- `category`: The category this page belongs to (should match the category name)
107+
- `quick_tips` (optional): A list of helpful tips for using the command
108+
- `examples` (optional): Example usages of the command
109+
- `related_commands` (optional): List of commands that will be linked to this page using
110+
discord slash command mentions
111+
112+
<!-- prettier-ignore -->
113+
> [!NOTE]
114+
> All text fields support multiple languages using language codes as keys.
115+
116+
### Step 4: Make Your YAML File Available
117+
118+
The help system automatically loads all `.yml` files from the
119+
`src/extensions/help/pages` directory. Make sure your file is properly formatted and
120+
placed in this directory.
121+
122+
<!-- prettier-ignore -->
123+
> [!NOTE]
124+
> All help files should be placed in the `src/extensions/help/pages` directory, not inside individual extension directories.
125+
126+
## Example: Complete Help Category
127+
128+
Here's a complete example of a help category for moderation commands:
129+
130+
```yaml
131+
name:
132+
en-US: Moderation
133+
es-ES: Moderación
134+
description:
135+
en-US: Commands for server moderation
136+
es-ES: Comandos para moderación del servidor
137+
order: 1
138+
pages:
139+
ban:
140+
title:
141+
en-US: Ban Command
142+
es-ES: Comando de Prohibición
143+
description:
144+
en-US: Bans a user from the server
145+
es-ES: Prohíbe a un usuario del servidor
146+
category:
147+
en-US: Moderation
148+
es-ES: Moderación
149+
quick_tips:
150+
- en-US: You can specify a reason for the ban
151+
es-ES: Puedes especificar una razón para la prohibición
152+
- en-US: Banned users can be unbanned later
153+
es-ES: Los usuarios prohibidos pueden ser readmitidos más tarde
154+
examples:
155+
- en-US: "/ban @user Spamming"
156+
es-ES: "/ban @usuario Spam"
157+
- en-US: "/ban @user"
158+
es-ES: "/ban @usuario"
159+
related_commands:
160+
- kick
161+
- unban
162+
163+
kick:
164+
title:
165+
en-US: Kick Command
166+
es-ES: Comando de Expulsión
167+
description:
168+
en-US: Kicks a user from the server
169+
es-ES: Expulsa a un usuario del servidor
170+
category:
171+
en-US: Moderation
172+
es-ES: Moderación
173+
quick_tips:
174+
- en-US: Kicked users can rejoin with a new invite
175+
es-ES: Los usuarios expulsados pueden volver a unirse con una nueva invitación
176+
examples:
177+
- en-US: "/kick @user Disruptive behavior"
178+
es-ES: "/kick @usuario Comportamiento disruptivo"
179+
related_commands:
180+
- ban
181+
```
182+
183+
## How the Help System Works
184+
185+
When a user requests help using the `/help` command, the help system:
186+
187+
1. Loads all help categories and pages from YAML files
188+
2. Organizes them by category
189+
3. Displays a paginated view with categories in a dropdown menu
190+
4. Shows pages within the selected category
191+
192+
The system automatically handles pagination, localization, and UI elements like "Tips &
193+
Tricks" and "Usage Examples" sections.
194+
195+
## Advanced: Understanding How Help Pages Are Loaded
196+
197+
The help system automatically loads all help pages from the `src/extensions/help/pages`
198+
directory when the bot starts. This is handled by the following code in
199+
`src/extensions/help/pages/__init__.py`:
200+
201+
```python
202+
# iterate over .y[a]ml files in the same directory as this file
203+
categories: list[HelpCategoryTranslation] = []
204+
205+
for file in chain(Path(__file__).parent.glob("*.yaml"), Path(__file__).parent.glob("*.yml")):
206+
with open(file, encoding="utf-8") as f:
207+
data = yaml.safe_load(f)
208+
categories.append(HelpCategoryTranslation(**data))
209+
210+
categories.sort(key=lambda item: item.order)
211+
212+
help_translation = HelpTranslation(categories=categories)
213+
```
214+
215+
This code:
216+
217+
1. Finds all `.yml` and `.yaml` files in the `src/extensions/help/pages` directory
218+
2. Loads each file as a YAML document
219+
3. Creates a `HelpCategoryTranslation` object for each file
220+
4. Sorts the categories by their `order` value
221+
5. Creates a `HelpTranslation` object containing all categories
222+
223+
<!-- prettier-ignore -->
224+
> [!IMPORTANT]
225+
> Remember that all help pages must be placed in the `src/extensions/help/pages` directory, not within individual extension directories.
226+
227+
## Conclusion
228+
229+
By following this guide, you've learned how to create help pages for your Botkit
230+
extensions. Well-documented commands improve user experience and make your bot more
231+
accessible to new users.
232+
233+
<!-- prettier-ignore -->
234+
> [!TIP]
235+
> Keep your help pages concise, clear, and up-to-date with your bot's functionality.
236+
237+
<!-- prettier-ignore -->
238+
> [!IMPORTANT]
239+
> Always provide examples for complex commands to help users understand how to use them correctly.

‎guides/getting-started.md

+36-12
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@ Before we begin, ensure you have the following:
1212
2. Basic understanding of Python and Discord concepts
1313
3. A Discord account and access to the Discord Developer Portal
1414

15-
> [!IMPORTANT] If you haven't already, create a Discord application and bot user in the
15+
<!-- prettier-ignore -->
16+
> [!TIP]
17+
> If you haven't already, create a Discord application and bot user in the
1618
> [Discord Developer Portal](https://discord.com/developers/applications). You'll need
1719
> the bot token for later steps.
1820
@@ -25,7 +27,9 @@ repository.
2527
version for your operating system.
2628
2. Follow the installation instructions for your OS.
2729

28-
> [!TIP] On Windows, you can use the Git Bash terminal that comes with Git for a
30+
<!-- prettier-ignore -->
31+
> [!TIP]
32+
> On Windows, you can use the Git Bash terminal that comes with Git for a
2933
> Unix-like command-line experience.
3034
3135
To verify Git is installed correctly, open a terminal or command prompt and run:
@@ -54,7 +58,9 @@ git clone https://github.com/nicebots-xyz/botkit
5458
cd botkit
5559
```
5660

57-
> [!NOTE] Cloning the repository creates a local copy of Botkit on your machine,
61+
<!-- prettier-ignore -->
62+
> [!INFO]
63+
> Cloning the repository creates a local copy of Botkit on your machine,
5864
> allowing you to build your bot using the Botkit framework.
5965
6066
## Step 3: Install Dependencies
@@ -73,7 +79,9 @@ pip install pdm
7379
pdm install
7480
```
7581

76-
> [!NOTE] PDM will read the `pyproject.toml` file and install all necessary dependencies
82+
<!-- prettier-ignore -->
83+
> [!NOTE]
84+
> PDM will read the `pyproject.toml` file and install all necessary dependencies
7785
> for Botkit.
7886
7987
## Step 4: Configure Your Bot
@@ -90,7 +98,9 @@ bot:
9098
9199
Replace `YOUR_BOT_TOKEN_HERE` with the actual token of your Discord bot.
92100

93-
> [!CAUTION] Never share your bot token publicly or commit it to version control. Treat
101+
<!-- prettier-ignore -->
102+
> [!CAUTION]
103+
> Never share your bot token publicly or commit it to version control. Treat
94104
> it like a password.
95105

96106
## Step 5: Create a New Extension Folder
@@ -122,7 +132,9 @@ from .main import setup, default
122132
__all__ = ["setup", "default"]
123133
```
124134

125-
> [!NOTE] This file imports and exposes the necessary components from our `main.py` file
135+
<!-- prettier-ignore -->
136+
> [!NOTE]
137+
> This file imports and exposes the necessary components from our `main.py` file
126138
> (which we'll create next). It allows Botkit to access these components when loading
127139
> the extension.
128140

@@ -165,7 +177,9 @@ Let's break down what we've done here:
165177
- The `setup` function is required by Botkit to add our cog to the bot.
166178
- We define a `default` dictionary for the extension's configuration.
167179

168-
> [!TIP] Using type hints (like `bot: discord.Bot`) helps catch errors early and
180+
<!-- prettier-ignore -->
181+
> [!TIP]
182+
> Using type hints (like `bot: discord.Bot`) helps catch errors early and
169183
> improves code readability. It's a good practice to use them consistently in your code.
170184

171185
## Step 8: Adding Commands
@@ -212,7 +226,9 @@ Let's explain these commands:
212226
- Creates an embed with various pieces of information about the user.
213227
- Responds with the created embed.
214228

215-
> [!NOTE] Slash commands are the modern way to create Discord bot commands. They provide
229+
<!-- prettier-ignore -->
230+
> [!NOTE]
231+
> Slash commands are the modern way to create Discord bot commands. They provide
216232
> better user experience and are easier to discover than traditional prefix-based
217233
> commands.
218234

@@ -232,7 +248,9 @@ async def on_ready(self):
232248
This listener will print a message to the console when the bot has successfully
233249
connected to Discord.
234250

235-
> [!TIP] Event listeners are great for performing actions based on Discord events, such
251+
<!-- prettier-ignore -->
252+
> [!TIP]
253+
> Event listeners are great for performing actions based on Discord events, such
236254
> as when a member joins a server or when a message is deleted.
237255

238256
## Step 10: Final `main.py` File
@@ -290,7 +308,9 @@ Now that we've created our extension, let's run the bot:
290308
pdm run start
291309
```
292310

293-
> [!IMPORTANT] Ensure your bot token is correctly set in the `config.yml` file before
311+
<!-- prettier-ignore -->
312+
> [!IMPORTANT]
313+
> Ensure your bot token is correctly set in the `config.yml` file before
294314
> running the bot.
295315

296316
If everything is set up correctly, you should see the "Bot is ready!" message in your
@@ -305,10 +325,14 @@ This extension includes:
305325
2. A more complex "userinfo" slash command that creates an embed
306326
3. An event listener for the "on_ready" event
307327

308-
> [!TIP] To continue improving your bot, consider adding more commands, implementing
328+
<!-- prettier-ignore -->
329+
> [!TIP]
330+
> To continue improving your bot, consider adding more commands, implementing
309331
> additional event listeners, or integrating with external APIs or databases.
310332

311-
> [!WARNING] Always be cautious when handling user data and permissions in your bot.
333+
<!-- prettier-ignore -->
334+
> [!WARNING]
335+
> Always be cautious when handling user data and permissions in your bot.
312336
> Ensure you're following Discord's Terms of Service and Developer Policy.
313337

314338
Remember to always use type hinting in your code. It helps with code readability,

0 commit comments

Comments
 (0)