Skip to content

Commit fca87bb

Browse files
No767No767
committed
Include documentation
1 parent b9340cf commit fca87bb

File tree

9 files changed

+287
-6
lines changed

9 files changed

+287
-6
lines changed

‎README.md

+15-6
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,27 @@
22

33
A improved, modern version of ModMail for Transprogrammer
44

5+
> [!IMPORTANT]
6+
> We would prefer if you do not run instances of Rodhaj (included self-hosted ones). The source code is provided as-is and is for educational and development purposes only.
7+
58
## What is Rodhaj?
69

710
Just like ModMail, Rodhaj serves to be the transprogrammer's official ModMail bot. By creating a shared inbox, it allows for users and staff to seamlessly communicate safely, securely, and privately.
811

9-
Unlike ModMail, this bot is fine-tuned for the needs of the transprogrammer community.
12+
Unlike ModMail, this bot is fine-tuned for the needs of the transprogrammer community. As a result, **there is no public invite**.
13+
14+
## How does it work?
1015

11-
## Stuff that needs to be done
16+
The process is extremely similar to ModMail, but with major differences. When a member
17+
sends a direct message to the bot, Rodhaj will create a new ticket (which is a forum post)
18+
internally for staff to view. From there, each ticket is tied with a member and DMs from Rodhaj will be processed and sent to their respective tickets.
1219

13-
- [x] Paginators
14-
- [x] R. Danny migrations or asyncpg-trek
15-
- [ ] The features
20+
To ensure that staff will be able to respond, each active staff is randomly assigned
21+
to a particular ticket. This ensures that tickets are evenly distributed among staff. Staff are free to swap and work on multiple tickets as needed. Once a ticket is closed, the staff will be automatically unassigned from the ticket, and a new DM to Rodhaj will prompt the user to create a new ticket.
1622

1723
## Contributing
1824

19-
See [contributing](./CONTRIBUTING.md)
25+
Contributions to Rodhaj are always welcomed. These could be as small as
26+
changing documentation to adding new features. If you are interested to start
27+
the process, please consult the [developer guide](CONTRIBUTING.md) before
28+
you get started.

‎docs/Makefile

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21+
22+
autobuild:
23+
sphinx-autobuild . build/html

‎docs/conf.py

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = "rodhaj"
10+
copyright = "2023, Noelle"
11+
author = "No767"
12+
13+
# -- General configuration ---------------------------------------------------
14+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
15+
16+
extensions = ["sphinx_copybutton"]
17+
18+
templates_path = ["_templates"]
19+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
20+
21+
html_title = "Rodhaj"
22+
23+
# -- Options for HTML output -------------------------------------------------
24+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
25+
26+
html_theme = "furo"
27+
html_static_path = ["_static"]
28+
29+
html_theme_options = {
30+
"dark_css_variables": {
31+
"color-brand-primary": "#b8c9ff",
32+
"color-brand-content": "#b8c9ff",
33+
},
34+
"light_css_variables": {
35+
"color-brand-primary": "#38a5ff",
36+
"color-brand-content": "#38a5ff",
37+
},
38+
}

‎docs/dev-guide/faq.rst

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
FAQ
2+
---
3+
4+
This is a list of frequently asked questions.
5+
If you have a question that is not answered here,
6+
feel free to submit one via pull requests or to suggest one.
7+
8+
Slash Commands
9+
==============
10+
11+
Questions regarding slash commands and how they operate in ``discord.py``.
12+
13+
Where are the slash commands?
14+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15+
16+
Unlike other frameworks, discord.py **does not** automatically sync slash commands
17+
for you (as slash commands need to be synced to Discord and are handled by them).
18+
As a result, you'll need to manually sync your commands using the included
19+
`sync command <https://about.abstractumbra.dev/discord.py/2023/01/29/sync-command-example.html>`_.
20+
It is strongly recommended you read what the different options the command offers.
21+
22+
For example, in order to sync your commands, you would run a command in your Discord client
23+
such as the following:
24+
25+
.. code-block::
26+
27+
r>sync
28+
29+
To see details information on why the practice of automatically syncing commands is bad,
30+
see `this gist <https://gist.github.com/No767/e65fbfdedc387457b88723595186000f>`_ for more.

‎docs/dev-guide/index.rst

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
================
2+
Developer Guide
3+
================
4+
5+
Rodhaj offers a developer guide so future developers can easily get started with the project.
6+
7+
.. toctree::
8+
:maxdepth: 2
9+
10+
intro
11+
faq

‎docs/dev-guide/intro.rst

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
============
2+
Introduction
3+
============
4+
5+
This is the documentation for Rodhaj, the modern ModMail bot for the transprogrammer server.
6+
7+
Software Requirements
8+
---------------------
9+
10+
Before you get started, please ensure you have the following installed:
11+
12+
- `Git <https://git-scm.com>`_
13+
- `Python 3 <https://python.org>`_
14+
- `Poetry <https://python-poetry.org>`_
15+
- `Docker <https://docker.com>`_
16+
- Discord Account + App
17+
18+
If you are using Linux, the following dependencies will need to be installed:
19+
20+
- `libffi <https://github.com/libffi/libffi>`_
21+
- `libnacl <https://github.com/saltstack/libnacl>`_
22+
- `python3-dev <https://packages.debian.org/python3-dev>`_
23+
- `libssl <https://github.com/openssl/openssl>`_
24+
25+
For a debian-based system, you can install them with the following command:
26+
27+
.. code-block:: bash
28+
29+
$ apt install libffi-dev libnacl-dev python3-dev libssl-dev
30+
31+
.. caution::
32+
Rodhaj uses `uvloop <https://github.com/MagicStack/uvloop>`_ on Linux and MacOS
33+
and `winloop <https://github.com/Vizonex/Winloop>`_ on Windows. Replacing the default event loop
34+
with these Cython-based implementations provides a significant performance boost.
35+
Although Rodhaj is natively developed and deployed on Linux,
36+
Windows support should work but is not tested.
37+
38+
Setup
39+
-----
40+
41+
**Rodhaj only supports Python 3.9 or higher**
42+
43+
.. important::
44+
Ensure that you are in the root of the repo throughout this process
45+
46+
1. Fork and clone the repo
47+
48+
2. Install dependencies and set up pre-commits
49+
50+
.. code-block:: bash
51+
52+
poetry install \
53+
&& poetry run pre-commit install
54+
55+
3. Copy over the ``.env`` template over to the ``bot`` directory. Modify the values as appropriate.
56+
57+
.. code-block:: bash
58+
59+
cp envs/dev.env bot/.env
60+
61+
4. Run the SQL migrations
62+
63+
.. code-block:: bash
64+
65+
poetry run python bot/migrations.py init
66+
67+
5. In order to demonstrate, you can run the bot to test everything out
68+
69+
.. code-block:: bash
70+
71+
poetry run python bot/launcher.py
72+
73+
Database
74+
^^^^^^^^
75+
76+
The following SQL queries can be used to create the user and database:
77+
78+
.. code-block:: sql
79+
80+
CREATE ROLE rodhaj WITH LOGIN PASSWORD 'somepass';
81+
CREATE DATABASE rodhaj OWNER rodhaj;
82+
83+
.. note::
84+
85+
This step is largely skipped if you are using Docker to run
86+
the PostgreSQL server. If you decide not to use Docker, you
87+
will need to manually create the database as shown below
88+
89+
Basic Concepts
90+
--------------
91+
92+
Rodhaj works by implementing commands, which
93+
are used staff. And Rodhaj takes care of assigning threads, creating tickets, etc.
94+
More will be provided in-depth in other parts of the documentation.

‎docs/index.rst

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
.. rodhaj documentation master file, created by
2+
sphinx-quickstart on Wed Nov 22 16:14:24 2023.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Rodhaj
7+
==================================
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
:hidden:
12+
:caption: Guides
13+
14+
dev-guide/index
15+
16+
A improved, modern version of ModMail for the Transprogrammer community.
17+
18+
Rodhaj is a ModMail bot similar to `ModMail <https://github.com/modmail-dev/modmail>`_,
19+
but with a completely new, improved codebase and features. It works just like Reddit's Modmail,
20+
where users can send messages to the bot and the bot will relay it to the server's staff team. This allows
21+
for a process of communicating from user to staff to be streamlined, and securely done.
22+
23+
24+
What's Different?
25+
-----------------
26+
27+
The major difference with Rodhaj is that tickets are handled through Discord's new Forum channels.
28+
Along with other changes, such as using PostgreSQL over MongoDB, Rodhaj takes the same concepts as ModMail
29+
and improves on them.
30+
31+
Unlike ModMail, this bot is fine-tuned for the needs of the Transprogrammer community.
32+
Thus, **this bot has no invite**.
33+
34+
Contributing
35+
------------
36+
37+
If you would like to contribute to Rodhaj, please read the guides below.

‎docs/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/requirements.txt

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
sphinx>=7.2.6
2+
sphinx-copybutton>=0.5.2
3+
sphinxext-opengraph>=0.8.2
4+
furo>=2023.9.10

0 commit comments

Comments
 (0)