Added some more documentation, especially package docs.

README.md

@@ -1,11 +1,22 @@
-# matemat
+# Matemat
 
-[![pipeline status](https://gitlab.com/s3lph/matemat/badges/master/pipeline.svg)](https://gitlab.com/s3lph/matemat/commits/master)
-[![coverage report](https://gitlab.com/s3lph/matemat/badges/master/coverage.svg)](https://gitlab.com/s3lph/matemat/commits/master)
+[![pipeline status](https://gitlab.com/s3lph/matemat/badges/master/pipeline.svg)][master]
+[![coverage report](https://gitlab.com/s3lph/matemat/badges/master/coverage.svg)][master]
+
+A web service for automated stock-keeping of a soda machine written in Python.
+It provides a touch-input-friendly user interface (as most input happens through the
+soda machine's touch screen).
+
+This project intends to provide a well-tested and maintainable alternative to
+[TODO][todo] (discontinued).
+
+## Further Documentation
+
+[Wiki][wiki]
 
 ## Dependencies
 
-- Python 3.6
+- Python 3 (>=3.6)
 - Python dependencies:
   - apsw
   - bcrypt
@@ -16,6 +27,16 @@
 python -m matemat
 ```
 
+## Contributors
+
+- s3lph
+- SPiNNiX
+
 ## License
 
-[MIT License](https://gitlab.com/s3lph/matemat/blob/master/LICENSE)
+[MIT License][mit-license]
+
+
+[mit-license]: https://gitlab.com/s3lph/matemat/blob/master/LICENSE
+[master]: https://gitlab.com/s3lph/matemat/commits/master
+[wiki]: https://gitlab.com/s3lph/matemat/wiki

matemat/db/__init__.py

@@ -1,3 +1,6 @@
+"""
+This package provides a developer-friendly API to the SQLite3 database backend of the Matemat software.
+"""
 
 from .wrapper import DatabaseWrapper
 from .facade import MatematDatabase

matemat/db/test/test_facade.py

@@ -10,6 +10,7 @@ from matemat.exceptions import AuthenticationError, DatabaseConsistencyError
 class DatabaseTest(unittest.TestCase):
 
     def setUp(self) -> None:
+        # Create an in-memory database for testing
         self.db = MatematDatabase(':memory:')
 
     def test_create_user(self) -> None:

matemat/db/test/test_wrapper.py

@@ -7,6 +7,7 @@ from matemat.db import DatabaseWrapper
 class DatabaseTest(unittest.TestCase):
 
     def setUp(self) -> None:
+        # Create an in-memory database for testing
         self.db = DatabaseWrapper(':memory:')
 
     def test_create_schema(self) -> None:

matemat/exceptions/__init__.py

@@ -1,3 +1,6 @@
+"""
+This package provides custom exception classes used in the Matemat codebase.
+"""
 
 from .AuthenticatonError import AuthenticationError
 from .DatabaseConsistencyError import DatabaseConsistencyError

matemat/primitives/__init__.py

@@ -1,3 +1,6 @@
+"""
+This package provides the 'primitive types' the Matemat software deals with - namely users and products.
+"""
 
 from .User import User
 from .Product import Product

matemat/webserver/__init__.py

@@ -1,2 +1,9 @@
+"""
+The Matemat Webserver.
+
+This package provides the webserver for the Matemat software.  It uses Python's http.server and extends it with an event
+API that can be used by 'pagelets' - single pages of a web service.  If a request cannot be handled by a pagelet, the
+server will attempt to serve the request with a static resource in a previously configured webroot directory.
+"""
 
 from .httpd import MatematWebserver, HttpHandler, pagelet

matemat/webserver/httpd.py

@@ -16,7 +16,7 @@ from datetime import datetime, timedelta
 from matemat import __version__ as matemat_version
 
 
-# Enable IPv6 support (with implicit DualStack)
+# Enable IPv6 support (IPv6/IPv4 dual-stack support should be implicitly enabled)
 TCPServer.address_family = socket.AF_INET6
 
 
@@ -25,6 +25,7 @@ _PAGELET_PATHS: Dict[str, Callable[[str, str, Dict[str, str], Dict[str, Any], Di
                                    Tuple[int, Union[bytes, str]]]] = dict()
 
 
+# Inactivity timeout for client sessions
 _SESSION_TIMEOUT: int = 3600
 
 

matemat/webserver/pagelets/__init__.py

@@ -1,3 +1,8 @@
+"""
+This package contains the pagelet functions served by the Matemat software.
+
+A new pagelet function must be imported here to be automatically loaded when the server is started.
+"""
 
 from .main import main_page
 from .login import login_page