1. Goal
2. Installation
3. Usage
4. Contributing
5. Creating a sample plugin
6. Style guide
   1. Classes
   2. Functions
   3. Variables
   4. Commenting
7. Gerbot tools
   1. Command Builder
   2. Production Mode

Gerbot is a python-based Discord bot written for the University of Central Florida's IT Discord. It's goal is to provide UCF IT majors with opportunities to socialize, study, and gain opportunities through various channels dedicated to organizations/interests.

To install Gerbot on your machine, go ahead and clone the respository by doing:

git clone https://github.com/s1ag/Gerbot

Then go ahead and create a virtual environment with venv like so:

python3 -m venv env

Once the virtual environment has been created, activate it:

Linux:

source env/bin/activate

Window's 10:

.\env\Scripts\activate

Upon being activated you should see (env) besides your terminal. Now install the dependencies:

pip3 install -r requirements.txt 

To use Gerbot, you must supply a valid bot token. First create a file in the src directory called .env. Inside this file populate it as follows:

BOT_TOKEN=DISCORD_TOKEN_HERE

Finally, run main.py and you should see that your bot is now running :)

python3 main.py

While development should be done using the venv, persistent deployment can be accomplished by using the Dockerfile provided in the repo.

You will need to first fork the repo, then submit a pull request that will be reviewed by the development team.

For suggestions/concerns please submit an issues ticket. Feel free to join us and become part of the development community through here: https://discord.gg/YM5QRzx and post your inquiries/suggests in the #bot-chat channel. You may also request to join the team there as well.

The plugins live within the cog directory, while the helper functions live outside the cog directory.

The code begins with imports

import discord 
from discord.ext import commands

Proceeded by a class based structure

class Plugin(commands.Cog):

Create a init function within the class

def __init__(self, bot):
  self.bot = bot
  self._last_member = None

Use @commands.command to signify that it's a command, and assign it a list of aliases to use for others to reference upon:

@commands.command(aliases = ['example', 'test', 'sample'])

Create a function, naming it anything. In this case, we'll call it first_plugin

async def simple_plugin(self, context, arg):

Context is how we will send messages and access everything involving message data, async is referencing to async programming and is needed for discord.py to work. Arg is what will be passed in after our command. In this case it will be ping.

if(arg == "ping"):
  await context.send("pong!")

We check to see if the argument passed is ping, and respond accordingly. To make sure that this plugin is loaded, we have to create a setup point like so:

def setup(bot):
    bot.add_cog(FirstPlugin(bot))

Full code:

import discord
from discord.ext import commands
from system_utils.container_logger import container_logger
class FirstPlugin(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self._last_member = None

    @commands.command(aliases = ['example', 'test', 'sample'])
    async def first_plugin(self, context):
        if(arg == "ping"):
            await context.send("pong")
        
def setup(bot):
    bot.add_cog(FirstPlugin(bot))

Congrulations! You've made your first plugin and dipped your toes into working with Gerbot.

Gerbot conforms to the PEP8 style, and enforces this using the black python plugin alongside with flake8. During contributing, follow these guidelines outline below as well. Black can be installed using:

pip install black

To format a file use:

black filename.py

To format an entire directory use:

black folder/

All classes must follow a uppercase standard, this applies to cogs classes and the file names of these cogs as well. We do not follow snake case or camelcase for classes, and should refrain from doing so. An example of this standard:

FileName.py

Opposed to:

fileName.py

Or:

file_name.py

Functions will follow the same naming convention as classes, within the helper functions outside of cogs we will state the datatype explicilty. This is also true for helper functions as well. An example:

def function(string: str):
    print(string)

Variables follow traditional snake case such as:

test_string = str()

Gerbot style in regards to comment is following docstrings. Example:

"""
This is a comment in the preferred way
"""
def comment(string: str):
    print(string)

Gerbot has many some system utils that you may use to aid you in your development

This is an automated tool that will build commands.json for you, not requiring you to do so. To add your cog command data into the list, an example from the cog CustomStudyRoom.py is provided:

@commands.has_permissions(manage_roles=True)
    async def CreateStudyRoom(self, context, class_code=None):
        command_prefix = "!sr"
        command_name = "Custom Study Room"
        alias = "createstudyroom, studyroom, sr"
        example = "!sr"

All that is necessary is to create variables for command_prefix, command_name, alias, and example and command builder will build your commands.json. Within command builder also lies the cog loader, which allows you to specify if you have any cogs that have apis to exclude, simply add it to the api_cogs list. The cat, and stock cogs are an example of cogs with apis. Adding a cog to the list:

"""
Before change
"""
api_cogs = ["Stocks.py", "Cat.py"]

"""
after change
"""
api_cogs = ["Stocks.py", "Cat.py", "Api.py"]

Within main.py lies a boolean, that will determine if it's in a deployed or development mode. If it's in development mode, certain features will be disabled for you, such as webhooks and will instead enable local debugging. It is preferable to disable when you are developing your features, and reenable when you have done a pull request. This variable is prod_mode, and can be toggled on or off.