You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/development.md
+24-1
Original file line number
Diff line number
Diff line change
@@ -53,11 +53,13 @@ The project is structured as follows:
53
53
-`help.py`: The help command class definition.
54
54
55
55
### Configuration
56
+
56
57
-`.env.example`: The example environment file containing the environment variables required for the bot.
57
58
-`config/`: The config directory containing the configuration files for the bot.
58
59
-`settings.json`: The settings file containing the bot settings and configuration.
59
60
60
61
### Documentation
62
+
61
63
-`docs/`: The documentation directory containing the project documentation.
62
64
-`CONTRIBUTING.md`: The contributing guidelines for the project.
63
65
-`README.md`: The project README file containing the project overview and installation instructions.
@@ -66,20 +68,41 @@ The project is structured as follows:
66
68
-`LICENSE.md`: The license file containing the project license information.
67
69
68
70
### Development
71
+
69
72
-`pyproject.toml`: The Poetry configuration file containing the project metadata and dependencies for the bot.
70
73
-`Dockerfile`: The Dockerfile containing the container configuration for the bot.
71
74
-`docker-compose.yml`: The Docker Compose file containing the container environment configuration for the bot.
72
75
-`justfile`: The Justfile containing the development commands for the bot.
73
76
-`.gitignore`: The Git ignore file containing the files and directories to be ignored by Git.
74
77
75
78
### CI/CD
79
+
76
80
-`.pre-commit-config.yaml`: The pre-commit configuration file containing the pre-commit hooks for the bot.
77
81
-`.github/workflows/`: The GitHub Actions directory containing the CI/CD workflows for the bot.
78
82
-`renovate.json`: The Renovate configuration file containing the dependency update settings for the bot.
79
83
80
84
## Cogs Primer
81
85
82
-
TODO: Add cogs primer
86
+
There comes a point in your bot’s development when you want to organize a collection of commands, listeners, and some state into one class. Cogs allow you to do just that.
87
+
88
+
It should be noted that cogs are typically used alongside with Extensions. An extension at its core is a python file with an entry point called setup. This setup function must be a Python coroutine. It takes a single parameter of the Bot that loads the extension.
89
+
90
+
With regards to Tux, we typically define one cog per extension. Furthermore, we have a `CogLoader` class that loads our cogs (technically, extensions) from the `cogs` directory and registers them with the bot at startup.
91
+
92
+
### Cog Essentials
93
+
94
+
- Each cog is a Python class that subclasses commands.Cog.
95
+
- Every regular command or "prefix" is marked with the `@commands.command()` decorator.
96
+
- Every app or "slash" command is marked with the `@app_commands.command()` decorator.
97
+
- Every hybrid command is marked with the `@commands.hybrid_command()` decorator.
98
+
- Every listener is marked with the `@commands.Cog.listener()` decorator.
99
+
100
+
tl;dr - Extensions are imported "modules", cogs are classes that are subclasses of `commands.Cog`.
0 commit comments