AKSubmission/locale/de_DE/LC_MESSAGES/django.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-05-15 20:03+0200\n"
+"POT-Creation-Date: 2023-08-16 16:30+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -17,16 +17,16 @@ msgstr ""
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 
-#: AKSubmission/forms.py:71
+#: AKSubmission/forms.py:93
 #, python-format
 msgid "\"%(duration)s\" is not a valid duration"
 msgstr "\"%(duration)s\" ist keine gültige Dauer"
 
-#: AKSubmission/forms.py:117
+#: AKSubmission/forms.py:159
 msgid "Duration(s)"
 msgstr "Dauer(n)"
 
-#: AKSubmission/forms.py:119
+#: AKSubmission/forms.py:161
 msgid ""
 "Enter at least one planned duration (in hours). If your AK should have "
 "multiple slots, use multiple lines"
@@ -34,33 +34,6 @@ msgstr ""
 "Mindestens eine geplante Dauer (in Stunden) angeben. Wenn der AK mehrere "
 "Slots haben soll, mehrere Zeilen verwenden"
 
-#: AKSubmission/forms.py:170
-#: AKSubmission/templates/AKSubmission/ak_detail.html:309
-msgid "Start"
-msgstr "Start"
-
-#: AKSubmission/forms.py:171
-#: AKSubmission/templates/AKSubmission/ak_detail.html:310
-msgid "End"
-msgstr "Ende"
-
-#: AKSubmission/forms.py:172
-#: AKSubmission/templates/AKSubmission/ak_detail.html:239
-#: AKSubmission/templates/AKSubmission/akslot_delete.html:35
-msgid "Duration"
-msgstr "Dauer"
-
-#: AKSubmission/forms.py:173
-#: AKSubmission/templates/AKSubmission/ak_detail.html:241
-msgid "Room"
-msgstr "Raum"
-
-#: AKSubmission/forms.py:177
-#: AKSubmission/templates/AKSubmission/ak_history.html:11
-#: AKSubmission/templates/AKSubmission/akslot_delete.html:31
-msgid "AK"
-msgstr "AK"
-
 #: AKSubmission/templates/AKSubmission/ak_detail.html:22
 #: AKSubmission/templates/AKSubmission/ak_edit.html:13
 #: AKSubmission/templates/AKSubmission/ak_history.html:16
@@ -215,6 +188,15 @@ msgstr "Notizen"
 msgid "When?"
 msgstr "Wann?"
 
+#: AKSubmission/templates/AKSubmission/ak_detail.html:239
+#: AKSubmission/templates/AKSubmission/akslot_delete.html:35
+msgid "Duration"
+msgstr "Dauer"
+
+#: AKSubmission/templates/AKSubmission/ak_detail.html:241
+msgid "Room"
+msgstr "Raum"
+
 #: AKSubmission/templates/AKSubmission/ak_detail.html:272
 msgid "Delete"
 msgstr "Löschen"
@@ -231,6 +213,14 @@ msgstr "Einen neuen AK-Slot hinzufügen"
 msgid "Possible Times"
 msgstr "Mögliche Zeiten"
 
+#: AKSubmission/templates/AKSubmission/ak_detail.html:309
+msgid "Start"
+msgstr "Start"
+
+#: AKSubmission/templates/AKSubmission/ak_detail.html:310
+msgid "End"
+msgstr "Ende"
+
 #: AKSubmission/templates/AKSubmission/ak_edit.html:8
 #: AKSubmission/templates/AKSubmission/ak_history.html:11
 #: AKSubmission/templates/AKSubmission/ak_overview.html:8
@@ -260,6 +250,11 @@ msgstr ""
 "Person hinzufügen, die noch nicht in der Liste ist. Ungespeicherte "
 "Änderungen in diesem Formular gehen verloren."
 
+#: AKSubmission/templates/AKSubmission/ak_history.html:11
+#: AKSubmission/templates/AKSubmission/akslot_delete.html:31
+msgid "AK"
+msgstr "AK"
+
 #: AKSubmission/templates/AKSubmission/ak_history.html:27
 msgid "Back"
 msgstr "Zurück"
@@ -283,7 +278,7 @@ msgstr "Die Ergebnisse dieses AKs vorstellen"
 msgid "Intends to submit a resolution"
 msgstr "Beabsichtigt eine Resolution einzureichen"
 
-#: AKSubmission/templates/AKSubmission/ak_list.html:6 AKSubmission/views.py:42
+#: AKSubmission/templates/AKSubmission/ak_list.html:6 AKSubmission/views.py:84
 msgid "All AKs"
 msgstr "Alle AKs"
 
@@ -409,74 +404,74 @@ msgstr ""
 msgid "Submit"
 msgstr "Eintragen"
 
-#: AKSubmission/views.py:73
+#: AKSubmission/views.py:127
 msgid "Wishes"
 msgstr "Wünsche"
 
-#: AKSubmission/views.py:73
+#: AKSubmission/views.py:127
 msgid "AKs one would like to have"
 msgstr ""
 "AKs die sich gewünscht wurden, aber bei denen noch nicht klar ist, wer sie "
 "macht. Falls du dir das vorstellen kannst, trag dich einfach ein"
 
-#: AKSubmission/views.py:93
+#: AKSubmission/views.py:167
 msgid "Currently planned AKs"
 msgstr "Aktuell geplante AKs"
 
-#: AKSubmission/views.py:186
+#: AKSubmission/views.py:300
 msgid "Event inactive. Cannot create or update."
 msgstr "Event inaktiv. Hinzufügen/Bearbeiten nicht möglich."
 
-#: AKSubmission/views.py:202
+#: AKSubmission/views.py:325
 msgid "AK successfully created"
 msgstr "AK erfolgreich angelegt"
 
-#: AKSubmission/views.py:252
+#: AKSubmission/views.py:398
 msgid "AK successfully updated"
 msgstr "AK erfolgreich aktualisiert"
 
-#: AKSubmission/views.py:290
+#: AKSubmission/views.py:449
 #, python-brace-format
 msgid "Added '{owner}' as new owner of '{ak.name}'"
 msgstr "'{owner}' als neue Leitung von '{ak.name}' hinzugefügt"
 
-#: AKSubmission/views.py:333
-msgid "Person Info successfully updated"
-msgstr "Personen-Info erfolgreich aktualisiert"
-
-#: AKSubmission/views.py:355
+#: AKSubmission/views.py:553
 msgid "No user selected"
 msgstr "Keine Person ausgewählt"
 
-#: AKSubmission/views.py:382
+#: AKSubmission/views.py:569
+msgid "Person Info successfully updated"
+msgstr "Personen-Info erfolgreich aktualisiert"
+
+#: AKSubmission/views.py:605
 msgid "AK Slot successfully added"
 msgstr "AK-Slot erfolgreich angelegt"
 
-#: AKSubmission/views.py:395
+#: AKSubmission/views.py:624
 msgid "You cannot edit a slot that has already been scheduled"
 msgstr "Bereits geplante AK-Slots können nicht mehr bearbeitet werden"
 
-#: AKSubmission/views.py:405
+#: AKSubmission/views.py:634
 msgid "AK Slot successfully updated"
 msgstr "AK-Slot erfolgreich aktualisiert"
 
-#: AKSubmission/views.py:417
+#: AKSubmission/views.py:652
 msgid "You cannot delete a slot that has already been scheduled"
 msgstr "Bereits geplante AK-Slots können nicht mehr gelöscht werden"
 
-#: AKSubmission/views.py:427
+#: AKSubmission/views.py:662
 msgid "AK Slot successfully deleted"
 msgstr "AK-Slot erfolgreich angelegt"
 
-#: AKSubmission/views.py:434
+#: AKSubmission/views.py:674
 msgid "Messages"
 msgstr "Nachrichten"
 
-#: AKSubmission/views.py:444
+#: AKSubmission/views.py:684
 msgid "Delete all messages"
 msgstr "Alle Nachrichten löschen"
 
-#: AKSubmission/views.py:467
+#: AKSubmission/views.py:711
 msgid "Message to organizers successfully saved"
 msgstr "Nachricht an die Organisator*innen erfolgreich gespeichert"
 

AKSubmission/models.py

@@ -3,14 +3,15 @@ from django.conf import settings
 from django.core.mail import EmailMessage
 from django.db.models.signals import post_save
 from django.dispatch import receiver
-from django.urls import reverse_lazy
 
 from AKModel.models import AKOrgaMessage, AKSlot
 
 
 @receiver(post_save, sender=AKOrgaMessage)
-def orga_message_saved_handler(sender, instance: AKOrgaMessage, created, **kwargs):
-    # React to newly created Orga message by sending an email
+def orga_message_saved_handler(sender, instance: AKOrgaMessage, created, **kwargs): # pylint: disable=unused-argument
+    """
+    React to newly created Orga message by sending an email
+    """
 
     if created and settings.SEND_MAILS:
         host = 'https://' + settings.ALLOWED_HOSTS[0] if len(settings.ALLOWED_HOSTS) > 0 else 'http://127.0.0.1:8000'
@@ -26,10 +27,12 @@ def orga_message_saved_handler(sender, instance: AKOrgaMessage, created, **kwarg
 
 
 @receiver(post_save, sender=AKSlot)
-def slot_created_handler(sender, instance: AKSlot, created, **kwargs):
-    # React to slots that are created after the plan was already published by sending an email
-
-    if created and settings.SEND_MAILS and apps.is_installed("AKPlan") and not instance.event.plan_hidden and instance.room is None and instance.start is None:
+def slot_created_handler(sender, instance: AKSlot, created, **kwargs): # pylint: disable=unused-argument
+    """
+    React to slots that are created after the plan was already published by sending an email
+    """
+    if created and settings.SEND_MAILS and apps.is_installed("AKPlan") \
+            and not instance.event.plan_hidden and instance.room is None and instance.start is None: # pylint: disable=too-many-boolean-expressions,line-too-long
         host = 'https://' + settings.ALLOWED_HOSTS[0] if len(settings.ALLOWED_HOSTS) > 0 else 'http://127.0.0.1:8000'
         url = f"{host}{instance.ak.detail_url}"
 

AKSubmission/templatetags/tags_AKSubmission.py

@@ -6,6 +6,11 @@ register = template.Library()
 
 @register.filter
 def bool_symbol(bool_val):
+    """
+    Show a nice icon instead of the string true/false
+    :param bool_val: boolean value to iconify
+    :return: check or times icon depending on the value
+    """
     if bool_val:
         return fa6_icon("check", "fas")
     return fa6_icon("times", "fas")
@@ -13,14 +18,34 @@ def bool_symbol(bool_val):
 
 @register.inclusion_tag("AKSubmission/tracks_list.html")
 def track_list(tracks, event_slug):
+    """
+    Generate a clickable list of tracks (one badge per track) based upon the tracks_list template
+
+    :param tracks: tracks to consider
+    :param event_slug: slug of this event, required for link creation
+    :return: html fragment containing track links
+    """
     return {"tracks": tracks, "event_slug": event_slug}
 
 
 @register.inclusion_tag("AKSubmission/category_list.html")
 def category_list(categories, event_slug):
+    """
+    Generate a clickable list of categories (one badge per category) based upon the category_list template
+
+    :param categories: categories to consider
+    :param event_slug: slug of this event, required for link creation
+    :return: html fragment containing category links
+    """
     return {"categories": categories, "event_slug": event_slug}
 
 
 @register.inclusion_tag("AKSubmission/category_linked_badge.html")
 def category_linked_badge(category, event_slug):
+    """
+    Generate a clickable category badge based upon the category_linked_badge template
+    :param category: category to show/link
+    :param event_slug: slug of this event, required for link creation
+    :return: html fragment containing badge
+    """
     return {"category": category, "event_slug": event_slug}

AKSubmission/tests.py

@@ -9,6 +9,15 @@ from AKModel.tests import BasicViewTests
 
 
 class ModelViewTests(BasicViewTests, TestCase):
+    """
+    Testcases for AKSubmission app.
+
+    This extends :class:`BasicViewTests` for standard view and edit testcases
+    that are specified in this class as VIEWS and EDIT_TESTCASES.
+
+    Additionally several additional testcases, in particular to test the API
+    and the dispatching for owner selection and editing are specified.
+    """
     fixtures = ['model.json']
 
     VIEWS = [
@@ -47,24 +56,27 @@ class ModelViewTests(BasicViewTests, TestCase):
         """
         self.client.logout()
 
-        view_name_with_prefix, url = self._name_and_url(('akslot_edit', {'event_slug': 'kif42', 'pk': 1}))
+        _, url = self._name_and_url(('akslot_edit', {'event_slug': 'kif42', 'pk': 1}))
         response = self.client.get(url)
         self.assertEqual(response.status_code, 302,
                          msg=f"AK Slot editing ({url}) possible even though slot was already scheduled")
         self._assert_message(response, "You cannot edit a slot that has already been scheduled")
 
-        view_name_with_prefix, url = self._name_and_url(('akslot_delete', {'event_slug': 'kif42', 'pk': 1}))
+        _, url = self._name_and_url(('akslot_delete', {'event_slug': 'kif42', 'pk': 1}))
         response = self.client.get(url)
         self.assertEqual(response.status_code, 302,
                          msg=f"AK Slot deletion ({url}) possible even though slot was already scheduled")
         self._assert_message(response, "You cannot delete a slot that has already been scheduled")
 
     def test_slot_creation_deletion(self):
+        """
+        Test creation and deletion of slots in frontend
+        """
         ak_args = {'event_slug': 'kif42', 'pk': 1}
         redirect_url = reverse_lazy(f"{self.APP_NAME}:ak_detail", kwargs=ak_args)
 
+        # Create a valid slot -> Redirect to AK detail page, message to user
         count_slots = AK.objects.get(pk=1).akslot_set.count()
-
         create_url = reverse_lazy(f"{self.APP_NAME}:akslot_add", kwargs=ak_args)
         response = self.client.post(create_url, {'ak': 1, 'event': 2, 'duration': 1.5})
         self.assertRedirects(response, redirect_url, status_code=302, target_status_code=200,
@@ -75,6 +87,8 @@ class ModelViewTests(BasicViewTests, TestCase):
         # Get primary key of newly created Slot
         slot_pk = AK.objects.get(pk=1).akslot_set.order_by('pk').last().pk
 
+        # Edit the recently created slot: Make sure view is accessible, post change
+        # -> redirect to detail page, duration updated
         edit_url = reverse_lazy(f"{self.APP_NAME}:akslot_edit", kwargs={'event_slug': 'kif42', 'pk': slot_pk})
         response = self.client.get(edit_url)
         self.assertEqual(response.status_code, 200, msg=f"Cant open edit view for newly created slot ({edit_url})")
@@ -84,6 +98,8 @@ class ModelViewTests(BasicViewTests, TestCase):
         self.assertEqual(AKSlot.objects.get(pk=slot_pk).duration, 2,
                          msg="Slot was not correctly changed")
 
+        # Delete recently created slot: Make sure view is accessible, post deletion
+        # -> redirect to detail page, slot deleted, message to user
         deletion_url = reverse_lazy(f"{self.APP_NAME}:akslot_delete", kwargs={'event_slug': 'kif42', 'pk': slot_pk})
         response = self.client.get(deletion_url)
         self.assertEqual(response.status_code, 200,
@@ -95,55 +111,77 @@ class ModelViewTests(BasicViewTests, TestCase):
         self.assertEqual(AK.objects.get(pk=1).akslot_set.count(), count_slots, msg="AK still has to many slots")
 
     def test_ak_owner_editing(self):
-        # Test editing of new user
+        """
+        Test dispatch of user editing requests
+        """
         edit_url = reverse_lazy(f"{self.APP_NAME}:akowner_edit_dispatch", kwargs={'event_slug': 'kif42'})
 
         base_url = reverse_lazy(f"{self.APP_NAME}:submission_overview", kwargs={'event_slug': 'kif42'})
+
+        # Empty form/no user selected -> start page
         response = self.client.post(edit_url, {'owner_id': -1})
         self.assertRedirects(response, base_url, status_code=302, target_status_code=200,
                              msg_prefix="Did not redirect to start page even though no user was selected")
         self._assert_message(response, "No user selected")
 
+        # Correct selection -> user edit page for that user
         edit_redirect_url = reverse_lazy(f"{self.APP_NAME}:akowner_edit", kwargs={'event_slug': 'kif42', 'slug': 'a'})
         response = self.client.post(edit_url, {'owner_id': 1})
         self.assertRedirects(response, edit_redirect_url, status_code=302, target_status_code=200,
                              msg_prefix=f"Dispatch redirect failed (should go to {edit_redirect_url})")
 
     def test_ak_owner_selection(self):
+        """
+        Test dispatch of owner selection requests
+        """
         select_url = reverse_lazy(f"{self.APP_NAME}:akowner_select", kwargs={'event_slug': 'kif42'})
-
         create_url = reverse_lazy(f"{self.APP_NAME}:akowner_create", kwargs={'event_slug': 'kif42'})
+
+        # Empty user selection -> create a new user view
         response = self.client.post(select_url, {'owner_id': -1})
         self.assertRedirects(response, create_url, status_code=302, target_status_code=200,
                              msg_prefix="Did not redirect to user create view even though no user was specified")
 
+        # Valid user selected -> redirect to view that allows to add a new AK with this user as owner
         add_redirect_url = reverse_lazy(f"{self.APP_NAME}:submit_ak", kwargs={'event_slug': 'kif42', 'owner_slug': 'a'})
         response = self.client.post(select_url, {'owner_id': 1})
         self.assertRedirects(response, add_redirect_url, status_code=302, target_status_code=200,
                     msg_prefix=f"Dispatch redirect to ak submission page failed (should go to {add_redirect_url})")
 
     def test_orga_message_submission(self):
+        """
+        Test submission and storing of direct confident messages to organizers
+        """
         form_url = reverse_lazy(f"{self.APP_NAME}:akmessage_add", kwargs={'event_slug': 'kif42', 'pk': 1})
         detail_url = reverse_lazy(f"{self.APP_NAME}:ak_detail", kwargs={'event_slug': 'kif42', 'pk': 1})
 
         count_messages = AK.objects.get(pk=1).akorgamessage_set.count()
 
+        # Test that submission view is accessible
         response = self.client.get(form_url)
         self.assertEqual(response.status_code, 200, msg="Could not load message form view")
+
+        # Test submission itself and the following redirect -> AK detail page
         response = self.client.post(form_url, {'ak': 1, 'event': 2, 'text': 'Test message text'})
         self.assertRedirects(response, detail_url, status_code=302, target_status_code=200,
                              msg_prefix=f"Did not trigger redirect to ak detail page ({detail_url})")
+
+        # Make sure message was correctly saved in database and user is notified about that
         self._assert_message(response, "Message to organizers successfully saved")
         self.assertEqual(AK.objects.get(pk=1).akorgamessage_set.count(), count_messages + 1,
                          msg="Message was not correctly saved")
 
     def test_interest_api(self):
+        """
+        Test interest indicating API (access, functionality)
+        """
         interest_api_url = "/kif42/api/ak/1/indicate-interest/"
 
         ak = AK.objects.get(pk=1)
         event = Event.objects.get(slug='kif42')
         ak_interest_counter = ak.interest_counter
 
+        # Check Access method (only POST)
         response = self.client.get(interest_api_url)
         self.assertEqual(response.status_code, 405, "Should not be accessible via GET")
 
@@ -151,6 +189,7 @@ class ModelViewTests(BasicViewTests, TestCase):
         event.interest_end = datetime.now().astimezone(event.timezone) + timedelta(minutes=+10)
         event.save()
 
+        # Test correct indication -> HTTP 200, counter increased
         response = self.client.post(interest_api_url)
         self.assertEqual(response.status_code, 200, f"API end point not working ({interest_api_url})")
         self.assertEqual(AK.objects.get(pk=1).interest_counter, ak_interest_counter + 1, "Counter was not increased")
@@ -158,30 +197,41 @@ class ModelViewTests(BasicViewTests, TestCase):
         event.interest_end = datetime.now().astimezone(event.timezone) + timedelta(minutes=-2)
         event.save()
 
+        # Test indication outside of indication window -> HTTP 403, counter not increased
         response = self.client.post(interest_api_url)
         self.assertEqual(response.status_code, 403,
                     "API end point still reachable even though interest indication window ended ({interest_api_url})")
         self.assertEqual(AK.objects.get(pk=1).interest_counter, ak_interest_counter + 1,
                          "Counter was increased even though interest indication window ended")
 
+        # Test call for non-existing AK -> HTTP 403
         invalid_interest_api_url = "/kif42/api/ak/-1/indicate-interest/"
         response = self.client.post(invalid_interest_api_url)
         self.assertEqual(response.status_code, 404, f"Invalid URL reachable ({interest_api_url})")
 
     def test_adding_of_unknown_user(self):
+        """
+        Test adding of a previously not existing owner to an AK
+        """
+        # Pre-Check: AK detail page existing?
         detail_url = reverse_lazy(f"{self.APP_NAME}:ak_detail", kwargs={'event_slug': 'kif42', 'pk': 1})
         response = self.client.get(detail_url)
         self.assertEqual(response.status_code, 200, msg="Could not load ak detail view")
 
+        # Make sure AK detail page contains a link to add a new owner
         edit_url = reverse_lazy(f"{self.APP_NAME}:ak_edit", kwargs={'event_slug': 'kif42', 'pk': 1})
         response = self.client.get(edit_url)
         self.assertEqual(response.status_code, 200, msg="Could not load ak detail view")
         self.assertContains(response, "Add person not in the list yet",
                             msg_prefix="Link to add unknown user not contained")
 
+        # Check adding of a new owner by posting an according request
+        # -> Redirect to AK detail page, message to user, owners list updated
         self.assertEqual(AK.objects.get(pk=1).owners.count(), 1)
-        add_new_user_to_ak_url = reverse_lazy(f"{self.APP_NAME}:akowner_create", kwargs={'event_slug': 'kif42'}) + f"?add_to_existing_ak=1"
-        response = self.client.post(add_new_user_to_ak_url, {'name': 'New test owner', 'event': Event.get_by_slug('kif42').pk})
+        add_new_user_to_ak_url = reverse_lazy(f"{self.APP_NAME}:akowner_create", kwargs={'event_slug': 'kif42'}) \
+                                 + "?add_to_existing_ak=1"
+        response = self.client.post(add_new_user_to_ak_url,
+                                    {'name': 'New test owner', 'event': Event.get_by_slug('kif42').pk})
         self.assertRedirects(response, detail_url,
                              msg_prefix=f"No correct redirect: {add_new_user_to_ak_url} (POST) -> {detail_url}")
         self._assert_message(response, "Added 'New test owner' as new owner of 'Test AK Inhalt'")

AKSubmission/views.py

 from datetime import timedelta
 from math import floor
+from abc import ABC, abstractmethod
 
 from django.apps import apps
 from django.conf import settings
@@ -23,27 +24,74 @@ from AKSubmission.forms import AKWishForm, AKOwnerForm, AKSubmissionForm, AKDura
 
 
 class SubmissionErrorNotConfiguredView(EventSlugMixin, TemplateView):
+    """
+    View to show when submission is not correctly configured yet for this event
+    and hence the submission component cannot be used already.
+    """
     template_name = "AKSubmission/submission_not_configured.html"
 
 
 class AKOverviewView(FilterByEventSlugMixin, ListView):
+    """
+    View: Show a tabbed list of AKs belonging to this event split by categories
+
+    Wishes show up in between of the other AKs in the category they belong to.
+    In contrast to :class:`SubmissionOverviewView` that inherits from this view,
+    on this view there is no form to add new AKs or edit owners.
+
+    Since the inherited version of this view will have a slightly different behaviour,
+    this view contains multiple methods that can be overriden for this adaption.
+    """
     model = AKCategory
     context_object_name = "categories"
     template_name = "AKSubmission/ak_overview.html"
     wishes_as_category = False
 
-    def filter_aks(self, context, category):
+    def filter_aks(self, context, category): # pylint: disable=unused-argument
+        """
+        Filter which AKs to display based on the given context and category
+
+        In the default case, all AKs of that category are returned (including wishes)
+
+        :param context: context of the view
+        :param category: category to filter the AK list for
+        :return: filtered list of AKs for the given category
+        :rtype: QuerySet[AK]
+        """
+        # Use prefetching and relation selection/joining to reduce the amount of necessary queries
         return category.ak_set.select_related('event').prefetch_related('owners').all()
 
     def get_active_category_name(self, context):
+        """
+        Get the category name to display by default/before further user interaction
+
+        In the default case, simply the first category (the one with the lowest ID for this event) is used
+
+        :param context: context of the view
+        :return: name of the default category
+        :rtype: str
+        """
         return context["categories_with_aks"][0][0].name
 
-    def get_table_title(self, context):
+    def get_table_title(self, context): # pylint: disable=unused-argument
+        """
+        Specify the title above the AK list/table in this view
+
+        :param context: context of the view
+        :return: title to use
+        :rtype: str
+        """
         return _("All AKs")
 
     def get(self, request, *args, **kwargs):
+        """
+        Handle GET request
+
+        Overriden to allow checking for correct configuration and
+        redirect to error page if necessary (see :class:`SubmissionErrorNotConfiguredView`)
+        """
         self._load_event()
-        self.object_list = self.get_queryset()
+        self.object_list = self.get_queryset() # pylint: disable=attribute-defined-outside-init
 
         # No categories yet? Redirect to configuration error page
         if self.object_list.count() == 0:
@@ -55,10 +103,16 @@ class AKOverviewView(FilterByEventSlugMixin, ListView):
     def get_context_data(self, *, object_list=None, **kwargs):
         context = super().get_context_data(object_list=object_list, **kwargs)
 
+        # ==========================================================
         # Sort AKs into different lists (by their category)
+        # ==========================================================
         ak_wishes = []
         categories_with_aks = []
 
+        # Loop over categories, load AKs (while filtering them if necessary) and create a list of (category, aks)-tuples
+        # Depending on the setting of self.wishes_as_category, wishes are either included
+        # or added to a special "Wish"-Category that is created on-the-fly to provide consistent handling in the
+        # template (without storing it in the database)
         for category in context["categories"]:
             aks_for_category = []
             for ak in self.filter_aks(context, category):
@@ -76,7 +130,9 @@ class AKOverviewView(FilterByEventSlugMixin, ListView):
         context["active_category"] = self.get_active_category_name(context)
         context['table_title'] = self.get_table_title(context)
 
+        # ==========================================================
         # Display interest indication button?
+        # ==========================================================
         current_timestamp = datetime.now().astimezone(self.event.timezone)
         context['interest_indication_active'] = ak_interest_indication_active(self.event, current_timestamp)
 
@@ -84,12 +140,30 @@ class AKOverviewView(FilterByEventSlugMixin, ListView):
 
 
 class SubmissionOverviewView(AKOverviewView):
+    """
+    View: List of AKs and possibility to add AKs or adapt owner information
+
+    Main/start view of the component.
+
+    This view inherits from :class:`AKOverviewView`, but treats wishes as separate category if requested in the settings
+    and handles the change actions mentioned above.
+    """
     model = AKCategory
     context_object_name = "categories"
     template_name = "AKSubmission/submission_overview.html"
+
+    # this mainly steers the different handling of wishes
+    # since the code for that is already included in the parent class
     wishes_as_category = settings.WISHES_AS_CATEGORY
 
     def get_table_title(self, context):
+        """
+        Specify the title above the AK list/table in this view
+
+        :param context: context of the view
+        :return: title to use
+        :rtype: str
+        """
         return _("Currently planned AKs")
 
     def get_context_data(self, *, object_list=None, **kwargs):
@@ -102,32 +176,71 @@ class SubmissionOverviewView(AKOverviewView):
 
 
 class AKListByCategoryView(AKOverviewView):
+    """
+    View: List of only the AKs belonging to a certain category.
+
+    This view inherits from :class:`AKOverviewView`, but produces only one list instead of a tabbed one.
+    """
     def dispatch(self, request, *args, **kwargs):
-        self.category = get_object_or_404(AKCategory, pk=kwargs['category_pk'])
+        # Override dispatching
+        # Needed to handle the checking whether the category exists
+        self.category = get_object_or_404(AKCategory, pk=kwargs['category_pk']) # pylint: disable=attribute-defined-outside-init,line-too-long
         return super().dispatch(request, *args, **kwargs)
 
     def get_active_category_name(self, context):
+        """
+        Get the category name to display by default/before further user interaction
+
+        In this case, this will be the name of the category specified via pk
+
+        :param context: context of the view
+        :return: name of the category
+        :rtype: str
+        """
         return self.category.name
 
 
 class AKListByTrackView(AKOverviewView):
+    """
+    View: List of only the AKs belonging to a certain track.
+
+    This view inherits from :class:`AKOverviewView` and there will be one list per category
+    -- but only AKs of a certain given track will be included in them.
+    """
     def dispatch(self, request, *args, **kwargs):
-        self.track = get_object_or_404(AKTrack, pk=kwargs['track_pk'])
+        # Override dispatching
+        # Needed to handle the checking whether the track exists
+
+        self.track = get_object_or_404(AKTrack, pk=kwargs['track_pk']) # pylint: disable=attribute-defined-outside-init
         return super().dispatch(request, *args, **kwargs)
 
     def filter_aks(self, context, category):
-        return category.ak_set.filter(track=self.track)
+        """
+        Filter which AKs to display based on the given context and category
+
+        In this case, the list is further restricted by the track
+
+        :param context: context of the view
+        :param category: category to filter the AK list for
+        :return: filtered list of AKs for the given category
+        :rtype: QuerySet[AK]
+        """
+        return super().filter_aks(context, category).filter(track=self.track)
 
     def get_table_title(self, context):
         return f"{_('AKs with Track')} = {self.track.name}"
 
 
 class AKDetailView(EventSlugMixin, DetailView):
+    """
+    View: AK Details
+    """
     model = AK
     context_object_name = "ak"
     template_name = "AKSubmission/ak_detail.html"
 
     def get_queryset(self):
+        # Get information about the AK and do some query optimization
         return super().get_queryset().select_related('event').prefetch_related('owners')
 
     def get_context_data(self, *, object_list=None, **kwargs):
@@ -163,29 +276,34 @@ class AKDetailView(EventSlugMixin, DetailView):
 
 
 class AKHistoryView(EventSlugMixin, DetailView):
+    """
+    View: Show history of a given AK
+    """
     model = AK
     context_object_name = "ak"
     template_name = "AKSubmission/ak_history.html"
 
 
-class AKListView(FilterByEventSlugMixin, ListView):
-    model = AK
-    context_object_name = "AKs"
-    template_name = "AKSubmission/ak_overview.html"
-    table_title = ""
-
-    def get_context_data(self, *, object_list=None, **kwargs):
-        context = super().get_context_data(object_list=object_list, **kwargs)
-        context['categories'] = AKCategory.objects.filter(event=self.event)
-        context['tracks'] = AKTrack.objects.filter(event=self.event)
-        return context
-
-
 class EventInactiveRedirectMixin:
+    """
+    Mixin that will cause a redirect when actions are performed on an inactive event.
+    Will add a message explaining why the action was not performed to the user
+    and then redirect to start page of the submission component
+    """
     def get_error_message(self):
+        """
+        Error message to display after redirect (can be adjusted by this method)
+
+        :return: error message
+        :rtype: str
+        """
         return _("Event inactive. Cannot create or update.")
 
     def get(self, request, *args, **kwargs):
+        """
+        Override GET request handling
+        Will either perform the redirect including the message creation or continue with the planned dispatching
+        """
         s = super().get(request, *args, **kwargs)
         if not self.event.active:
             messages.add_message(self.request, messages.ERROR, self.get_error_message())
@@ -194,6 +312,11 @@ class EventInactiveRedirectMixin:
 
 
 class AKAndAKWishSubmissionView(EventSlugMixin, EventInactiveRedirectMixin, CreateView):
+    """
+    View: Submission form for AKs and Wishes
+
+    Base view, will be used by :class:`AKSubmissionView` and :class:`AKWishSubmissionView`
+    """
     model = AK
     template_name = 'AKSubmission/submit_new.html'
     form_class = AKSubmissionForm
@@ -221,7 +344,14 @@ class AKAndAKWishSubmissionView(EventSlugMixin, EventInactiveRedirectMixin, Crea
 
 
 class AKSubmissionView(AKAndAKWishSubmissionView):
+    """
+    View: AK submission form
+
+    Extends :class:`AKAndAKWishSubmissionView`
+    """
     def get_initial(self):
+        # Load initial values for the form
+        # Used to directly add the first owner and the event this AK will belong to
         initials = super(AKAndAKWishSubmissionView, self).get_initial()
         initials['owners'] = [AKOwner.get_by_slug(self.event, self.kwargs['owner_slug'])]
         initials['event'] = self.event
@@ -234,33 +364,54 @@ class AKSubmissionView(AKAndAKWishSubmissionView):
 
 
 class AKWishSubmissionView(AKAndAKWishSubmissionView):
+    """
+    View: Wish submission form
+
+    Extends :class:`AKAndAKWishSubmissionView`
+    """
     template_name = 'AKSubmission/submit_new_wish.html'
     form_class = AKWishForm
 
     def get_initial(self):
+        # Load initial values for the form
+        # Used to directly select the event this AK will belong to
         initials = super(AKAndAKWishSubmissionView, self).get_initial()
         initials['event'] = self.event
         return initials
 
 
 class AKEditView(EventSlugMixin, EventInactiveRedirectMixin, UpdateView):
+    """
+    View: Update an AK
+
+    This allows to change most fields of an AK as specified in :class:`AKSubmission.forms.AKForm`,
+    including the availabilities.
+    It will also handle the change from AK to wish and vice versa (triggered by adding or removing owners)
+    and automatically create or delete (unscheduled) slots
+    """
     model = AK
     template_name = 'AKSubmission/ak_edit.html'
     form_class = AKForm
 
     def get_success_url(self):
+        # Redirection after successfully saving to detail page of AK where also a success message is displayed
         messages.add_message(self.request, messages.SUCCESS, _("AK successfully updated"))
         return self.object.detail_url
 
     def form_valid(self, form):
+        # Handle valid form submission
+
+        # Only save when event is active, otherwise redirect
         if not form.cleaned_data["event"].active:
             messages.add_message(self.request, messages.ERROR, self.get_error_message())
             return redirect(reverse_lazy('submit:submission_overview',
                                          kwargs={'event_slug': form.cleaned_data["event"].slug}))
 
+        # Remember owner count before saving to know whether the AK changed its state between AK and wish
         previous_owner_count = self.object.owners.count()
 
-        super_form_valid = super().form_valid(form)
+        # Perform saving and redirect handling by calling default/parent implementation of form_valid
+        redirect_response = super().form_valid(form)
 
         # Did this AK change from wish to AK or vice versa?
         new_owner_count = self.object.owners.count()
@@ -273,15 +424,23 @@ class AKEditView(EventSlugMixin, EventInactiveRedirectMixin, UpdateView):
             # Delete all unscheduled slots
             self.object.akslot_set.filter(start__isnull=True).delete()
 
-        return super_form_valid
+        # Redirect to success url
+        return redirect_response
 
 
 class AKOwnerCreateView(EventSlugMixin, EventInactiveRedirectMixin, CreateView):
+    """
+    View: Create a new owner
+    """
     model = AKOwner
     template_name = 'AKSubmission/akowner_create_update.html'
     form_class = AKOwnerForm
 
     def get_success_url(self):
+        # The redirect url depends on the source this view was called from:
+
+        # Called from an existing AK? Add the new owner as an owner of that AK, notify the user and redirect to detail
+        # page of that AK
         if "add_to_existing_ak" in self.request.GET:
             ak_pk = self.request.GET['add_to_existing_ak']
             ak = get_object_or_404(AK, pk=ak_pk)
@@ -289,15 +448,20 @@ class AKOwnerCreateView(EventSlugMixin, EventInactiveRedirectMixin, CreateView):
             messages.add_message(self.request, messages.SUCCESS,
                                  _("Added '{owner}' as new owner of '{ak.name}'").format(owner=self.object, ak=ak))
             return ak.detail_url
+
+        # Called from the submission overview? Offer the user to create a new AK with the recently created owner
+        # prefilled as owner of that AK in the creation form
         return reverse_lazy('submit:submit_ak',
                             kwargs={'event_slug': self.kwargs['event_slug'], 'owner_slug': self.object.slug})
 
     def get_initial(self):
-        initials = super(AKOwnerCreateView, self).get_initial()
+        # Set the event in the (hidden) event field in the form based on the URL this view was called with
+        initials = super().get_initial()
         initials['event'] = self.event
         return initials
 
     def form_valid(self, form):
+        # Prevent changes if event is not active
         if not form.cleaned_data["event"].active:
             messages.add_message(self.request, messages.ERROR, self.get_error_message())
             return redirect(reverse_lazy('submit:submission_overview',
@@ -305,29 +469,98 @@ class AKOwnerCreateView(EventSlugMixin, EventInactiveRedirectMixin, CreateView):
         return super().form_valid(form)
 
 
-class AKOwnerSelectDispatchView(EventSlugMixin, View):
+class AKOwnerDispatchView(ABC, EventSlugMixin, View):
     """
-    This view only serves as redirect to prepopulate the owners field in submission create view
+    Base view: Dispatch to correct view based upon
+
+    Will be used by :class:`AKOwnerSelectDispatchView` and :class:`AKOwnerEditDispatchView` to handle button clicks for
+    "New AK" and "Edit Person Info" in submission overview based upon the selection in the owner dropdown field
+    """
+
+    @abstractmethod
+    def get_new_owner_redirect(self, event_slug):
+        """
+        Get redirect when user selected "I do not own AKs yet"
+
+        :param event_slug: slug of the event, needed for constructing redirect
+        :return: redirect to perform
+        :rtype: HttpResponseRedirect
         """
 
+    @abstractmethod
+    def get_valid_owner_redirect(self, event_slug, owner):
+        """
+        Get redirect when user selected "I do not own AKs yet"
+
+        :param event_slug: slug of the event, needed for constructing redirect
+        :param owner: owner to perform the dispatching for
+        :return: redirect to perform
+        :rtype: HttpResponseRedirect
+        """
+
+
     def post(self, request, *args, **kwargs):
+        # This view is solely meant to handle POST requests
+        # Perform dispatching based on the submitted owner_id
+
+        # No owner_id? Redirect to submission overview view
         if "owner_id" not in request.POST:
             return redirect('submit:submission_overview', event_slug=kwargs['event_slug'])
         owner_id = request.POST["owner_id"]
 
+        # Special owner_id "-1" (value of "I do not own AKs yet)? Redirect to owner creation view
         if owner_id == "-1":
-            return HttpResponseRedirect(
-                reverse_lazy('submit:akowner_create', kwargs={'event_slug': kwargs['event_slug']}))
+            return self.get_new_owner_redirect(kwargs['event_slug'])
 
+        # Normal owner_id given? Check vor validity and redirect to AK submission page with that owner prefilled
+        # or display a 404 error page if no owner for the given id can be found. The latter should only happen when the
+        # user manipulated the value before sending or when the owner was deleted in backend and the user did not
+        # reload the dropdown between deletion and sending the dispatch request
         owner = get_object_or_404(AKOwner, pk=request.POST["owner_id"])
-        return HttpResponseRedirect(
-            reverse_lazy('submit:submit_ak', kwargs={'event_slug': kwargs['event_slug'], 'owner_slug': owner.slug}))
+        return self.get_valid_owner_redirect(kwargs['event_slug'], owner)
 
     def get(self, request, *args, **kwargs):
+        # This view should never be called with GET, perform a redirect to overview in that case
         return redirect('submit:submission_overview', event_slug=kwargs['event_slug'])
 
 
-class AKOwnerEditView(FilterByEventSlugMixin, EventSlugMixin, UpdateView):
+class AKOwnerSelectDispatchView(AKOwnerDispatchView):
+    """
+    View: Handle submission from the owner selection dropdown in submission overview for AK creation
+    ("New AK" button)
+
+    This view will perform redirects depending on the selection in the owner dropdown field.
+    Based upon the abstract base view :class:`AKOwnerDispatchView`.
+    """
+
+    def get_new_owner_redirect(self, event_slug):
+        return redirect('submit:akowner_create', event_slug=event_slug)
+
+    def get_valid_owner_redirect(self, event_slug, owner):
+        return redirect('submit:submit_ak', event_slug=event_slug, owner_slug=owner.slug)
+
+
+class AKOwnerEditDispatchView(AKOwnerDispatchView):
+    """
+    View: Handle submission from the owner selection dropdown in submission overview for owner editing
+    ("Edit Person Info" button)
+
+    This view will perform redirects depending on the selection in the owner dropdown field.
+    Based upon the abstract base view :class:`AKOwnerDispatchView`.
+    """
+
+    def get_new_owner_redirect(self, event_slug):
+        messages.add_message(self.request, messages.WARNING, _("No user selected"))
+        return redirect('submit:submission_overview', event_slug)
+
+    def get_valid_owner_redirect(self, event_slug, owner):
+        return redirect('submit:akowner_edit', event_slug=event_slug, slug=owner.slug)
+
+
+class AKOwnerEditView(FilterByEventSlugMixin, EventSlugMixin, EventInactiveRedirectMixin, UpdateView):
+    """
+    View: Edit an owner
+    """
     model = AKOwner
     template_name = "AKSubmission/akowner_create_update.html"
     form_class = AKOwnerForm
@@ -337,6 +570,7 @@ class AKOwnerEditView(FilterByEventSlugMixin, EventSlugMixin, UpdateView):
         return reverse_lazy('submit:submission_overview', kwargs={'event_slug': self.kwargs['event_slug']})
 
     def form_valid(self, form):
+        # Prevent updating if event is not active
         if not form.cleaned_data["event"].active:
             messages.add_message(self.request, messages.ERROR, self.get_error_message())
             return redirect(reverse_lazy('submit:submission_overview',
@@ -344,36 +578,19 @@ class AKOwnerEditView(FilterByEventSlugMixin, EventSlugMixin, UpdateView):
         return super().form_valid(form)
 
 
-class AKOwnerEditDispatchView(EventSlugMixin, View):
-    """
-    This view only serves as redirect choose the correct edit view
+class AKSlotAddView(EventSlugMixin, EventInactiveRedirectMixin, CreateView):
     """
+    View: Add an additional slot to an AK
+    The user has to select the duration of the slot in this view
 
-    def post(self, request, *args, **kwargs):
-        if "owner_id" not in request.POST:
-            return redirect('submit:submission_overview', event_slug=kwargs['event_slug'])
-        owner_id = request.POST["owner_id"]
-
-        if owner_id == "-1":
-            messages.add_message(self.request, messages.WARNING, _("No user selected"))
-            return HttpResponseRedirect(
-                reverse_lazy('submit:submission_overview', kwargs={'event_slug': kwargs['event_slug']}))
-
-        owner = get_object_or_404(AKOwner, pk=request.POST["owner_id"])
-        return HttpResponseRedirect(
-            reverse_lazy('submit:akowner_edit', kwargs={'event_slug': kwargs['event_slug'], 'slug': owner.slug}))
-
-    def get(self, request, *args, **kwargs):
-        return redirect('submit:submission_overview', event_slug=kwargs['event_slug'])
-
-
-class AKSlotAddView(EventSlugMixin, EventInactiveRedirectMixin, CreateView):
+    The view will only process the request when the event is active (as steered by :class:`EventInactiveRedirectMixin`)
+    """
     model = AKSlot
     form_class = AKDurationForm
     template_name = "AKSubmission/akslot_add_update.html"
 
     def get_initial(self):
-        initials = super(AKSlotAddView, self).get_initial()
+        initials = super().get_initial()
         initials['event'] = self.event
         initials['ak'] = get_object_or_404(AK, pk=self.kwargs['pk'])
         initials['duration'] = self.event.default_slot
@@ -390,6 +607,12 @@ class AKSlotAddView(EventSlugMixin, EventInactiveRedirectMixin, CreateView):
 
 
 class AKSlotEditView(EventSlugMixin, EventInactiveRedirectMixin, UpdateView):
+    """
+    View: Update the duration of an AK slot
+
+    The view will only process the request when the event is active (as steered by :class:`EventInactiveRedirectMixin`)
+    and only slots that are not scheduled yet may be changed
+    """
     model = AKSlot
     form_class = AKDurationForm
     template_name = "AKSubmission/akslot_add_update.html"
@@ -413,6 +636,12 @@ class AKSlotEditView(EventSlugMixin, EventInactiveRedirectMixin, UpdateView):
 
 
 class AKSlotDeleteView(EventSlugMixin, EventInactiveRedirectMixin, DeleteView):
+    """
+    View: Delete an AK slot
+
+    The view will only process the request when the event is active (as steered by :class:`EventInactiveRedirectMixin`)
+    and only slots that are not scheduled yet may be deleted
+    """
     model = AKSlot
     template_name = "AKSubmission/akslot_delete.html"
 
@@ -436,6 +665,11 @@ class AKSlotDeleteView(EventSlugMixin, EventInactiveRedirectMixin, DeleteView):
 
 @status_manager.register(name="event_ak_messages")
 class EventAKMessagesWidget(TemplateStatusWidget):
+    """
+    Status page widget: AK Messages
+
+    A widget to display information about AK-related messages sent to organizers for the given event
+    """
     required_context_type = "event"
     title = _("Messages")
     template_name = "admin/AKModel/render_ak_messages.html"
@@ -454,12 +688,16 @@ class EventAKMessagesWidget(TemplateStatusWidget):
 
 
 class AKAddOrgaMessageView(EventSlugMixin, CreateView):
+    """
+    View: Form to create a (confidential) message to the organizers as defined in
+    :class:`AKSubmission.forms.AKOrgaMessageForm`
+    """
     model = AKOrgaMessage
     form_class = AKOrgaMessageForm
     template_name = "AKSubmission/akmessage_add.html"
 
     def get_initial(self):
-        initials = super(AKAddOrgaMessageView, self).get_initial()
+        initials = super().get_initial()
         initials['ak'] = get_object_or_404(AK, pk=self.kwargs['pk'])
         initials['event'] = initials['ak'].event
         return initials

CONTRIBUTING.md

@@ -61,7 +61,7 @@ Provide more context by answering these questions:
 
 Include details about your configuration and environment:
 
-* **Which version (commit)) are you using?**
+* **Which version (commit) are you using?**
 * **What's the OS you're using**?
 
 ### Suggesting Enhancements

Utils/setup.sh

@@ -15,6 +15,14 @@ source venv/bin/activate
 pip install --upgrade setuptools pip wheel
 pip install -r requirements.txt
 
+# set environment variable when we want to update in production
+if [ "$1" = "--prod" ]; then
+    export DJANGO_SETTINGS_MODULE=AKPlanning.settings_production
+fi
+if [ "$1" = "--ci" ]; then
+    export DJANGO_SETTINGS_MODULE=AKPlanning.settings_ci
+fi
+
 # Setup database
 python manage.py migrate
 
@@ -26,4 +34,12 @@ python manage.py compilemessages -l de_DE
 # Credentials are entered interactively on CLI
 python manage.py createsuperuser
 
+# Generate documentation (but not for CI use)
+if [ -n "$1" = "--ci" ]; then
+    cd docs
+    make html
+    cd ..
+fi
+
+
 deactivate

Utils/update.sh

@@ -27,4 +27,10 @@ pip install --upgrade -r requirements.txt
 ./manage.py collectstatic --noinput
 ./manage.py compilemessages -l de_DE
 
+
+# Update documentation
+cd docs
+make html
+cd ..
+
 touch AKPlanning/wsgi.py

docs/.gitignore

+_build/
+code/

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     = .
+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)

docs/code.rst

+Code
+=====
+
+.. toctree::
+    code/AKDashboard
+    code/AKModel
+    code/AKOnline
+    code/AKPlan
+    code/AKScheduling
+    code/AKSubmission

docs/conf.py

+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import os
+import sys
+from recommonmark.parser import CommonMarkParser
+import django
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'AK Planning'
+copyright = '2023, N. Geisler, B. Hättasch & more'
+author = 'N. Geisler, B. Hättasch & more'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinxcontrib.apidoc',   # runs sphinx-apidoc automatically as part of sphinx-build
+    'sphinx.ext.autodoc',     # the autodoc extensions uses files generated by apidoc
+    "sphinx.ext.autosummary",
+    "sphinxcontrib_django",
+    'sphinx.ext.viewcode',    # enable viewing autodoc'd code
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Django specific settings ------------------------------------------------
+
+# Add source directory to sys.path
+sys.path.insert(0, os.path.abspath(".."))
+
+# Configure the path to the Django settings module
+django_settings = "AKPlanning.settings"
+os.environ['DJANGO_SETTINGS_MODULE'] = django_settings
+
+django.setup()
+
+# Include the database table names of Django models
+django_show_db_tables = True                # Boolean, default: False
+# Add abstract database tables names (only takes effect if django_show_db_tables is True)
+django_show_db_tables_abstract = True       # Boolean, default: False
+
+# Auto-generate API documentation.
+os.environ['SPHINX_APIDOC_OPTIONS'] = "members,show-inheritance"
+
+# -- Input ----
+
+source_parsers = {
+    '.md': CommonMarkParser,
+}
+
+source_suffix = ['.rst', '.md']
+
+# -- Extension Conf ----
+
+autodoc_member_order = 'bysource'
+autodoc_inherit_docstrings = False
+
+apidoc_module_dir = '../'
+apidoc_output_dir = 'code'
+apidoc_excluded_paths = ['*/migrations',
+                         'AKPlanning/',
+                         'manage.py',
+                         'docs',
+                         'locale',
+                         'Utils',
+                         '*/urls.py',
+                         ]
+apidoc_separate_modules = True
+apidoc_toc_file = False
+apidoc_module_first = True
+apidoc_extra_args = ['-f']
+apidoc_project = project
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_static_path = ['_static']
+html_theme = 'sphinx_rtd_theme'

docs/index.rst

+.. AK Planning documentation master file, created by
+   sphinx-quickstart on Wed Jun 21 09:54:11 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Start
+=======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   usage/usage
+   code
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

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

docs/usage/usage.rst

+Usage
+=====
+
+.. toctree::
+

locale/de_DE/LC_MESSAGES/django.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-05-15 20:05+0200\n"
+"POT-Creation-Date: 2023-08-16 16:30+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -27,11 +27,15 @@ msgstr "Wirklich jetzt die Sprache ändern? Das wird das Formular zurücksetzen!
 msgid "Go to backend"
 msgstr "Zum Backend"
 
-#: templates/base.html:114
+#: templates/base.html:109
+msgid "Docs"
+msgstr "Doku"
+
+#: templates/base.html:115
 msgid "Impress"
 msgstr "Impressum"
 
-#: templates/base.html:117
+#: templates/base.html:118
 msgid "This software is open source"
 msgstr "Diese Software ist Open Source"
 

pylintrc

+[MAIN]
+
+ignore=urls.py, migrations, AKPlanning
+
+load-plugins=
+    pylint_django,
+    pylint_django.checkers.migrations
+
+django-settings-module=AKPlanning.settings
+
+disable=
+    C0114, # missing-module-docstring
+
+
+[FORMAT]
+
+# Maximum number of characters on a single line.
+max-line-length=120
+
+indent-string='    '
+
+
+
+[SIMILARITIES]
+
+# Minimum lines number of a similarity.
+min-similarity-lines=6
+
+# Ignore comments when computing similarities.
+ignore-comments=yes
+
+# Ignore docstrings when computing similarities.
+ignore-docstrings=yes
+
+# Ignore imports when computing similarities.
+ignore-imports=yes
+
+# Signatures are removed from the similarity computation
+ignore-signatures=yes
+
+
+[BASIC]
+
+# Regular expression matching correct module names
+module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+)|((tags_)*AK[A-Z][a-z0-9_]+))$
+
+# Good variable names which should always be accepted, separated by a comma
+good-names=i,j,k,a,e,ak,tz,_,pk
+
+# Allow single-letter variables and enforce lowercase variables with underscores otherwise
+variable-rgx=[a-z_][a-z0-9_]{0,30}$
+
+
+[TYPECHECK]
+
+# Tells whether missing members accessed in mixin class should be ignored. A
+# mixin class is detected if its name ends with "mixin" (case insensitive).
+ignore-mixin-members=yes
+
+# List of classes names for which member attributes should not be checked
+# (useful for classes with attributes dynamically set).
+ignored-classes=SQLObject,WSGIRequest
+
+# List of members which are set dynamically and missed by pylint inference
+# system, and so shouldn't trigger E0201 when accessed.
+generated-members=objects,DoesNotExist,id,pk,_meta,base_fields,context
+
+# List of method names used to declare (i.e. assign) instance attributes
+defining-attr-methods=__init__,__new__,setUp
+
+
+[DESIGN]
+
+max-parents=15
+
+max-args=8

requirements.txt

@@ -16,3 +16,11 @@ django-libsass==0.9
 django-betterforms==2.0.0
 mysqlclient==2.2.0  # for production deployment
 tzdata==2023.3
+
+# Documentation
+sphinxcontrib-django==2.3
+sphinxcontrib-apidoc==0.3.0
+recommonmark==0.7.1
+django-docs==0.3.3
+sphinx-rtd-theme==1.2.2
+sphinx==6.2.1
\ No newline at end of file

setup.cfg

+[pycodestyle]
+max-line-length = 120
+exclude = migrations,static
+max-complexity = 11