Resolve "Add automatic documentation generation"

.gitignore

-__pycache__
-*.db
-*/env
 *.coverage
 */coverage
-htmlcov
-.pytest_cache
 /.idea
 .vs/
-/server/app/static/

.vscode/settings.json

@@ -41,5 +41,6 @@
   "search.exclude": {
     "**/env": true
   },
-  "python.pythonPath": "server\\env\\Scripts\\python.exe"
+  "python.pythonPath": "server\\env\\Scripts\\python.exe",
+  "restructuredtext.confPath": "${workspaceFolder}\\server\\sphinx\\source"
 }

.vscode/tasks.json

@@ -23,7 +23,6 @@
         {
             "label": "Open client coverage",
             "type": "shell",
-            "group": "build",
             "command": "start ./output/coverage/jest/index.html",
             "problemMatcher": [],
             "options": {
@@ -54,7 +53,7 @@
             },
         },
         {
-            "label": "Populate server",
+            "label": "Populate database",
             "type": "shell",
             "group": "build",
             "command": "env/Scripts/python populate.py",
@@ -66,13 +65,30 @@
         {
             "label": "Open server coverage",
             "type": "shell",
-            "group": "build",
             "command": "start ./htmlcov/index.html",
             "problemMatcher": [],
             "options": {
                 "cwd": "${workspaceFolder}/server"
             },
         },
+        {
+            "label": "Generate server documentation",
+            "type": "shell",
+            "command": "../env/Scripts/activate; ./make html",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${workspaceFolder}/server/docs"
+            },
+        },
+        {
+            "label": "Open server documentation",
+            "type": "shell",
+            "command": "start index.html",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${workspaceFolder}/server/docs/build/html"
+            },
+        },
         {
             "label": "Start client and server",
             "group": "build",

server/.gitignore

+__pycache__
+env
+htmlcov
+.pytest_cache
+app/*.db
+app/static/
+
+# Documentation files
+docs/build

server/app/__init__.py

@@ -7,6 +7,11 @@ from app.core.dto import MediaDTO
 
 
 def create_app(config_name="configmodule.DevelopmentConfig"):
+    """
+    Creates Flask app, returns it and a SocketIO instance. Call run on the
+    SocketIO instance and pass in the Flask app to start the server.
+    """
+
     app = Flask(__name__, static_url_path="/static", static_folder="static")
     app.config.from_object(config_name)
     app.url_map.strict_slashes = False

server/app/core/__init__.py

+"""
+The core submodule contains everything important to the server that doesn't
+fit neatly in either apis or database.
+"""
+
 from app.database import Base, ExtendedQuery
 from flask_bcrypt import Bcrypt
 from flask_jwt_extended.jwt_manager import JWTManager

server/app/core/codes.py

+"""
+Contains all functions purely related to creating and verifying a code.
+"""
+
 import random
 import re
 import string
@@ -7,9 +11,14 @@ ALLOWED_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 CODE_RE = re.compile(f"^[{ALLOWED_CHARS}]{{{CODE_LENGTH}}}$")
 
 
-def generate_code_string():
+def generate_code_string() -> str:
+    """Generates a 6 character long random sequence containg uppercase letters
+    and numbers.
+    """
     return "".join(random.choices(ALLOWED_CHARS, k=CODE_LENGTH))
 
 
-def verify_code(c):
-    return CODE_RE.search(c.upper()) is not None
+def verify_code(code: str) -> bool:
+    """Returns True if code only contains letters and/or numbers
+    and is exactly 6 characters long."""
+    return CODE_RE.search(code.upper()) is not None

server/app/core/dto.py

+"""
+The DTO module (short for Data Transfer Object) connects the namespace of an
+API and its related schemas.
+"""
+
 import app.core.rich_schemas as rich_schemas
 import app.core.schemas as schemas
 from flask_restx import Namespace

server/app/core/files.py

+"""
+Contains functions related to file handling, mainly saving and deleting images.
+"""
+
 from PIL import Image, ImageChops
-from flask import current_app
+from flask import current_app, has_app_context
 import os
 import datetime
 from flask_uploads import IMAGES, UploadSet
 
-PHOTO_PATH = current_app.config["UPLOADED_PHOTOS_DEST"]
-THUMBNAIL_SIZE = current_app.config["THUMBNAIL_SIZE"]
-image_set = UploadSet("photos", IMAGES)
+if has_app_context():
+    PHOTO_PATH = current_app.config["UPLOADED_PHOTOS_DEST"]
+    THUMBNAIL_SIZE = current_app.config["THUMBNAIL_SIZE"]
+    image_set = UploadSet("photos", IMAGES)
 
 
-def compare_images(input_image, output_image):
-    # compare image dimensions (assumption 1)
-    if input_image.size != output_image.size:
-        return False
+# def compare_images(input_image, output_image):
+#     # compare image dimensions (assumption 1)
+#     if input_image.size != output_image.size:
+#         return False
 
-    rows, cols = input_image.size
+#     rows, cols = input_image.size
 
-    # compare image pixels (assumption 2 and 3)
-    for row in range(rows):
-        for col in range(cols):
-            input_pixel = input_image.getpixel((row, col))
-            output_pixel = output_image.getpixel((row, col))
-            if input_pixel != output_pixel:
-                return False
+#     # compare image pixels (assumption 2 and 3)
+#     for row in range(rows):
+#         for col in range(cols):
+#             input_pixel = input_image.getpixel((row, col))
+#             output_pixel = output_image.getpixel((row, col))
+#             if input_pixel != output_pixel:
+#                 return False
 
-    return True
+#     return True
 
 
 def _delete_image(filename):
@@ -33,6 +38,10 @@ def _delete_image(filename):
 
 
 def save_image_with_thumbnail(image_file):
+    """
+    Saves the given image and also creates a small thumbnail for it.
+    """
+
     saved_filename = image_set.save(image_file)
     saved_path = os.path.join(PHOTO_PATH, saved_filename)
     with Image.open(saved_path) as im:
@@ -45,6 +54,9 @@ def save_image_with_thumbnail(image_file):
 
 
 def delete_image_and_thumbnail(filename):
+    """
+    Delete the given image together with its thumbnail.
+    """
     _delete_image(filename)
     _delete_image(f"thumbnail_{filename}")
 

server/app/core/http_codes.py

+"""
+This module defines all the http status codes thats used in the api.
+"""
+
 OK = 200
 NO_CONTENT = 204
 BAD_REQUEST = 400

server/app/core/parsers.py

+"""
+This module contains the parsers used to parse the data gotten in api requests.
+"""
+
 from flask_restx import inputs, reqparse
 
 

server/app/core/rich_schemas.py

+"""
+This module contains rich schemas used to convert database objects into 
+dictionaries. This is the rich variant which means that objects will 
+pull in other whole objects instead of just the id.
+"""
 import app.core.schemas as schemas
 import app.database.models as models
 from app.core import ma

server/app/core/schemas.py

+"""
+This module contains schemas used to convert database objects into 
+dictionaries.
+"""
+
 from marshmallow.decorators import pre_load
 from marshmallow.decorators import pre_dump, post_dump
 import app.database.models as models

server/app/core/sockets.py

+"""
+Contains all functionality related sockets. That is starting and ending a presentation, 
+joining and leaving a presentation and syncing slides and timer bewteen all clients
+connected to the same presentation.
+"""
+
+from typing import Dict
 import app.database.controller as dbc
 from app.core import db
 from app.database.models import Competition, Slide, Team, ViewType, Code
@@ -20,12 +27,16 @@ presentations = {}
 
 
 @sio.on("connect")
-def connect():
+def connect() -> None:
     logger.info(f"Client '{request.sid}' connected")
 
 
 @sio.on("disconnect")
-def disconnect():
+def disconnect() -> None:
+    """
+    Remove client from the presentation it was in. Delete presentation if no
+    clients are connected to it.
+    """
     for competition_id, presentation in presentations.items():
         if request.sid in presentation["clients"]:
             del presentation["clients"][request.sid]
@@ -40,7 +51,11 @@ def disconnect():
 
 
 @sio.on("start_presentation")
-def start_presentation(data):
+def start_presentation(data: Dict) -> None:
+    """
+    Starts a presentation if that competition is currently not active.
+    """
+
     competition_id = data["competition_id"]
 
     if competition_id in presentations:
@@ -62,7 +77,15 @@ def start_presentation(data):
 
 
 @sio.on("end_presentation")
-def end_presentation(data):
+def end_presentation(data: Dict) -> None:
+    """
+    End a presentation by sending end_presentation to all connected clients.
+
+    The only clients allowed to do this is the one that started the presentation.
+
+    Log error message if no presentation exists with the send id or if this
+    client is not in that presentation.
+    """
     competition_id = data["competition_id"]
 
     if competition_id not in presentations:
@@ -91,8 +114,13 @@ def end_presentation(data):
 
 
 @sio.on("join_presentation")
-def join_presentation(data):
-    team_view_id = 1
+def join_presentation(data: Dict) -> None:
+    """
+    Join a currently active presentation.
+
+    Log error message if given code doesn't exist, if not presentation associated
+    with that code exists or if client is already in the presentation.
+    """
     code = data["code"]
     item_code = db.session.query(Code).filter(Code.code == code).first()
 
@@ -126,7 +154,15 @@ def join_presentation(data):
 
 
 @sio.on("set_slide")
-def set_slide(data):
+def set_slide(data: Dict) -> None:
+    """
+    Sync slides between all clients in the same presentation by sending
+    set_slide to them.
+
+    Log error if the given competition_id is not active, if client is not in
+    that presentation or the client is not the one who started the presentation.
+    """
+
     competition_id = data["competition_id"]
     slide_order = data["slide_order"]
 
@@ -165,7 +201,14 @@ def set_slide(data):
 
 
 @sio.on("set_timer")
-def set_timer(data):
+def set_timer(data: Dict) -> None:
+    """
+    Sync slides between all clients in the same presentation by sending
+    set_timer to them.
+
+    Log error if the given competition_id is not active, if client is not in
+    that presentation or the client is not the one who started the presentation.
+    """
     competition_id = data["competition_id"]
     timer = data["timer"]
 

server/app/database/__init__.py

+"""
+The database submodule contaisn all functionality that has to do with the
+database. It can add, get, delete, edit, search and copy items.
+"""
+
 import json
 
 from flask_restx import abort
@@ -16,7 +21,15 @@ class Base(Model):
 
 
 class ExtendedQuery(BaseQuery):
+    """
+    Extensions to a regular query which makes using the database more convenient.
+    """
+
     def first_extended(self, required=True, error_message=None, error_code=404):
+        """
+        Extensions of the first() functions otherwise used on queries. Abort
+        if no item was found and it was required.
+        """
         item = self.first()
 
         if required and not item:
@@ -27,6 +40,10 @@ class ExtendedQuery(BaseQuery):
         return item
 
     def pagination(self, page=0, page_size=15, order_column=None, order=1):
+        """
+        When looking for lists of items this is used to only return a few of
+        them to allow for pagination.
+        """
         query = self
         if order_column:
             if order == 1:
@@ -40,17 +57,17 @@ class ExtendedQuery(BaseQuery):
         return items, total
 
 
-class Dictionary(TypeDecorator):
+# class Dictionary(TypeDecorator):
 
-    impl = Text
+#     impl = Text
 
-    def process_bind_param(self, value, dialect):
-        if value is not None:
-            value = json.dumps(value)
+#     def process_bind_param(self, value, dialect):
+#         if value is not None:
+#             value = json.dumps(value)
 
-        return value
+#         return value
 
-    def process_result_value(self, value, dialect):
-        if value is not None:
-            value = json.loads(value)
-        return value
+#     def process_result_value(self, value, dialect):
+#         if value is not None:
+#             value = json.loads(value)
+#         return value

server/app/database/controller/__init__.py

-# import add, get
+"""
+The controller subpackage provides a simple interface to the database. It 
+exposes methods to simply add, copy, delete, edit, get and search for items.
+"""
+
 from app.core import db
 from app.database.controller import add, copy, delete, edit, get, search, utils

server/app/database/models.py

+"""
+This file contains every model in the database. In regular SQL terms, it 
+defines every table, the fields in those tables and their relationship to 
+each other.
+"""
+
 from app.core import bcrypt, db
 from sqlalchemy.ext.hybrid import hybrid_method, hybrid_property
 

server/app/database/types.py

+"""
+This module defines the different component types.
+"""
+
 ID_TEXT_COMPONENT = 1
 ID_IMAGE_COMPONENT = 2
 ID_QUESTION_COMPONENT = 3
\ No newline at end of file

server/docs/Makefile

+# 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     = source
+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)

server/docs/make.bat

+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%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.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd