From f6901f7f9eb588c6065d18ef5f42e9d1ccbc3716 Mon Sep 17 00:00:00 2001
From: s3lph <account-gitlab-ideynizv@kernelpanic.lol>
Date: Wed, 15 Aug 2018 16:18:52 +0200
Subject: [PATCH] User bootstrapping documentation

---
 doc                                         |  2 +-
 matemat/db/facade.py                        |  2 ++
 matemat/webserver/pagelets/main.py          |  1 +
 matemat/webserver/pagelets/userbootstrap.py | 11 +++++++++++
 templates/userbootstrap.html                |  3 ++-
 5 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/doc b/doc
index c3cbf1f..9449a6d 160000
--- a/doc
+++ b/doc
@@ -1 +1 @@
-Subproject commit c3cbf1fdabc81c3e73d831655fe4d9c2d3d8330c
+Subproject commit 9449a6dc39843969d3b549f05848b5857c23cfa3
diff --git a/matemat/db/facade.py b/matemat/db/facade.py
index 29562c8..b7f4291 100644
--- a/matemat/db/facade.py
+++ b/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] = []
diff --git a/matemat/webserver/pagelets/main.py b/matemat/webserver/pagelets/main.py
index 8524e4a..54f6f79 100644
--- a/matemat/webserver/pagelets/main.py
+++ b/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
diff --git a/matemat/webserver/pagelets/userbootstrap.py b/matemat/webserver/pagelets/userbootstrap.py
index b9ac067..8efdb39 100644
--- a/matemat/webserver/pagelets/userbootstrap.py
+++ b/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'])
diff --git a/templates/userbootstrap.html b/templates/userbootstrap.html
index 57c8a45..3bab41f 100644
--- a/templates/userbootstrap.html
+++ b/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 %}