[PATCH] Added the rest of the docs + PyPI deploy

.github/workflows/pypi_deploy.yml

+# This workflow deploys a new release on PyPI once a pull request is closed
+
+name: Deploy to PyPI
+
+on:
+  pull_request:
+    types: [ closed ]
+    branches:
+      - main
+
+jobs:
+  pypi-deploy:
+    name: Build and publish Python 🐍 distributions 📦 to live PyPI
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.merged == true
+
+    steps:
+    - uses: actions/checkout@master
+
+    - name: Publish distribution 📦 to PyPI
+      uses: JRubics/poetry-publish@v1.13
+      with:
+        ignore_dev_requirements: 'yes'
+        pypi_token: ${{ secrets.PYPI_PASSWORD }}

docs/index.md

-# EguiValet Server - Documentation - Index
+# EguiValet Server - Documentation - Index <!-- omit in toc -->
 
 This document contains the documentation for the EguiValet Server project.
 
-## Table of Contents
-
-- [EguiValet Server - Documentation - Index](#eguivalet-server---documentation---index)
-  - [Table of Contents](#table-of-contents)
-  - [Introduction](#introduction)
-  - [Installation](#installation)
-  - [Development](#development)
-    - [Project file structure](#project-file-structure)
-      - [Root directory](#root-directory)
-      - [Docs](#docs)
-      - [Source directory](#source-directory)
-      - [Tests](#tests)
-    - [OpenAPI docs](#openapi-docs)
-
-## Introduction
+## Table of Contents <!-- omit in toc -->
+
+- [1. Introduction](#1-introduction)
+- [2. Installation](#2-installation)
+- [3. Development](#3-development)
+  - [3.1. Project file structure](#31-project-file-structure)
+    - [3.1.1. Root directory](#311-root-directory)
+    - [3.1.2. Docs](#312-docs)
+    - [3.1.3. Source directory](#313-source-directory)
+    - [3.1.4. Tests](#314-tests)
+  - [3.2. OpenAPI docs](#32-openapi-docs)
+  - [3.3. Unit tests](#33-unit-tests)
+  - [3.4. Linters](#34-linters)
+  - [3.5. Build](#35-build)
+- [4. Usage](#4-usage)
+  - [4.1. Running](#41-running)
+- [5. Troubleshooting](#5-troubleshooting)
+
+## 1. Introduction
 
 This is the server half of the EguiValet chat application project, which
 functions as the brains behing the chat system, storing chatrooms, users,
@@ -35,7 +39,7 @@ This guide will instruct you on how to operate the server application, how to
 extend it, where to find what, and the last chapter will provide help for
 solving known problems.
 
-## Installation
+## 2. Installation
 
 To install the server application, it is recommended to download the latest
 packaged executable file from the project's
@@ -67,12 +71,12 @@ If one doesn't exist, you'll likely need to install from source.
 
     to install the dependencies and to open a virtual environment session
 
-## Development
+## 3. Development
 
 This part of the documentation will instruct you on how the project is
 structured, and how to continue developing it.
 
-### Project file structure
+### 3.1. Project file structure
 
 The project files can be categorised roughly into four categories; the project
 metadata files in the root directory, files in the documentation directory,
@@ -100,7 +104,7 @@ of the documentation will attempt to proovide an overview of all these.
  ┗ 📜server.db
 ```
 
-#### Root directory
+#### 3.1.1. Root directory
 
 The repository houses several metadata files which are mostly either
 information about the project itself, configuration files, or utility
@@ -161,7 +165,7 @@ files.
     change in the future. It can be viewed manually with a tool such as
     [DB Browser]
 
-#### Docs
+#### 3.1.2. Docs
 
 The `docs` directory mostly contains the documentation, which you are reading
 right now, but in addition it also houses code examples for different API
@@ -175,7 +179,7 @@ interface.
  ┗ 📜pull_request_template.md
 ```
 
-#### Source directory
+#### 3.1.3. Source directory
 
 The directory containing the project's source code, `eguivalet_server`, is
 fairly vast. There's likely no need to go into full detail as the files are
@@ -224,27 +228,205 @@ mostly self-documenting, so this section aims to provide a general overview.
   - `other.py` contains miscellaneous routes, like the Hello World message
   - `robots.txt` contains what the API serves when asked for it
 
+- `__main__.py`
+  This file makes the module an executable Python package
+  (eg. `python -m eguivalet_server`)
+
 - `config.py`
-  Contains
+  Contains virtually all important configuration options for the server,
+  such as string data length limits and the database URL, which can be
+  changed if needed
 
 - `crud.py`
+  Utilities for interfacing with the database. The name stands for
+  Create, Read, Update, Delete
+
 - `database.py`
+  Defines the database engine, and a function that auto-closes a provided
+  database session
+
 - `main.py`
+  The main executable used to run the program
+
 - `models.py`
+  Defines SQLAlchemy database models
+
 - `openapi_extension.py`
+  Defines extensions for the OpenAPI standard, too enrich the content of
+  Redoc and Swagger UI
+
 - `schemas.py`
+  Defines Pydantic schemas for automatic data verification and conversion
+
 - `utility.py`
+  Defines miscellaneous utility functions that don't really fit elsewhere
 
-#### Tests
+#### 3.1.4. Tests
 
-The `tests`-directory coontains unit tests - how original. But that's actually
+The `tests`-directory contains unit tests - how original. But that's actually
 not everything, which is why this directory deserves its own coverage.
 
-### OpenAPI docs
+```text
+📂tests
+ ┣ 📂reports
+ ┃ ┣ 📂coverage-html
+ ┃ ┗ 📜coverage.xml
+ ┣ 📜conftest.py
+ ┣ 📜test_crud.py
+ ┣ 📜test_rooms.py
+ ┣ 📜test_root.py
+ ┣ 📜test_schemas.py
+ ┣ 📜test_users.py
+ ┗ 📜test.db
+```
+
+- `reports`
+  This directory is generated whenever unit tests are executed, containing
+  coverage reports in both JUnit XML and HTML format, thee latter being a
+  human-readable web page
+
+- `conftest.py`
+  This is a special file `pytest` loads when it starts a test session. In
+  this project, it's used to define useful fixtures for getting access to a
+  testing database, and initialising it for different test configurations
+
+- `test_crud.py`
+  Contains unit tests for CRUD operations not already covered by other tests
+
+- `test_rooms.py`
+  Contains unit tests for chatroom routes
+
+- `test_root.py`
+  Contains unit tests for the "other" routes for the root address, like
+  the Hello World message
+
+- `test_schemas.py`
+  Contains unit tests for Pydantic schemas not already covered by other tests
+
+- `test_users.py`
+  Contains unit ttests for user routes
+
+- `test.db`
+  This is a database file generated while running the tests. In practice,
+  the database remains empty as the tests utilise transactions which are
+  ultimately cancelled, but it neeeds to exist during testing - in the
+  future the test suite may delete it automatically after the tests finish
+
+### 3.2. OpenAPI docs
 
 Thanks to `fastapi`, the EguiValet server offers built-in API documentation in
 the form of Redoc and Swagger. They are useful tools for keeping track of which
-routes
+routes the API defines, what HTTP methods they support, what kind of data they
+expect and return, and even what errors may arise.
+
+Swagger is a flexible interface, letting you make requests to the API from
+within itself, if you want to test something on the fly. Assuming default
+configuration, it can be accessed using a web browser while the server is
+running via the address
+
+```text
+localhost:11037/docs
+```
+
+Swagger is very intuitive to use, so it shouldn't require additional
+explanation.
+
+Redoc is purely for API documentation, and can display more information than
+Swagger. It can be accessed via the address
+
+```text
+localhost:11037/redoc
+```
+
+### 3.3. Unit tests
+
+All of the unit tests for the project are contained in `/tests`. They use
+`pytest`, but it is possible to write tests using the built-in `unittest`
+module as well since `pytest` supports it. That said, it is recommended to
+stick to `pytest` as fragmenting the test codebase would not be ideal.
+
+The existing test suite can be used as an example for writing new tests, in
+fact that is encouraged in order to keep the tests uniform.
+
+Running the unit tests is as simplle as running the command `poetry run pytest`
+in a terminal, such as PowerShell, within the project's root directory.
+
+The unit tests generate coverage reports, which can be used to track how much
+of the codebase was executed during testing. This is a useful metric, and a
+good goal is 90% coverage or better. These reports are automatically uploaded
+to Codecov when pushing code to GitHub, and can be seen on the `README.md`.
+
+### 3.4. Linters
+
+Linters are used to keep the codebase consistent and as compliant to the PEP-8
+and PEP-257 rules as possible. Sometimes they cannot be perfectly met due to
+design considerations, which is normal, but it is a goood aim to always focus
+on writing readable and maintainable, consistent code.
+
+The project uses `pylint` and `flake8`, both of which are configured in
+`pyproject.toml`. To run them, simply run
+
+```sh
+poetry run pylint eguivalet_server
+poetry run pflake8
+```
+
+in a terminal, such as PowerShell, within the project's root directory.
+
+> The `p` in `pflake8` is not a typo. In order to keep `flake8`'s configuration
+in `pyproject.toml`, until official support is added we use `pyproject-flake8`
+as a middleman, which uses that alias.
+
+Running the linters will list all places where they find style problems,
+letting you fix them at your leisure. If a problem cannot be fixed due to a
+design consideration for the project, either ignore that one line or add an
+exception in `pyproject.toml` to ignore the error altogether, preferably
+with some kind of an explanation.
+
+### 3.5. Build
+
+Building the project is, again, fairly simple. By running
+`poetry build --format wheel` in a terminal, Poetry will generate a portable
+wheel file which can then be easily installed anywhere with a compatible Python
+environment and an internet connection for fetching the dependencies. The
+generated file can be found in `/dist`.
+
+## 4. Usage
+
+The EguiValet server has beeen designed to be fairly easy to use without any
+mandatory training.
+
+### 4.1. Running
+
+If using a cloned repository, you simply need to run the main program while
+Poetry's virtual environment is active.
+
+1. Install a compatible Python version (3.8 or newer at the time of writing)
+2. Install Poetry (`pip install poetry`)
+   NOTE: If Python wasn't addeed to PATH during installlation, you may need to
+   prepend all these commands with `py -m` for them to work.
+3. While in the project directory, run `poetry shell`
+4. After the virtual environment has been generated, run `poetry install` to
+   install all dependencies. If you don't care about development dependencies,
+   you can add the `--no-dev` flag
+5. Once all dependencies have been installed, simply run
+   `poetry run python eguivalet_server/main.py` within the environment
+
+This will launch Uvicorn, which begins seetting up the server and it should
+finish in a minute. All the logs will be displayed in the terminal. You can
+test it works by trying to open
+
+```text
+localhost:11037/
+```
+
+in any web browser on your computer. A message should get logged into the
+terminal.
+
+Once the server is running, nothing needs to be done unlless you need to
+reconfigure the server or perform other administrative tasks.
+
+## 5. Troubleshooting
 
 [DB Browser]: https://sqlitebrowser.org/
 [GitHub]: https://github.com/Diapolo10/5G00EV25-3001_server

eguivalet_server/config.py

@@ -56,7 +56,7 @@ class AccessLevel(IntEnum):
 # Running
 
 HOST = '127.0.0.1'
-PORT = 8080
+PORT = 11037
 URL = f'http://{HOST}:{PORT}'