Rewrite documentation (#224)

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build
 
 # PyBuilder
 .pybuilder/

.readthedocs.yaml

@@ -3,10 +3,13 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
+  commands:
+    - python -m sphinx -aEnTW --builder html --keep-going docs/ $READTHEDOCS_OUTPUT/html
 
 sphinx:
    configuration: docs/source/conf.py
+   fail_on_warning: true
 
 python:
    install:

changelog.md

@@ -12,7 +12,12 @@
 - New requirements.txt for dependencies (https://github.com/No767/Catherine-Chan/pull/173)
 - Fixed pygit2 deprecations (https://github.com/No767/Catherine-Chan/pull/176)
 - Fixed inaccurate member counts with Prometheus (https://github.com/No767/Catherine-Chan/pull/181)
-- General codebase maintenance (https://github.com/No767/Catherine-Chan/pull/204)
+- General codebase maintenance (https://github.com/No767/Catherine-Chan/pull/204, https://github.com/No767/Catherine-Chan/pull/223)
+- Migrated to Lefthook and optimized pre-commit hooks (https://github.com/No767/Catherine-Chan/pull/218)
+- Use JSON decoder provided by msgspec (https://github.com/No767/Catherine-Chan/pull/222)
+- Use proper type checking imports (https://github.com/No767/Catherine-Chan/pull/216)
+- Fix exception violations with pronouns tester (https://github.com/No767/Catherine-Chan/pull/212)
+- Migrate from Bandit, Black, Autoflake and Isort to Ruff (https://github.com/No767/Catherine-Chan/pull/218, https://github.com/No767/Catherine-Chan/pull/223)
 
 ## ✨ Additions
 
@@ -27,8 +32,10 @@
   - HRT Conversion (https://github.com/No767/Catherine-Chan/pull/200)
   - Pronouns (https://github.com/No767/Catherine-Chan/pull/207)
   - Dictionary (https://github.com/No767/Catherine-Chan/pull/221)
+  - Documentation (https://github.com/No767/Catherine-Chan/pull/224)
 - Include Taskfile (https://github.com/No767/Catherine-Chan/pull/208)
 
 ## ➖ Removals
 
 - Tonetags (https://github.com/No767/Catherine-Chan/pull/183)
+- pre-commit (https://github.com/No767/Catherine-Chan/pull/218)

docs/Makefile

@@ -20,4 +20,4 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 autobuild:
-	sphinx-autobuild source build/html
+	sphinx-autobuild . build/html

docs/source/conf.py → docs/conf.py

@@ -7,7 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "Catherine-Chan"
-copyright = "2023, No767"
+copyright = "2024, No767"
 author = "No767"
 
 # -- General configuration ---------------------------------------------------
@@ -16,7 +16,7 @@
 extensions = ["sphinxext.opengraph", "sphinx_copybutton"]
 
 templates_path = ["_templates"]
-exclude_patterns = []
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 latex_elements = {
     "sphinxsetup": "verbatimwithframe=false",

docs/dev-intro.rst

@@ -0,0 +1,182 @@
+============
+Introduction
+============
+
+Catherine-Chan is internally built with discord.py. 
+This document introduces relevant concepts and instructions for this project.
+
+Prerequisites
+-------------
+
+There are some tools that you would need to have installed before you continue. 
+They are listed below:
+
+- `Git <https://git-scm.com>`_
+- `Python 3 <https://python.org>`_
+- `Docker <https://docker.com>`_
+- `Task <https://taskfile.dev>`_
+- 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
+
+.. note::
+    Catherine-Chan replaces the default event loop with `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 libraries is how Catherine-Chan is able to be extremely performant.
+    Although Catherine-Chan is natively developed for Linux and MacOS, Windows support has not been tested.
+
+Setup
+-----
+
+.. important::
+
+  Ensure that you are in the root of the repo throughout this process and have the database running
+
+Step 1 - Clone the repo
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to work on the project at all, you will need to fork and clone the repo
+
+.. code-block:: bash
+
+    git clone https://github.com/SomeUser/Catherine-Chan
+
+Step 2 - Create a virtualenv
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is best to make a virtualenv to install all dependencies on their first.
+
+.. code-block:: bash
+
+    python3 -m venv catherine-chan
+
+Step 3 - Activate the virtualenv
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+    # Linux/MacOS
+    source catherine-chan/bin/activate
+
+    # Windows
+    catherine-chan/Scripts/activate.bat
+
+Step 4 - Install dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We are going to be installing all of the development dependencies needed.
+This includes `Lefthook <https://github.com/evilmartians/lefthook>`_, which is the Git hooks manager.
+
+.. code-block:: bash
+
+   pip install -r requirements-dev.txt \
+   && lefthook install
+
+Step 5 - Copying configuration templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Catherine-Chan is configured by using a YAML configuration, which a template of it is included in the repo. 
+We need to copy it over and modify the values as needed.
+
+.. code-block:: bash
+
+    cp config-example.yml bot/config.yml
+
+Step 6 - Run the SQL migrations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Catherine-Chan includes an custom SQL migrations system that has been battle-tested, so that's what we need to set up. 
+If this step doesn't work, just skip it for now.
+
+.. code-block:: bash
+
+    python3 bot/migrations.py init
+
+Step 7 - Running Catherine-Chan
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to demonstrate, we are going to run our bot. The following command executes this.
+
+.. code-block:: bash
+
+    python bot/catherinebot.py
+
+
+Once done, set up your testing server, invite your development bot, and verify that it works.
+
+.. tip:: 
+
+    If you have Task installed, you can use ``task bot`` as a shortcut.
+
+Database
+--------
+
+The database used is PostgreSQL. By default, a Docker Compose file is included for spinning up these for development. 
+Setup instructions are as follows:
+
+Step 1 - Copy ``.env`` template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Copy ``docker/example.env`` to ``.env`` within the docker folder. Modify as appropriate.
+
+.. code-block:: bash
+
+    cp docker/example.env docker/.env
+
+Step 2 - Run the servers
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+All you need to do is to run the following command.
+
+.. code-block:: bash
+
+    docker compose -f docker/docker-compose.dev.yml up -d
+
+.. tip:: 
+
+    If you have Task installed, you can use ``task dev-up`` as a shortcut.
+
+Details
+-------
+
+Development Features
+^^^^^^^^^^^^^^^^^^^^
+
+Catherine-Chan includes an development mode allowing for continuous
+reloading of extensions and library code. Once the file is saved, the 
+module is reloaded and changes can be reflected. This can be enabled 
+through the ``bot.dev_mode`` key in the configuration file. In addition,
+Jishaku is bundled with the bot, allowing for easy debugging and
+faster development.
+
+.. note::
+
+    You may need to restart the bot entirely for
+    some changes to be reflected.
+
+Prometheus Metrics
+^^^^^^^^^^^^^^^^^^
+
+Catherine-Chan also includes an Prometheus endpoint for metrics.
+This can enabled through the ``bot.prometheus.enabled`` key. If 
+you don't need this feature, feel free to entirely disable it.
+Disabling this feature does not affect the bot, as the cog
+responsible for this feature is an extension that can be
+enabled at will. 
+
+Type Hinting
+^^^^^^^^^^^^
+
+Catherine-Chan actively uses `type hinting <https://docs.python.org/3/library/typing.html>`_ in order to verify for types before runtime.
+`Pyright <https://github.com/microsoft/pyright>`_ is used to enforce this standard. Checks happen before you commit, and on Github actions.
+These checks are activated by default on VSCode. Pyright is available as a LSP on Neovim.

docs/source/index.rst → docs/index.rst

@@ -9,10 +9,16 @@ Catherine-Chan
 .. toctree::
    :maxdepth: 2
    :hidden:
-   :caption: Guides
+   :caption: User Guide
 
-   guides/dev/index
-   guides/user/index
+   user-guide/index
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Development Guide
+
+   dev-intro
 
 .. toctree::
    :maxdepth: 2
@@ -30,7 +36,7 @@ Catherine-Chan
    terms-of-service/privacy-policy.rst
 
 
-.. figure:: /_static/pride_smaller.png
+.. figure:: /_assets/pride_smaller.png
    :align: right
 
 .. image:: https://img.shields.io/github/v/release/No767/Catherine-Chan?label=Release&logo=github&sort=semver
@@ -60,8 +66,8 @@ Guides
 
 Are you interested in contributing to Catherine-Chan as a developer? Or are you interested in learning the different features of Catherine-chan? This is the place to get started!
 
-- :doc:`guides/dev/index`
-- :doc:`guides/user/index`
+- :doc:`dev-intro`
+- :doc:`user-guide/index`
 
 Resources and Links
 -------------------

docs/requirements.txt

@@ -1,4 +1,4 @@
-sphinx>=7.3.7
-furo>=2023.8.19
-sphinx-copybutton>=0.5.2
-sphinxext-opengraph>=0.8.2
+sphinx>=8.1.3,<9
+furo>=2024.8.6,<2025
+sphinx-copybutton>=0.5.2,<1
+sphinxext-opengraph>=0.9.1,<1