User bootstrapping documentation

doc

@@ -1 +1 @@
-Subproject commit c3cbf1fdabc81c3e73d831655fe4d9c2d3d8330c
+Subproject commit 9449a6dc39843969d3b549f05848b5857c23cfa3

matemat/db/facade.py

@@ -76,6 +76,8 @@ class MatematDatabase(object):
     def list_users(self, with_touchkey: bool = False) -> List[User]:
         """
         Return a list of users in the database.
+
+        :param with_touchkey: If true, only lists those users that have a touchkey set.  Defaults to false.
         :return: A list of users.
         """
         users: List[User] = []

matemat/webserver/pagelets/main.py

@@ -30,6 +30,7 @@ def main_page(method: str,
                                     authuser=user, products=products, authlevel=authlevel,
                                     setupname=config['InstanceName'])
         else:
+            # If there are no admin users registered, jump to the admin creation procedure
             if not db.has_admin_users():
                 return RedirectResponse('/userbootstrap')
             # If no user is logged in, fetch the list of users and render the userlist template

matemat/webserver/pagelets/userbootstrap.py

@@ -14,19 +14,30 @@ def userbootstrap(method: str,
                   headers: Dict[str, str],
                   config: Dict[str, str]) \
         -> Union[bytes, str, PageletResponse]:
+    """
+    The page for creating a first admin user.  To be used when the system is set up the first time, or when there are no
+    admin users left.
+    """
     with MatematDatabase(config['DatabaseFile']) as db:
+        # Redirect to main if there are still administrators registered
         if db.has_admin_users():
             return RedirectResponse('/')
+        # Process submission
         if method == 'POST':
+            # Make sure all required values are present
             if 'username' not in args or 'password' not in args or 'password2' not in args:
                 raise HttpException(400, 'Some arguments are missing')
             username: str = str(args.username)
             password: str = str(args.password)
             password2: str = str(args.password2)
+            # The 2 passwords must match
             if password != password2:
                 return RedirectResponse('/userbootstrap')
+            # Create the admin user
             db.create_user(username, password, None, True, False)
+            # Redirect to the main page
             return RedirectResponse('/')
+        # Requested via GET; show the user creation UI
         else:
             return TemplateResponse('userbootstrap.html',
                                     setupname=config['InstanceName'])

templates/userbootstrap.html

@@ -1,7 +1,8 @@
 {% extends "base.html" %}
 
 {% block header %}
-    <h1>Setup</h1>
+    {# Show the setup name, as set in the config file, as page title followed by "Setup". Don't escape HTML entities. #}
+    <h1>{{ setupname|safe }} Setup</h1>
     {{ super() }}
 {% endblock %}