wlinator/tux
1
Fork 0
mirror of https://github.com/allthingslinux/tux.git synced 2024-10-02 16:43:12 +00:00
Code Issues Releases Wiki Activity

docs(development.md): add detailed explanation about Cogs in the Cogs Primer section to provide better understanding for developers

Browse source
This commit is contained in:
kzndotsh 2024-08-17 07:26:20 +00:00
parent fd16a93326
commit 1bf1642b5b
1 changed files with 24 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
docs/development.md
View file

@ -53,11 +53,13 @@ The project is structured as follows:
- `help.py`: The help command class definition.
### Configuration
- `.env.example`: The example environment file containing the environment variables required for the bot.
- `config/`: The config directory containing the configuration files for the bot.
- `settings.json`: The settings file containing the bot settings and configuration.
### Documentation
- `docs/`: The documentation directory containing the project documentation.
- `CONTRIBUTING.md`: The contributing guidelines for the project.
- `README.md`: The project README file containing the project overview and installation instructions.
@ -66,6 +68,7 @@ The project is structured as follows:
- `LICENSE.md`: The license file containing the project license information.
### Development
- `pyproject.toml`: The Poetry configuration file containing the project metadata and dependencies for the bot.
- `Dockerfile`: The Dockerfile containing the container configuration for the bot.
- `docker-compose.yml`: The Docker Compose file containing the container environment configuration for the bot.
@ -73,13 +76,33 @@ The project is structured as follows:
- `.gitignore`: The Git ignore file containing the files and directories to be ignored by Git.
### CI/CD
- `.pre-commit-config.yaml`: The pre-commit configuration file containing the pre-commit hooks for the bot.
- `.github/workflows/`: The GitHub Actions directory containing the CI/CD workflows for the bot.
- `renovate.json`: The Renovate configuration file containing the dependency update settings for the bot.
## Cogs Primer
TODO: Add cogs primer
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.
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.
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.
### Cog Essentials
- Each cog is a Python class that subclasses commands.Cog.
- Every regular command or "prefix" is marked with the `@commands.command()` decorator.
- Every app or "slash" command is marked with the `@app_commands.command()` decorator.
- Every hybrid command is marked with the `@commands.hybrid_command()` decorator.
- Every listener is marked with the `@commands.Cog.listener()` decorator.
tl;dr - Extensions are imported "modules", cogs are classes that are subclasses of `commands.Cog`.
Referance:
- [discord.py - Cogs](https://discordpy.readthedocs.io/en/stable/ext/commands/cogs.html)
- [discord.py - Extensions](https://discordpy.readthedocs.io/en/stable/ext/commands/extensions.html)
## Database Primer