Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
raidensakura committed Apr 18, 2024
1 parent 218052a commit 320951b
Show file tree
Hide file tree
Showing 9 changed files with 70 additions and 83 deletions.
6 changes: 1 addition & 5 deletions docs/pages/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,8 @@
"getting-started": "Getting started",
"installation": "Installing Modmail",
"logviewer-installation": "Installing Logviewer",
"configuration": "Configuring Modmail",
"updating": "Updating Modmail",
"configuring": {
"title": "Configuring Modmail",
"href": "https://docs.modmail.dev/usage-guide/configuration",
"newWindow": true
},
"contact": {
"title": "Discord ↗",
"type": "page",
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/community-guides.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { Card, Cards } from 'nextra-theme-docs'
# Community Guides

<Callout emoji="ℹ️" type="info">
Community guides are not verified by the Modmail team, so use them at your own risks.
Community guides are not official, the official support team will not be answering any question regarding these methods.
</Callout>

### Hosting on [Northflank](https://northflank.com/)
Expand Down
17 changes: 17 additions & 0 deletions docs/pages/configuration.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
description: Keeping your Modmail up to date
title: Updating Modmail
---

import { Callout } from 'nextra-theme-docs'
import Image from 'next/image'
import { Steps } from 'nextra-theme-docs'
import { Card, Cards } from 'nextra-theme-docs'
import Link from 'next/link'

# Base Configuration

This forked version of Modmail also inherits all of the base configuration of the original project.
See all of the variable listing on the official project [Documentation](https://docs.modmail.dev/usage-guide/configuration).

Additionally, you can also use `[p]config help` to see a list of all the variables and `[p]config help` to see the details of individual config.
15 changes: 1 addition & 14 deletions docs/pages/installation/docker.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,7 @@ import { Steps } from 'nextra-theme-docs'
import { Card, Cards } from 'nextra-theme-docs'
import Link from 'next/link'

# Installing Modmail on Docker

<Callout emoji="ℹ️" type="info">
Docker is considered an advanced setup, it is recommended that you understand how Docker works before deciding to use this method.
</Callout>

<Image src="/docker-illust.png" alt="Hello" width={700} height={500} />
<sub>A simple illustration explaining how Docker works</sub>

## Prerequisites

* Supported OS for Docker
* Docker Engine
* Docker Compose
# Running Modmail on Docker

## Installing Docker Engine

Expand Down
2 changes: 1 addition & 1 deletion docs/pages/installation/ubuntu.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import Image from 'next/image'
1. Root access (**`sudo`**), **not** `root` user.
2. Minimum 1 GB of RAM
3. At least 2 GB available disk space.
4. Supported releases:
4. Tested releases:
* Ubuntu 22.04 LTS (Jammy Jellyfish)

## Dependencies
Expand Down
11 changes: 0 additions & 11 deletions docs/pages/logviewer-installation/plugin.md

This file was deleted.

13 changes: 13 additions & 0 deletions docs/pages/logviewer-installation/plugin.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import { Callout } from 'nextra-theme-docs'
import Image from 'next/image'

# Installing Logviewer

**The only recommended way** to run Logviewer on this fork is by using the plugin. The original [Logviewer](https://github.com/modmail-dev/logviewer)
application is unmaintained, has an unreported vulnerability and is a hassle to set up.

Simply install and load the plugin by running the command on your bot below (`[p]` is your prefix)

```js
[p]plugin load logviewer
```
54 changes: 34 additions & 20 deletions docs/pages/plugins.mdx
Original file line number Diff line number Diff line change
@@ -1,20 +1,25 @@
---
title: Plugins Documentation
title: Plugin documentation for developer
---
# Plugins Documentation

Visit the [Unofficial List of Plugins](https://github.com/kyb3r/modmail/wiki/Unofficial-List-of-Plugins) for a list of plugins.
import { Callout } from 'nextra-theme-docs'
import Image from 'next/image'
import { Steps } from 'nextra-theme-docs'
import { Card, Cards } from 'nextra-theme-docs'
import Link from 'next/link'

# Guidelines
To get approved and officially verified, you need to ensure you follow these guidelines:
- Supporting Python 3.9 (and above).
- No malicious intent.
- The plugin cannot be a feature pending to be added into [Modmail](https://github.com/kyb3r/modmail/issues). You can submit a PR to add it to the core Modmail.
- Core Modmail still needs to 100% function.
# Plugin Documentation

This forked version of Modmail maintains its own list of community-made plugins. Run `[p]plugin registry` command on your bot to see
a list of submitted plugins available.

## General plugin creation guideline
- Support Python 3.10 (and above).
- Plugin must adhere to (Discord's Terms of Service)[https://discord.com/terms/].
- Cog name cannot be the same as any current class (`Core`, `Modmail`).
- It cannot have the same name as another approved plugin.

# Creating Plugins
## 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:
Expand All @@ -37,8 +42,15 @@ 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:
### Folder Structure
Your plugin has to be uploaded on Github on a **public repository.**

<Callout emoji="ℹ️" type="info">
private repositories are supported, but they require extra setup, see
[Private Plugins](#private-plugins)
</Callout>

The repository folder structure has to be as follows:
```yaml
root:
plugin_name:
Expand All @@ -61,25 +73,25 @@ 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/kyb3r/modmail/blob/master/plugins/registry.json).
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/raidensakura/modmail/blob/stable/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.
The branch parameter is **optional** (default to `main`) 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.
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)
### @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
## 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 `
3. Merge it into the main branch using pull requests or `git merge -v dev --squash `
4. Update your plugin!

## Private Plugins
Expand Down Expand Up @@ -126,5 +138,7 @@ async def on_thread_ready(self, thread, creator, category, initial_message):
```


## Approval request
Create a [Pull Request](https://github.com/kyb3r/modmail/pulls) adding your plugin into [`plugins/registry.json`](https://github.com/kyb3r/modmail/blob/master/plugins/registry.json) and we will take a look at it.
## Adding your plugin
Create a [Pull Request](https://github.com/raidensakura/modmail/pulls) into the stable branch,
adding your plugin into [`REGISTRY.json`](https://github.com/raidensakura/modmail/blob/stable/REGISTRY.json)
following the correct JSON format.
33 changes: 2 additions & 31 deletions docs/pages/updating.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,35 +5,6 @@ title: Updating Modmail

import Image from 'next/image'

# Updating
# Updating Modmail

Your Modmail is set to auto-update itself by default, but you can also run the `?update` command on your bot manually, replacing `?` with your bot prefix.

If for some reason your update command isn't working correctly, you can update your bot by going into your Modmail folder and pulling the latest changes from GitHub with the steps below.

First, determine whether you have the official Modmail repository cloned or a fork by observing the output of the command below:

```
cat .git/config
```

If the output shows this exact URL as shown below,

```
[remote "origin"]
url = https://github.com/modmail-dev/modmail.git
```

you can go ahead and run the command below to pull in the latest changes:

```bash
git pull
```

Else, it means that your repository is a fork and must update (aka sync) it independently. If your repository is hosted on GitHub, click on the button on your repo's GitHub URL as highlighted below:

<Image src="/updating.png" alt="Hello" width={900} height={500} />

Run the `git pull` command above locally after syncing your fork.

And then, be sure to restart your bot to apply the update.
Your Modmail is set to auto-update itself periodically by default, but you can also run the `[p]update` command on your bot manually, replacing `[p]` with your bot prefix.

0 comments on commit 320951b

Please sign in to comment.