Include documentation

README.md

@@ -2,18 +2,27 @@
 
 A improved, modern version of ModMail for Transprogrammer
 
+> [!IMPORTANT]
+> 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.
+
 ## What is Rodhaj?
 
 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.
 
-Unlike ModMail, this bot is fine-tuned for the needs of the transprogrammer community.
+Unlike ModMail, this bot is fine-tuned for the needs of the transprogrammer community. As a result, **there is no public invite**.
+
+## How does it work?
 
-## Stuff that needs to be done
+The process is extremely similar to ModMail, but with major differences. When a member
+sends a direct message to the bot, Rodhaj will create a new ticket (which is a forum post)
+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.
 
-- [x] Paginators
-- [x] R. Danny migrations or asyncpg-trek
-- [ ] The features
+To ensure that staff will be able to respond, each active staff is randomly assigned
+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.
 
 ## Contributing
 
-See [contributing](./CONTRIBUTING.md)
+Contributions to Rodhaj are always welcomed. These could be as small as
+changing documentation to adding new features. If you are interested to start
+the process, please consult the [developer guide](CONTRIBUTING.md) before
+you get started.

docs/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+autobuild:
+	sphinx-autobuild . build/html

docs/conf.py

@@ -0,0 +1,38 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "rodhaj"
+copyright = "2023, Noelle"
+author = "No767"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx_copybutton"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_title = "Rodhaj"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]
+
+html_theme_options = {
+    "dark_css_variables": {
+        "color-brand-primary": "#b8c9ff",
+        "color-brand-content": "#b8c9ff",
+    },
+    "light_css_variables": {
+        "color-brand-primary": "#38a5ff",
+        "color-brand-content": "#38a5ff",
+    },
+}

docs/dev-guide/faq.rst

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

docs/dev-guide/index.rst

@@ -0,0 +1,11 @@
+================
+Developer Guide
+================
+
+Rodhaj offers a developer guide so future developers can easily get started with the project.
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   faq

docs/dev-guide/intro.rst

@@ -0,0 +1,94 @@
+============
+Introduction
+============
+
+This is the documentation for Rodhaj, the modern ModMail bot for the transprogrammer server.
+
+Software Requirements
+---------------------
+
+Before you get started, please ensure you have the following installed:
+
+- `Git <https://git-scm.com>`_
+- `Python 3 <https://python.org>`_
+- `Poetry <https://python-poetry.org>`_
+- `Docker <https://docker.com>`_
+- Discord Account + App 
+
+If you are using Linux, the following dependencies will need to be installed:
+
+- `libffi <https://github.com/libffi/libffi>`_
+- `libnacl <https://github.com/saltstack/libnacl>`_
+- `python3-dev <https://packages.debian.org/python3-dev>`_
+- `libssl <https://github.com/openssl/openssl>`_
+
+For a debian-based system, you can install them with the following command:
+
+.. code-block:: bash
+
+    $ apt install libffi-dev libnacl-dev python3-dev libssl-dev
+
+.. caution:: 
+    Rodhaj uses `uvloop <https://github.com/MagicStack/uvloop>`_ on Linux and MacOS
+    and `winloop <https://github.com/Vizonex/Winloop>`_ on Windows. Replacing the default event loop
+    with these Cython-based implementations provides a significant performance boost.
+    Although Rodhaj is natively developed and deployed on Linux,
+    Windows support should work but is not tested.
+
+Setup
+-----
+
+**Rodhaj only supports Python 3.9 or higher**
+
+.. important::
+    Ensure that you are in the root of the repo throughout this process
+
+1. Fork and clone the repo
+
+2. Install dependencies and set up pre-commits
+
+.. code-block:: bash
+
+    poetry install \
+    && poetry run pre-commit install
+
+3. Copy over the ``.env`` template over to the ``bot`` directory. Modify the values as appropriate.
+
+.. code-block:: bash
+
+    cp envs/dev.env bot/.env
+
+4. Run the SQL migrations
+
+.. code-block:: bash
+
+    poetry run python bot/migrations.py init
+
+5. In order to demonstrate, you can run the bot to test everything out
+
+.. code-block:: bash
+
+    poetry run python bot/launcher.py
+
+Database
+^^^^^^^^
+
+The following SQL queries can be used to create the user and database:
+
+.. code-block:: sql
+
+    CREATE ROLE rodhaj WITH LOGIN PASSWORD 'somepass';
+    CREATE DATABASE rodhaj OWNER rodhaj;
+
+.. note::
+
+    This step is largely skipped if you are using Docker to run
+    the PostgreSQL server. If you decide not to use Docker, you 
+    will need to manually create the database as shown below
+
+Basic Concepts
+--------------
+
+Rodhaj works by implementing commands, which
+are used staff. And Rodhaj takes care of assigning threads, creating tickets, etc.
+More will be provided in-depth in other parts of the documentation.

docs/index.rst

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

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx>=7.2.6
+sphinx-copybutton>=0.5.2
+sphinxext-opengraph>=0.8.2
+furo>=2023.9.10