Commit c51f4eaa authored by Aleksa Radovic's avatar Aleksa Radovic 💤
Browse files

Doc Generation Check

parent 838c48f9
Pipeline #342402914 passed with stages
in 2 minutes and 47 seconds
# Apex Sigma Changelog
## [WIP]
### Changed
- Change command list MD file location.
- Replace documentation files with new, reworked content.
## 4.91.1820 Fubuki
### Changed
......
# Apex Sigma: The Database Giant
<div align="center">
<a href="https://lucia.moe/">
<img src="https://i.imgur.com/TRSdGni.png" alt="Sigma Banner">
<a href="https://luciascipher.com/">
<img src="https://i.imgur.com/O5832Le.png" alt="Sigma Banner">
</a>
</div>
......
import sphinx_rtd_theme
extensions = [
"sphinx_rtd_theme",
]
html_logo = "project_sigma_white.png"
html_theme = "sphinx_rtd_theme"
html_theme_options = {
"gitlab_url": "https://gitlab.com/lu-ci/sigma/apex-sigma"
}
html_static_path = ['static']
html_css_files = [
'custom.css'
]
# Core Configuration
\ No newline at end of file
# Configuration
- [Core](/config/core)
- [Modules](/config/modules)
# Module Configuration
\ No newline at end of file
# Configuring Sigma's Core
## Making The Folders
Inside Sigma's main directory, you should see a folder called `config`. Inside said folder there are another two, `core`
and `modules`. If these folders do not exist, feel free to create them. The `core` folder contains `.yml` files used to
configure Sigma's core functions. Only the core configuration files are mandatory for Sigma to work.
## Making The Core YAMLs
Go to `config/core` and make **three** new files.
* discord.yml
* database.yml
* preferences.yml
Your `config` folder should look like this:
```
config
└── core
   ├── cache.yml
   ├── database.yml
   ├── discord.yml
   └── preferences.yml
```
### `discord.yml` Contents
```yml
bot: true
token: 'myfancydiscordtokengoeshere'
owners:
- 123456789123456789
```
* `bot`: Controls if the account the bot is running is a proper bot account. This is implemented as Sigma is able to be
a self bot. If this is `false` all event handling will be disabled and the bot will only respond to itself. The value
of the `bot` key is **boolean**.
* `token`: Your **Discord Client Token**. Which you can obtain from your applications. You can find your
applications [Here](https://discordapp.com/developers/applications/me). The value of the `token` key is a **string**.
* `owners`: Contains a list of User IDs that should be marked as bot owners. Users with bot owners privileges can
control any and all bot functions. Be careful who you designated as a bot owner, some functions are dangerous. The
value of the `owners` key is a **list of integers**.
* `max_messages`: It sets a limit of how many message objects should be cached. The default is 5000 as set by
discord.py, the minimum is 100. If you set it below that, it'll just silently use 100. The value of the `max_messages`
key is an **integer**.
### `database.yml` Contents
```yml
database: aurora
auth: false
host: '127.0.0.1'
port: 27017
username: 'username'
password: 'password'
```
* `database`: The name of the database object in MongoDB for storing your data. It can be anything you want. Changing it
will cause issues as the data stored will be in another location afterwards. The value of the `database` key is a **
string**.
* `auth`: Tells Sigma if the database requires authorization or not. If you have no changed any settings in Mongo, set
this to `false`. If your MongoDB server does indeed need a username and password, set it to `true`. The value of
the `auth` key is a **boolean**.
* `host`: Quite simply the IP address of the MongoDB server. If it's running on the same machine, set it to `127.0.0.1`
or `localhost`. The value of the `host` key is a **string**.
* `port`: This is the connection port of the MongoDB server. By default it is `27017`. The value of the `port` key is
an **integer** but can be a **string**.
* `username`: The authorization username for the MongoDB server if authorization is required. If authorization is not
required, just input anything as the username, the key is still needed in the configuration file. The value of
the `username` key is a **string**.
* `password`: Same as the `username` key. Used for authorization when needed. If you don't need to authorize, input
anything you want, the key is still required. The value of the `password` key is a **string**.
### `preferences.yml` Contents
```yml
dev_mode: false
status_rotation: true
text_only: false
music_only: false
prefix: '>>'
currency: 'Kud'
currency_icon: '⚜'
website: 'https://lucia.moe/#/sigma'
movelog_channel: 123456789123456789
errorlog_channel: 123456789123456789
key_to_my_heard: '5up3r_53cr3t_3ncrypt10n'
```
* `dev_mode`: Defines if the bot is in development mode or not. When in dev mode, errors that occur are not stored in
the database with an error token. But their full trace-back is printed in the shell console where it is running. The
value of the `dev_mode` key is a **boolean**.
* `status_rotation`: If true, Sigma's status will automatically rotate each 3 minutes. The list of statuses is hardcoded
for now, but they're pretty fun. The value of the `status_rotation` key is a **boolean**.
* `text_only`: If `true`, Sigma will not load any commands inside the `Music` module group. If `false` nothing changes,
and we recommend you keep it to `false`. The value of the `text_only` key is a **boolean**.
* `music_only`: If `true`, Sigma will not load any commands outside the `Music` module group. If `false` nothing
changes, and we recommend you keep it to `false`. The value of the `music_only` key is a **boolean**.
* `prefix`: Specifies the default prefix for all of Sigma's commands. The default value is `>>`. The value of
the `prefix` key is a **string**.
* `currency`: Since Sigma has an internal currency, this controls the name of that currency. By default it's `Kud`, but
you can set it to anything you want. The value of the `currency` key is a **string**.
* `currency_icon`: Controls the icon of the specified currency. While it can be an emoticon string like `:fleur_de_lis:`
, to preserve compatibility, please use UTF-8 emoticon characters like `⚜`. Which is also the default for the icon.
The value of the `currency_icon` key is a **string**.
* `website`: The URL leading to Sigma's website that contains all the commands and help for the bot. This is used in the
help command. The value of the `website` key is a **string**.
* `movelog_channel`: The ID of the channel that should log movement messages. Whenever the bot is added to a server a
message with basic information about the server is sent to that channel. The value of the `movelog_channel` key is
an **integer**.
* `errorlog_channel`: The ID of the channel that should log errors. When a command breaks and fails to execute,
information about what went wrong is, aside from being stored in the database, also sent to this channel (if
specified). The value of the `errorlog_channel` key is an **integer**.
* `key_to_my_heart`: Sigma has an **encrypt** and **decrypt** command. Those commands use this key as the
encryption/decryption key for the given data. You can make this as short or as long as you'd like. The value of
the `website` key is a **string**.
# Plugin Configuration Files
All plugin configuration files are `.yml` files that need to be made manually. They need to be made in
the `config/plugins/` folder. Plugin configuration files need to be named after the main command name of their
respective commands. For example, if you are making a configuration file for the `>>slots` command, the configuration
file needs to be named `slots.yml`. They can not use command alternate names/aliases.
## Interaction Adding
The interaction addition configuration tells the bot where to send a message notifying the authors that a new
interaction has been submitted. This can be used as a safety protocol against malicious submissions, and a quick way to
remove bad submissions. If a bot owner reacts to one of these interaction log messages with an **❌** emote the bot will
remove it and react with **🔥** if it deletes it, that is, if the submission is found in the database and deleted.
**Note: This requires the `imgur` command to be set up.**
**Example of log message**:
> ![Interaction Log Example](https://i.imgur.com/GGc9F4s.png)
**Configuration file contents**:
```yml
log_ch: 01234567890123456789
```
The `log_ch` key value needs to be an **Integer**.
> The file for storing this configuration is `addinteraction.yml`. You can obtain a channel's ID by using the `>>cid` command in that channel, or by targeting a channel with the same command. Or by activating Developer Mode in Discord's Appearance settings, right clicking the channel of your choice, and clicking Copy ID, the ID will be copied to your clipboard.
## Bot Development Suggestions
This function serves to have a global centralized suggestion channel where users can submit suggest changes they want
made to the bot. Usually development and feature wise. When someone uses the `>>botsuggest` command their suggestion is
sent to the bot suggestion channel, given a suggestion ID and stored in the database, as well as automatically given an
Arrow Up and Arrow Down emote reaction so users can vote on the suggestion. This ID, shown in the bottom left of the
suggestion message, can be used with the `>>declinesuggestion` and `>>approvesuggestion` commands which allow fast
responses to suggestions.
**Example of suggestion message**:
> ![Suggestion Message Example](https://i.imgur.com/5UdGnZw.png)
**Configuration file contents**:
```yml
channel: 01234567890123456789
```
The `channel` key value needs to be an **Integer**.
> The file for storing this configuration is `botsuggest.yml`. You can obtain a channel's ID by using the `>>cid` command in that channel, or by targeting a channel with the same command. Or by activating Developer Mode in Discord's Appearance settings, right clicking the channel of your choice, and clicking Copy ID, the ID will be copied to your clipboard.
## Suggestion Approval
This command automates a lot of stuff for developers when it comes to approving suggestions and adding them to a TODO
list. Well, GitLab honestly since that's what Lucia's Cipher uses. When the `>>approvesuggestion` command is used with a
suggestion ID the suggestion message in the suggestion channel is marked with a check mark and if GitLab repository
information is in the config it is also added as a new issue with a **Suggestion** tag.
**Example of suggestion issue**:
![Suggestion Issie Example](https://i.imgur.com/8gVeBOf.png)
**Configuration file contents**:
```yml
token: 'gitlab_personal_access_token'
project: 123456789
```
The `token` key value needs to be a **String**, the `project` key value needs to be a **String** or an **Integer**.
> The file for storing this configuration is `approvesuggestion.yml`. The `token` which is a Personal Access Token can be obtained from your settings [here](https://gitlab.com/profile/personal_access_tokens). I'm not sure which scopes are required so I enable all of them. Just remember to never give that token to anyone no matter what. The `project` is the ID of the GitLab project. It can be found on your project page under the project's description, where it says:
`Project ID: XXXXXXX`. The `XXXXXXX` is what you want here.
## Cat Command
The `>>cat` command pulls images of cats from an external API. This API has a usage limit when used without an API key.
The configuration for this command, as well as the API key is **NOT REQUIRED** for the command to work. But is highly
recommended to have.
**Configuration file contents**:
```yml
api_key: 'cat_api_key'
```
The `api_key` key value needs to be a **String**.
> The file for storing this configuration is `cat.yml`. You can obtain an API key for the Cat API at their documentation page [here](http://thecatapi.com/docs.html).
## Dictionary
This is the configuration file for the `>>dictionary` command. The function for the dictionary command uses the Oxford
dictionary API, and requires a key to use their features.
**Configuration file contents**:
```yml
app_id: 'your_app_id'
app_key: 'your_app_api_key'
```
Both the `app_id` and `app_key` keys need to be **Strings**.
> The file for storing this configuration is `dictionary.yml`. You can obtain the application credentials from Oxford's developer page
[here](https://developer.oxforddictionaries.com/).
## Food Recipe
Unfortunately a tool for finding recipes was actually really hard to find. Or rather, a good and reliable, but free and
open one, to be precise. Sigma uses the Food2Fork API to search for recipes, and requires their API key.
**Configuration file contents**:
```yml
api_key: 'my_f2f_api_key_here'
```
The `api_key` key value is a **String**.
> The file for storing this configuration is `foodrecipe.yml`. You can obtain an API key from their API page
[here](http://food2fork.com/about/api).
## URL Shortening
For the `>>shortenurl` command, the Bit.ly API is used. By default and hardcoded, all links generated are ad-less simple
redirect URLs. To use this function a API key is required.
**Configuration file contents**:
```yml
access_token: 'my_access_token'
```
The `access_token` key value is a **String**.
> The file for storing this configuration is `shortenurl.yml`. The access token can be obtained from their official dev page
[here](http://dev.bitly.com/). You can generate a *Generic Access Token* once there.
## Urban Dictionary
This command uses the Urban Dictionary API that needs to be consumed on RapidAPI. RapidAPI is basically a market of
various APIs, and the UD API is one of them. It's required for UD command to function.
**Configuration file contents**:
```yml
api_key: 'your_rapidapi_key'
```
The `api_key` key value is a **String**.
> The file for storing this configuration is `urbandictionary.yml`. The urban dictionary API can be seen and consumed
[here](https://rapidapi.com/community/api/urban-dictionary).
## Weather
To use the `>>weather` command you need a Dark Sky API secret key.
**Configuration file contents**:
```yml
secret_key: 'your_ds_secret_key'
```
The `secret_key` key value is a **String**.
> The file for storing this configuration is `weather.yml`. You can get the secret key at the developer page
[here](https://darksky.net/dev/account).
## Wolfram Alpha
Wolfram Alpha is one of the most amazing mathematics and statistics engines. Capable of processing extreme operations
and finding various data. Way beyond any of our capabilities, so we mooch off of them a bit, and use their API. To use
the `>>wa` command, you need their API key.
**Configuration file contents**:
```yml
app_id: 'your_app_id'
```
The `app_id` key value is a **String**.
> The file for storing this configuration is `wolframalpha.yml`. You can get the application ID at their API product page
[here](https://products.wolframalpha.com/api/).
# Adding a new feature
1. Fork the repository.
1. Create a feature branch in your repository and base it on the current `master` branch.
1. Commit your changes and push them to the feature branch of your repo.
1. Open a pull request from your feature branch.
We will respond to your PR as soon as possible.
# Submitting a Pull Request
## Formatting
Make sure that your code is formatted according to [PEP8](https://www.python.org/dev/peps/pep-0008/).
Your Editor/IDE probably comes with a linter installed or has plugins for linting available.
You can also use a CLI tool like `flake8` to manually lint your code.
## Commit Messages
Keep your commit messages short and informative. You can add a more comprehensive description below the commit message.
Things to **not** include in your commit message:
* `@tag` team or username references
* `#ref` issue or pull request references
Never include `[ci skip]` or similar to skip CI. Pull requests skipping any kind of CI will be ignored.
Check out this [article](https://chris.beams.io/posts/git-commit) if you want to know why good commit messages matter.
# Command Development
\ No newline at end of file
# Core Development
Don't.
# Event Development
\ No newline at end of file
# Development
Want to write your own code and add functions?
- [Commands](/development/commands)
- [Events](/development/events)
- [Modules](/development/modules)
# Module Construction Guide
## About
Sigma has her own internal framework that is used for handling commands and the functions that they can access. This
will explain how the Apex Sigma module framework works and how to control it as well as some examples for basic
functions.
## Modules
Sigma's modules are composed of two main things, a module information `.yml` and the module `.py` file and function. In
the following examples we'll make a simple `>>ping` command that will respond with a simple text message and the bot's
latency and a message event that will unflip tables.
### Preparation
The modules are stored in `sigma/modules` and grouped into folders. For organization and clarity during the guide we'll
make a new folder in the `modules` folder and name it `custom`. Within that folder create two new files, `module.yml`
, `ping.py` and `unflipper.py`. Since we said that the command we're making is named ping, the `.py` file for it must be
named `ping.py`.
### YAML Information Container
The YAML information container is the `module.yml` file we previously created, and it looks like this.
#### Layout
```yml
name: Custom Commands # The name of the module.
category: custom # The category of the module.
enabled: true # Is the module enabled or not.
commands: # List of commands in the module.
- name: ping # Name of the command function.
alts: # List of aliases for that command.
- "pang"
enabled: true # Is the command enabled or not.
permissions: # Permission settings for the command.
nsfw: false # Is the command a NSFW command.
owner: false # Is the command only for owners.
dmable: true # Can the command be used in DMs.
usage: "{pfx}{cmd}" # Usage example for the command.
description: # The description of the command.
"Returns a message with the bot's current latency."
events: # List of events in the module.
- name: unflipper # Name of the event function.
type: message # Type of the event it listens for.
enabled: true # Is the event enabled or not.
```
#### Module Keys
- `name`: The name of the module used for organization and vanity.
- `category`: The category of the module, when the `>>modules` command is used, it lists all the module categories. The
category of modules that this one falls into.
- `enabled`: If set to `true` the module and it's nested commands are loaded, if `false` no command in that module will
be loaded.
- `commands`: A list of dicts that contain information about each command that is a part of that module.
#### Command Keys
- `name`: The name of the file and function of the command as well as the main command that function responds to.
- `alts`: Alternative commands that will call the same function.
- `enabled`: If set to `true` the command will be loaded, if `false` it will not be loaded.
- `permissions`: Contains details of where the command can be used and by who.
- `usage`: The usage example of the command. It usually has `{pfx}` and `{cmd}` in it, being the `Prefix`
and `Command Name` respectively.
- `description`: The verbose description of the command with details about it.
#### Permission Keys
- `nsfw`: Detemines if the command is usable anywhere or just in NSFW channels.
- `owner`: Determines if the command is usable by anyone or just the bot's owners.
- `partner`: Determines if the command is usable anywhere or just on partner servers.
- `dmable`: Determines if the command is usable in Direct Messages or only on guilds.
#### Event Keys
- `name` The name of the file and function of the event that is called.
- `type`: The type of event the function listens for. This is any event from the `discord.py` library with the `on_`
removed from it's name. Such as `on_message`, `on_member_join` and the like, resulting in `message` and `member_join`.
- `enabled`: If set to `true` the event will be loaded, if `false` it will not be loaded.
### Ping Command
The code of the actual `>>ping` command and function. The following code goes into `ping.py` that we created.
```py
async def ping(cmd, message, args):
bot_latency = round(cmd.bot.latency * 1000, 2)
response = f'Pong! Latency: {bot_latency}ms'
await message.channel.send(response)
```
So what does all this mean. We defined a new asyncronous function using `async def` and named it `ping` after our
command and file name. Every command takes `3` arguments which are `cmd`, `message` and `args`.
- `cmd`: Main command class, the gateway to accessing the command's internal function as well as the `bot` class which
is the main discord client connection class.
- `message`: The `discord.Message()` class that was passed when the message was sent, containing it's contents, who the
author is, where it was sent and similar information.
- `args`: Short for `arguments` it is a list of what else the message had in it besides the command. For example if the
command entered was `>>ping me daddy` args would contain `['me', 'daddy']` in it, otherwise it's an empty list.
We grabbed the bot's latency accessible through the client's attribute of `.latency`. Since it is stored as a `float` in
seconds (for example `0.0694123`) we multiplied it by `1000` to get the latency in miliseconds and rounded the number
to `2` decimals. We made a new string response from that using a `fString` which was introduced in Python 3.6 that will
be sent as a reply. Then we call and await the method to send the response to the channel where the command, that is the
message that called the command, originated from.
### Unflipper Event
The code of the `on_message`, that is the `message` event in Sigma that will result in automatically unflipped tables.
This code resides in `unflipper.py` as created earlier and specified in the `module.yml`.
```py
async def unflipper(ev, message):
flipped_table = '(╯°□°)╯︵ ┻━┻'
if flipped_table in message.content:
unflipped_table = '┬─┬ ノ( ゜-゜ノ)'
await message.channel.send(unflipped_table)
```
Events are composed of an `ev` argument as it's core argument contained in every event, however depending on the event
type, other arguments might be present, they might be members, guilds, messages, etc. In this example that is
a `message` argument due to the event being triggered by a `message` event.
- `ev`: Main event class, the same as the `cmd` argument for commands, giving access to the bot core and functions from
the event.
- `*args`: Whatever arguments the event has in it other than `ev` depending on it's type.
The command checks if the content of the message sent has a flipped table in it. If it does it responds to that channel
with an unflipped table, simple enough.
\ No newline at end of file
# Module Control Files
\ No newline at end of file
# Docker Setup
\ No newline at end of file
# Downloading and Updating
Before we do anything, we need Sigma's repository which contains all her code.
If you installed Git, which was optional above, use the "Git" section,
otherwise the "Manual" one.
## Manual
You can download the entire repository from [here](https://gitlab.com/lu-ci/sigma/apex-sigma/-/archive/master/apex-sigma-master.zip) as a ZIP file.
Once it's done downloading just extract it to where you want Sigma's files to be.
Updating manually is crude, you re-download the ZIP above and overwrite the
entire directory where Sigma's files are.
## Git
Open the location where you want to clone Sigma's repository in a terminal.
And hit the good old clone command with her repository [URI](https://gitlab.com/lu-ci/sigma/apex-sigma.git).
```
git clone https://gitlab.com/lu-ci/sigma/apex-sigma.git
```
Updating with git pretty much works the same,
except you don't need to clone it again,
you just run the following from Sigma's directory.
```
git pull
```
Easy, huh?
Neither of these touch your configuration or data.
The configuration files are not a part of the repository,
and the data is stored in the database.
\ No newline at end of file
# Frequently Asked Questions
*Sigh...*
## Will you add a command that sells all non-recipe items?
No.
## Does my PC need to be on for the bot to run?
Yes. Unless you rent a server to run it non-stop. I recommand Scaleway.
We use their Dedibox service and rent a dedicated server for Sigma.
## How can I see the stuff stored in the database?
There are multiple tools that can access MongoDB, I use Robo3T.
## Music commands don't work!
If you're self-hosting, make sure text-only mode is off and
that FFMPEG is set up correctly.
Otherwise, yes, because music is off for the main instance.
Too performance costly to keep publicly available.
## What is "earned" Kud?
Kud obtained from minigames that aren't gambling.
Kud generated from admins also doesn't count towards it.
## I have a suggestion, where can I send it?
You can submit a suggestion from anywhere you want with `>>botsuggest`.