wsgi server docs

.gitignore

@@ -140,3 +140,4 @@ server/**/*.db-journal
 server/docs/build
 server/thumbnails/*
 !server/thumbnails/.gitkeep
+server/*.json

server/docs/make.bat

@@ -1,35 +1,35 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-    set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-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
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+    set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+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

server/src/api_user_routes.py

@@ -22,6 +22,7 @@
 
 cred = credentials.Certificate('../inventory-a7bb6-firebase-adminsdk-ikk5m-492b597eea.json')
 firebase_admin.initialize_app(cred)
+# TODO add doc about firebase not initializing if tst placeholder is included for build
 
 
 def create_user(user_id: Identifier, name: str, authmask: int) -> models.User:

server/src/identifier.py

@@ -9,7 +9,7 @@
 
 _alphabet = string.ascii_lowercase + (string.digits * 2)
 # TODO documentation
-# Increase the probability of getting a digit (otherwise few digits appear)
+# TODO Increase the probability of getting a digit (otherwise few digits appear)
 
 
 class IdInitializerError(ValueError):

server/src/wsgi.py

@@ -14,15 +14,24 @@
 
 
 def _create_table(entity_type: Type[models.Model]):
-    # TODO documentation
+    """
+    Creates a single table in the backing database
+    representing a store for a passed model type.
+
+    Assumes an ``INTEGER`` data type if the backing data is of type ``int``,
+    otherwise assumes type ``TEXT`` (i.e. ``VARCHAR``).
+    """
     model_keys = models.get_model_attributes(entity_type).items()
     table_keys = ', '.join([f'{k} {"INTEGER" if isinstance(v, int) else "TEXT"}' for k, v in model_keys])
     conn, cursor = common.get_db_connection()
     cursor.execute(f'CREATE TABLE IF NOT EXISTS {entity_type.table_name}({table_keys})').close()
 
 
 def _create_tables():
-    # TODO documentation
+    """
+    Creates all tables in the backing database
+    representing stores for all model types (:py:class:`models.Box`).
+    """
     with app.app_context():
         _create_table(models.Item)
         _create_table(models.User)
@@ -45,7 +54,7 @@ def _create_tables():
 
 @app.teardown_appcontext
 def close_connection(exception):
-    # TODO documentation
+    """Close database connection, if previously opened."""
     db = getattr(flask.g, '_database', None)
     if db is not None:
         db.close()