Skip to content

Commit 1bf1642

Browse files
committed
docs(development.md): add detailed explanation about Cogs in the Cogs Primer section to provide better understanding for developers
1 parent fd16a93 commit 1bf1642

File tree

1 file changed

+24
-1
lines changed

1 file changed

+24
-1
lines changed

docs/development.md

+24-1
Original file line numberDiff line numberDiff line change
@@ -53,11 +53,13 @@ The project is structured as follows:
5353
- `help.py`: The help command class definition.
5454

5555
### Configuration
56+
5657
- `.env.example`: The example environment file containing the environment variables required for the bot.
5758
- `config/`: The config directory containing the configuration files for the bot.
5859
- `settings.json`: The settings file containing the bot settings and configuration.
5960

6061
### Documentation
62+
6163
- `docs/`: The documentation directory containing the project documentation.
6264
- `CONTRIBUTING.md`: The contributing guidelines for the project.
6365
- `README.md`: The project README file containing the project overview and installation instructions.
@@ -66,20 +68,41 @@ The project is structured as follows:
6668
- `LICENSE.md`: The license file containing the project license information.
6769

6870
### Development
71+
6972
- `pyproject.toml`: The Poetry configuration file containing the project metadata and dependencies for the bot.
7073
- `Dockerfile`: The Dockerfile containing the container configuration for the bot.
7174
- `docker-compose.yml`: The Docker Compose file containing the container environment configuration for the bot.
7275
- `justfile`: The Justfile containing the development commands for the bot.
7376
- `.gitignore`: The Git ignore file containing the files and directories to be ignored by Git.
7477

7578
### CI/CD
79+
7680
- `.pre-commit-config.yaml`: The pre-commit configuration file containing the pre-commit hooks for the bot.
7781
- `.github/workflows/`: The GitHub Actions directory containing the CI/CD workflows for the bot.
7882
- `renovate.json`: The Renovate configuration file containing the dependency update settings for the bot.
7983

8084
## Cogs Primer
8185

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`.
101+
102+
Referance:
103+
104+
- [discord.py - Cogs](https://discordpy.readthedocs.io/en/stable/ext/commands/cogs.html)
105+
- [discord.py - Extensions](https://discordpy.readthedocs.io/en/stable/ext/commands/extensions.html)
83106

84107
## Database Primer
85108

0 commit comments

Comments
 (0)