From f8652a69b244e9113184e6821c00b7efd22faa6a Mon Sep 17 00:00:00 2001 From: Martin Date: Fri, 23 Feb 2024 20:39:07 +0100 Subject: [PATCH 1/6] Move Plugin Page Plugin page moved from old docs to usage folder --- plugins.md | 147 ---------------------------------------- usage-guide/plugins.md | 148 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 145 insertions(+), 150 deletions(-) delete mode 100644 plugins.md diff --git a/plugins.md b/plugins.md deleted file mode 100644 index 2251102..0000000 --- a/plugins.md +++ /dev/null @@ -1,147 +0,0 @@ -# Plugins - -## Plugins - -Visit the [Unofficial List of Plugins](https://github.com/modmail-dev/modmail/wiki/Unofficial-List-of-Plugins) for a list of plugins. - -## Guidelines - -To get approved and officially verified, you need to ensure you follow these guidelines: - -* Supporting Python 3.8 (and above). -* No malicious intent. -* The plugin cannot be a feature pending to be added into [Modmail](https://github.com/modmail-dev/modmail/issues). You can submit a PR to add it to the core Modmail. -* Core Modmail still needs to 100% function. -* Cog name cannot be the same as any current class (`Core`, `Modmail`). -* It cannot have the same name as another approved plugin. - -## Creating Plugins - -We use [discord.py](https://discordpy.readthedocs.io/en/stable/) for the bot and plugins take the form of [Cogs](https://discordpy.readthedocs.io/en/stable/ext/commands/cogs.html). - -Short example: - -```py -from discord.ext import commands - -class Hello(commands.Cog): - def __init__(self, bot): - self.bot = bot - - @commands.Cog.listener() - async def on_message(self, message): - print(message.content) - - @commands.command() - async def say(self, ctx, *, message): - await ctx.send(message) - -async def setup(bot): - await bot.add_cog(Hello(bot)) -``` - -### Folder Structure - -Your plugin has to be uploaded on Github on a **public repository.** (Note: private repositories are supported, but they require extra setup, see [Private Plugins](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)). The repository folder structure has to be as follows: - -```yaml -root: - plugin_name: - .. - plugin_name.py - requirements.txt [optional] - plugin_name: - .. - plugin_name.py - requirements.txt [optional] -``` - -The plugin will be loaded with something similar to - -```py -await bot.load_extension('username.plugin_name.plugin_name') -``` - -To install a plugin that is not in the official registry, type: - -``` -?plugin add githubusername/plugin_repo/plugin_name[@branch] -``` - -An example of a plugin can be seen at [`fourjr/modmail-plugins`](https://github.com/fourjr/modmail-plugins) or any of the plugins in our [registry](https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json). - -#### Branch parameter - -The branch parameter is **optional** (default to `master`) and can be used to test in-development/unstable plugins with a development branch. - -Users will always be updated to the latest version. Thus, if there is a broken plugin on the latest version, users would not be able to use the plugin. - -#### @local (For Developers) - -To make it easier to develop a plugin, there's a folder named `@local` in the plugins folder. You can directly put a folder for each plugin in it. - -Using the example cog above, the load command would be - -``` -?plugin load @local/hello -``` - -#### Best Practices - -1. Create a development branch -2. Push to it until you are confident that your code is stable -3. Merge it into `master` using pull requests or `git merge -v dev --squash` -4. Update your plugin! - -### Private Plugins - -* Obtain a [Github Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo` scope -* Include `GITHUB_TOKEN` as a config variable (or in .env) with the token as the value. -* Upload your code to a private Github repository. -* Install just like a normal public plugin. - -### Database Interfacing - -Do **not** interact with `bot.api` directly. Fetch a partition and use it: - -```python -def __init__(self, bot): # in the class init - self.coll = bot.api.get_plugin_partition(self) -``` - -`self.coll` is a [motor.motor\_asyncio.AsyncIOMotorCollection](https://motor.readthedocs.io/en/stable/api-asyncio/asyncio\_motor\_collection.html) - -### Additional PIP requirements - -Create a [`requirements.txt` file](https://pip.pypa.io/en/stable/user\_guide/#requirements-files) in the plugin folder. Packages listed here would be installed via something similar to the following command: - -``` -python3 -m pip install -r requirements.txt --user -q -q -``` - -### Exposed Events - -The bot dispatches custom events to aid plugin developers to extend Modmail functionality. - -Currently, we have these custom coroutines: - -* `Bot.format_channel_name(bot, author, exclude_channel=None, force_null=False)` can be overwritten for custom behaviour. -* `on_plugins_ready()` which is dispatched when all the plugins are fully loaded and ready to be used. -* `on_thread_initiate(thread, creator, category, initial_message)` which is dispatched at the beginning of setup process. It is recommended to use the other events instead. -* `on_thread_create(thread)` which is dispatched when the thread is registered as a thread by Modmail (i.e., when channel topic is edited). -* `on_thread_ready(thread, creator, category, initial_message)` which is dispatched when a thread channel is created and the `genesis_message` (info embed) is sent. It is recommended to use this event. -* `on_thread_close(thread, closer, silent, delete_channel, message, scheduled)` which is dispatched when a thread is closed, after channel deletion. -* `on_thread_reply(thread, from_mod, message, anonymous, plain)` which is dispatched upon any reply. - -e.g. - -```py -@commands.Cog.listener() -async def on_thread_ready(self, thread, creator, category, initial_message): - msg = thread.genesis_message - ... # do stuff -``` - -### Approval request - -Create a [Pull Request](https://github.com/modmail-dev/modmail/pulls) adding your plugin into [`plugins/registry.json`](https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json) and we will take a look at it. diff --git a/usage-guide/plugins.md b/usage-guide/plugins.md index d4e06b7..157e1cd 100644 --- a/usage-guide/plugins.md +++ b/usage-guide/plugins.md @@ -1,3 +1,145 @@ ---- -description: Installing and using plugins for extended functionality. ---- \ No newline at end of file +# Plugins + +Visit the [Unofficial List of Plugins](https://docs.modmail.dev/old-docs/the-unofficial-list-of-plugins) for a list of plugins. + +## Guidelines + +To get approved and officially verified, you need to ensure you follow these guidelines: + +* Supporting Python 3.8 (and above). +* No malicious intent. +* The plugin cannot be a feature pending to be added into [Modmail](https://github.com/modmail-dev/modmail/issues). You can submit a PR to add it to the core Modmail. +* Core Modmail still needs to 100% function. +* Cog name cannot be the same as any current class (`Core`, `Modmail`). +* It cannot have the same name as another approved plugin. + +## Creating Plugins + +We use [discord.py](https://discordpy.readthedocs.io/en/stable/) for the bot and plugins take the form of [Cogs](https://discordpy.readthedocs.io/en/stable/ext/commands/cogs.html). + +Short example: + +```py +from discord.ext import commands + +class Hello(commands.Cog): + def __init__(self, bot): + self.bot = bot + + @commands.Cog.listener() + async def on_message(self, message): + print(message.content) + + @commands.command() + async def say(self, ctx, *, message): + await ctx.send(message) + +async def setup(bot): + await bot.add_cog(Hello(bot)) +``` + +### Folder Structure + +Your plugin has to be uploaded on Github on a **public repository.** (Note: private repositories are supported, but they require extra setup, see [Private Plugins](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)). The repository folder structure has to be as follows: + +```yaml +root: + plugin_name: + .. + plugin_name.py + requirements.txt [optional] + plugin_name: + .. + plugin_name.py + requirements.txt [optional] +``` + +The plugin will be loaded with something similar to + +```py +await bot.load_extension('username.plugin_name.plugin_name') +``` + +To install a plugin that is not in the official registry, type: + +``` +?plugin add githubusername/plugin_repo/plugin_name[@branch] +``` + +An example of a plugin can be seen at [`fourjr/modmail-plugins`](https://github.com/fourjr/modmail-plugins) or any of the plugins in our [registry](https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json). + +#### Branch parameter + +The branch parameter is **optional** (default to `master`) and can be used to test in-development/unstable plugins with a development branch. + +Users will always be updated to the latest version. Thus, if there is a broken plugin on the latest version, users would not be able to use the plugin. + +#### @local (For Developers) + +To make it easier to develop a plugin, there's a folder named `@local` in the plugins folder. You can directly put a folder for each plugin in it. + +Using the example cog above, the load command would be + +``` +?plugin load @local/hello +``` + +#### Best Practices + +1. Create a development branch +2. Push to it until you are confident that your code is stable +3. Merge it into `master` using pull requests or `git merge -v dev --squash` +4. Update your plugin! + +### Private Plugins + +* Obtain a [Github Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo` scope +* Include `GITHUB_TOKEN` as a config variable (or in .env) with the token as the value. +* Upload your code to a private Github repository. +* Install just like a normal public plugin. + +### Database Interfacing + +Do **not** interact with `bot.api` directly. Fetch a partition and use it: + +```python +def __init__(self, bot): # in the class init + self.coll = bot.api.get_plugin_partition(self) +``` + +`self.coll` is a [motor.motor\_asyncio.AsyncIOMotorCollection](https://motor.readthedocs.io/en/stable/api-asyncio/asyncio\_motor\_collection.html) + +### Additional PIP requirements + +Create a [`requirements.txt` file](https://pip.pypa.io/en/stable/user\_guide/#requirements-files) in the plugin folder. Packages listed here would be installed via something similar to the following command: + +``` +python3 -m pip install -r requirements.txt --user -q -q +``` + +### Exposed Events + +The bot dispatches custom events to aid plugin developers to extend Modmail functionality. + +Currently, we have these custom coroutines: + +* `Bot.format_channel_name(bot, author, exclude_channel=None, force_null=False)` can be overwritten for custom behaviour. +* `on_plugins_ready()` which is dispatched when all the plugins are fully loaded and ready to be used. +* `on_thread_initiate(thread, creator, category, initial_message)` which is dispatched at the beginning of setup process. It is recommended to use the other events instead. +* `on_thread_create(thread)` which is dispatched when the thread is registered as a thread by Modmail (i.e., when channel topic is edited). +* `on_thread_ready(thread, creator, category, initial_message)` which is dispatched when a thread channel is created and the `genesis_message` (info embed) is sent. It is recommended to use this event. +* `on_thread_close(thread, closer, silent, delete_channel, message, scheduled)` which is dispatched when a thread is closed, after channel deletion. +* `on_thread_reply(thread, from_mod, message, anonymous, plain)` which is dispatched upon any reply. + +e.g. + +```py +@commands.Cog.listener() +async def on_thread_ready(self, thread, creator, category, initial_message): + msg = thread.genesis_message + ... # do stuff +``` + +### Approval request + +Create a [Pull Request](https://github.com/modmail-dev/modmail/pulls) adding your plugin into [`plugins/registry.json`](https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json) and we will take a look at it. From 1bed27f32e1d9f52ec671745b8fa2dd64b37c9a0 Mon Sep 17 00:00:00 2001 From: Martin Bndr Date: Sun, 25 Feb 2024 11:28:36 +0000 Subject: [PATCH 2/6] GITBOOK-1: No subject --- SUMMARY.md | 1 - 1 file changed, 1 deletion(-) diff --git a/SUMMARY.md b/SUMMARY.md index f31376f..6599d1b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -32,7 +32,6 @@ * [Frequently Asked Questions]() * [Modmail Usage](modmail-usage.md) * [Permissions](permissions.md) - * [Plugins](plugins.md) * [Seperate Server Setup](seperate-server-setup.md) * [The Unofficial List of Plugins](the-unofficial-list-of-plugins.md) * [Updating]() From fe8c5bacc9b23322755ca8d07b6218aa3e3f4009 Mon Sep 17 00:00:00 2001 From: Martin Date: Sun, 25 Feb 2024 13:01:55 +0100 Subject: [PATCH 3/6] Remove unofficial plugins Removes the unofficial plugin list, also modifies the plugin page accordingly --- SUMMARY.md | 1 - the-unofficial-list-of-plugins.md | 52 ------------------------------- usage-guide/plugins.md | 3 +- 3 files changed, 2 insertions(+), 54 deletions(-) delete mode 100644 the-unofficial-list-of-plugins.md diff --git a/SUMMARY.md b/SUMMARY.md index 6599d1b..6ceb83d 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -33,6 +33,5 @@ * [Modmail Usage](modmail-usage.md) * [Permissions](permissions.md) * [Seperate Server Setup](seperate-server-setup.md) - * [The Unofficial List of Plugins](the-unofficial-list-of-plugins.md) * [Updating]() * [Video Tutorials](video-tutorials.md) diff --git a/the-unofficial-list-of-plugins.md b/the-unofficial-list-of-plugins.md deleted file mode 100644 index 1700993..0000000 --- a/the-unofficial-list-of-plugins.md +++ /dev/null @@ -1,52 +0,0 @@ -# The Unofficial List of Plugins - -To add any of the plugins listed below, do `?plugins add plugin-name`, where `plugin-name` is the name of the plugin. - -* **Taki**: - * [`colors`](https://github.com/Taaku18/modmail-plugins/tree/master/colors) - * [`Taaku18/modmail-plugins/bettercalc`](https://github.com/Taaku18/modmail-plugins/tree/master/bettercalc) (BETA) - * [`Taaku18/modmail-plugins/animals`](https://github.com/Taaku18/modmail-plugins/tree/master/animals) -* **Akhil**: - * [`fun`](https://github.com/TheKinG2149/modmail-plugins/tree/master/fun) -* **MiTonder**: - * [`stats`](https://github.com/MiTonder/modmail-plugins/tree/master/stats) -* **DAzVise**: - * [`serverstats`](https://github.com/DAzVise/modmail-plugins/tree/master/serverstats) - * [`DAzVise/modmail-plugins/reports`](https://github.com/DAzVise/modmail-plugins/tree/master/reports) - * [`DAzVise/modmail-plugins/reaction-role`](https://github.com/DAzVise/modmail-plugins/tree/master/reaction-role) - * [`DAzVise/modmail-plugins/role`](https://github.com/DAzVise/modmail-plugins/tree/master/role) -* **SnailDOS**: - * [`snaildos/modmail-plugins/sudo`](https://github.com/snaildos/modmail-plugins/tree/master/sudo) -* **RealCyGuy**: - * [`realcyguy/modmail-plugins/8ball`](https://github.com/RealCyGuy/modmail-plugins/tree/master/8ball) -* **mischievousdev**: - * [`githubstats`](https://github.com/mischievousdev/modmail-plugins/tree/master/githubstats) -* **xTeen**: - * [`Teen1/Modmail-Plugins/helloplugin`](https://github.com/Teen1/Modmail-Plugins/tree/master/helloplugin) - * [`Teen1/Modmail-Plugins/nitroboost`](https://github.com/Teen1/Modmail-Plugins/tree/master/nitroboost) - * [`slowmode`](https://github.com/Teen1/Modmail-Plugins/tree/master/slowmode) -* **Jerrie**: - * [`Jerrie-Aries/modmail-plugins/trivia`](https://github.com/Jerrie-Aries/modmail-plugins/tree/master/trivia) - * [`Jerrie-Aries/modmail-plugins/embedmanager`](https://github.com/Jerrie-Aries/modmail-plugins/tree/master/embedmanager) - * [`Jerrie-Aries/modmail-plugins/rolemanager`](https://github.com/Jerrie-Aries/modmail-plugins/tree/master/rolemanager) -* **Nziie**: - * [`Nzii3/modmail-plugins/raw-content`](https://github.com/Nzii3/modmail-plugins/tree/main/raw-content) - -*** - -**Beware**, this is a community project, all plugins listed above may or may not be safe, only add plugins from developers you trust! - -*** - -> Plugin developers, feel free to add your plugins on this page. -> -> Format: -> -> ``` -> - **Your Name**: -> - [`plugin-name#1`](link to GitHub directory of the first plugin) -> - [`plugin-name#2`](link to GitHub directory of the second plugin) -> - ... -> ``` -> -> `plugin-name` is the approved name of the plugin as appeared in the registry for approved plugins or in the format of `username/repo/plugin-name` for not-yet approved plugins. diff --git a/usage-guide/plugins.md b/usage-guide/plugins.md index 157e1cd..a110a7f 100644 --- a/usage-guide/plugins.md +++ b/usage-guide/plugins.md @@ -1,6 +1,7 @@ # Plugins -Visit the [Unofficial List of Plugins](https://docs.modmail.dev/old-docs/the-unofficial-list-of-plugins) for a list of plugins. +Plugins can add additional functionality into the modmail bot. +You can view a list of approved plugins via the ``?plugins registry`` command or take a look at the [`plugins/registry.json`](https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json). ## Guidelines From efa71f5a6ff10b4984f5b409d47a0b916e3a132a Mon Sep 17 00:00:00 2001 From: Martin Date: Sun, 25 Feb 2024 13:19:13 +0100 Subject: [PATCH 4/6] Move Seperate Server to FAQ Moves seperate server page from old docs to the frequently asked questions --- SUMMARY.md | 1 - frequently-asked-questions.md | 7 ++++++- seperate-server-setup.md | 6 ------ 3 files changed, 6 insertions(+), 8 deletions(-) delete mode 100644 seperate-server-setup.md diff --git a/SUMMARY.md b/SUMMARY.md index 6ceb83d..75b1fb4 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -32,6 +32,5 @@ * [Frequently Asked Questions]() * [Modmail Usage](modmail-usage.md) * [Permissions](permissions.md) - * [Seperate Server Setup](seperate-server-setup.md) * [Updating]() * [Video Tutorials](video-tutorials.md) diff --git a/frequently-asked-questions.md b/frequently-asked-questions.md index a832ca8..5c776c9 100644 --- a/frequently-asked-questions.md +++ b/frequently-asked-questions.md @@ -24,4 +24,9 @@ And then, fetch the original files with: git checkout FETCH_HEAD -- Pipfile && git checkout FETCH_HEAD -- Pipfile.lock ``` -### +### I would like to have threads in a seperate guild inbox, how can I do that? + +If you want to use a separate server to the main one as the inbox server (Where threads get relayed to) add the following environment variables into your ``.env`` file: + +* `MODMAIL_GUILD_ID` (the server where messages are sent to) +* `GUILD_ID` (The server where users message from) diff --git a/seperate-server-setup.md b/seperate-server-setup.md deleted file mode 100644 index f30609a..0000000 --- a/seperate-server-setup.md +++ /dev/null @@ -1,6 +0,0 @@ -# Seperate Server Setup - -If you want to use a separate server to the main one as the inbox server (Where threads get relayed to) add the following config variables on Heroku: - -* `MODMAIL_GUILD_ID` (the server where messages are sent to) -* `GUILD_ID` (The server where users message from) From 7b7c5dd478c258a0537447a3701a809731672789 Mon Sep 17 00:00:00 2001 From: Martin Date: Sun, 25 Feb 2024 13:31:23 +0100 Subject: [PATCH 5/6] Update Railway Railway is no longer free, so updating that info. --- installation/railway.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/installation/railway.md b/installation/railway.md index df5543c..5ece4e7 100644 --- a/installation/railway.md +++ b/installation/railway.md @@ -10,18 +10,15 @@ Railway is a deployment platform where you can provision infrastructure, develop ## Requirements -* A credit card (for verification only). +* A credit card. * An email account. * A [GitHub](https://github.com/signup) account. * You have completed the initial steps: [invited your bot](./#create-a-discord-bot) and [created a MongoDB database](./#create-a-mongodb-database). ## Costs -Railway provides a **free** "Starter" plan. This plan allows you to try out their platform for free without requiring a credit card\*. Your bot will be online for 10 days after signing up. - -To keep your bot running 24/7, you'll need to sign up for their "Developer" plan. This plan is also **free**, but you will need to verify using your credit card, as it's to prevent abuse on their systems. - -\*Credit card may be required for some users. +Railway is no longer free. Their lowest plan starts at $5 per month. +Visit the [pricing](https://railway.app/pricing) page for the up-to-date pricing info. ## Fork our GitHub repositories From b7e2c009d728a8cb3536fadcc70e9a2b34a7f05a Mon Sep 17 00:00:00 2001 From: Martin Date: Sun, 25 Feb 2024 20:46:59 +0100 Subject: [PATCH 6/6] Update community-guides.md Changed invalid northflank link and updated replit info as its no longer free. --- installation/community-guides.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/installation/community-guides.md b/installation/community-guides.md index 64ce8f4..454d2f4 100644 --- a/installation/community-guides.md +++ b/installation/community-guides.md @@ -5,13 +5,12 @@ description: Unofficial installation guides created by the community. # Community Guides {% hint style="warning" %} -Community guides are not verified by the Modmail team, so use them at your own risks. -{% endhint %} +Community guides are not verified by the Modmail team, so use them at your own risks.{% endhint %} ## [Replit Guide](https://gist.github.com/anondev-sudo/24978429b85b44348bcff5c0885afe82) by AnonDev -An online code execution environment. You can host Modmail there for free using certain exploits. The legitimate method costs $7 USD per month. However, regardless if you pay or host for free, hosting on Replit are often unstable and thus not recommended. But for now, this is the only option for those without a payment method for hosting or verification. +An online code execution environment which used to be free with certain exploids but starting 2024 replit removed the free tier. You can deploy modmail there if you pay for their monthly plans/deployment costs. For the up-to--date pricing info check out their [pricing](https://replit.com/pricing) page. -## [Northflank](https://blog.project-mei.xyz/2023/04/11/hosting-discord-modmail-on-northflank/) Guide by raidensakura +## [Northflank](https://blog.project-mei.xyz/posts/2023-08-02-hosting-modmail-on-northflank.html) Guide by raidensakura -Northflank is a Platform as a Service (PaaS) like Railway that offers abilities to run micro-services like bots, schedule jobs that run periodically and databases with a powerful UI, API and CLI. Their panel is a bit more advanced as compared to Railway but comes with the perk of more customization and features. You will need a valid payment method to verify your account, but will unlock a free tier project that's separated from paid resources. They will not charge your card if you go over resource usage as you have limited allocation per service. +Northflank is a Platform as a Service (PaaS) like Railway that offers abilities to run micro-services like bots, schedule jobs that run periodically and databases with a powerful UI, API and CLI. Their panel is a bit more advanced as compared to Railway but comes with the perk of more customization and features. You will need a valid payment method to verify your account, but will unlock a free tier project that's separated from paid resources. They will not charge your card if you go over resource usage as you have limited allocation per service. \ No newline at end of file