From fca87bb073536e6802a2f4eed856fc4324b9156d Mon Sep 17 00:00:00 2001 From: No767 <73260931+No767@users.noreply.github.com> Date: Tue, 28 Nov 2023 19:06:36 -0800 Subject: [PATCH] Include documentation --- README.md | 21 ++++++--- docs/Makefile | 23 ++++++++++ docs/conf.py | 38 ++++++++++++++++ docs/dev-guide/faq.rst | 30 +++++++++++++ docs/dev-guide/index.rst | 11 +++++ docs/dev-guide/intro.rst | 94 ++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 37 ++++++++++++++++ docs/make.bat | 35 +++++++++++++++ docs/requirements.txt | 4 ++ 9 files changed, 287 insertions(+), 6 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/dev-guide/faq.rst create mode 100644 docs/dev-guide/index.rst create mode 100644 docs/dev-guide/intro.rst create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt diff --git a/README.md b/README.md index b02c4ab..95ba686 100644 --- a/README.md +++ b/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. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..021ffbf --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..3fb8c2b --- /dev/null +++ b/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", + }, +} diff --git a/docs/dev-guide/faq.rst b/docs/dev-guide/faq.rst new file mode 100644 index 0000000..eadde6f --- /dev/null +++ b/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 `_. +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 `_ for more. diff --git a/docs/dev-guide/index.rst b/docs/dev-guide/index.rst new file mode 100644 index 0000000..8be7cfe --- /dev/null +++ b/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 diff --git a/docs/dev-guide/intro.rst b/docs/dev-guide/intro.rst new file mode 100644 index 0000000..df67401 --- /dev/null +++ b/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 `_ +- `Python 3 `_ +- `Poetry `_ +- `Docker `_ +- Discord Account + App + +If you are using Linux, the following dependencies will need to be installed: + +- `libffi `_ +- `libnacl `_ +- `python3-dev `_ +- `libssl `_ + +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 `_ on Linux and MacOS + and `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. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..8e2ebd3 --- /dev/null +++ b/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 `_, +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. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..954237b --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..b40b029 --- /dev/null +++ b/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