AKOnline/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-03-26 19:51+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"
@@ -34,7 +34,7 @@ msgstr "Raum"
 msgid "Virtual Room"
 msgstr "Virtueller Raum"
 
-#: AKOnline/models.py:17 AKOnline/views.py:27
+#: AKOnline/models.py:17 AKOnline/views.py:38
 msgid "Virtual Rooms"
 msgstr "Virtuelle Räume"
 
@@ -42,12 +42,12 @@ msgstr "Virtuelle Räume"
 msgid "Leave empty if that room is not virtual/hybrid."
 msgstr "Leer lassen wenn der Raum nicht virtuell/hybrid ist"
 
-#: AKOnline/views.py:18
+#: AKOnline/views.py:25
 #, python-format
 msgid "Created Room '%(room)s'"
 msgstr "Raum '%(room)s' angelegt"
 
-#: AKOnline/views.py:20
+#: AKOnline/views.py:28
 #, python-format
 msgid "Created related Virtual Room '%(vroom)s'"
 msgstr "Verbundenen virtuellen Raum '%(vroom)s' angelegt"

AKOnline/models.py

 from django.db import models
 from django.utils.translation import gettext_lazy as _
 
-from AKModel.models import Event, Room
+from AKModel.models import Room
 
 
 class VirtualRoom(models.Model):
@@ -18,6 +18,12 @@ class VirtualRoom(models.Model):
 
     @property
     def event(self):
+        """
+        Property: Event this virtual room belongs to.
+
+        :return: Event this virtual room belongs to
+        :rtype: Event
+        """
         return self.room.event
 
     def __str__(self):

AKOnline/tests.py

-# Create your tests here.

AKOnline/views.py

@@ -9,20 +9,31 @@ from AKOnline.forms import RoomWithVirtualForm
 
 
 class RoomCreationWithVirtualView(RoomCreationView):
+    """
+    View to create both rooms and optionally virtual rooms by filling one form
+    """
     form_class = RoomWithVirtualForm
     template_name = 'admin/AKOnline/room_create_with_virtual.html'
+    room = None
 
     def form_valid(self, form):
+        # This will create the room and additionally a virtual room if the url field is not blank
+        # objects['room'] will always a room instance afterwards, objects['virtual'] may be empty
         objects = form.save()
         self.room = objects['room']
-        messages.success(self.request, _("Created Room '%(room)s'" % {'room': objects['room']}))
+        # Create a (translated) success message containing information about the created room
+        messages.success(self.request, _("Created Room '%(room)s'" % {'room': objects['room']})) #pylint: disable=consider-using-f-string, line-too-long
         if objects['virtual'] is not None:
-            messages.success(self.request, _("Created related Virtual Room '%(vroom)s'" % {'vroom': objects['virtual']}))
+            # Create a (translated) success message containing information about the created virtual room
+            messages.success(self.request, _("Created related Virtual Room '%(vroom)s'" % {'vroom': objects['virtual']})) #pylint: disable=consider-using-f-string, line-too-long
         return HttpResponseRedirect(self.get_success_url())
 
 
 @status_manager.register(name="event_virtual_rooms")
 class EventVirtualRoomsWidget(TemplateStatusWidget):
+    """
+    Status page widget to contain information about all virtual rooms belonging to the given event
+    """
     required_context_type = "event"
     title = _("Virtual Rooms")
     template_name = "admin/AKOnline/status/event_virtual_rooms.html"

AKPlan/admin.py

-# Register your models here.

AKPlan/apps.py

@@ -2,4 +2,7 @@ from django.apps import AppConfig
 
 
 class AkplanConfig(AppConfig):
+    """
+    App configuration (default, only specifies name of the app)
+    """
     name = 'AKPlan'

AKPlan/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: 2022-12-27 00:42+0100\n"
+"POT-Creation-Date: 2023-05-15 20:03+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,56 +27,56 @@ msgstr "Plan"
 msgid "Write to organizers of this event for questions and comments"
 msgstr "Fragen oder Kommentare? Schreib den Orgas dieses Events eine Mail"
 
-#: AKPlan/templates/AKPlan/plan_index.html:32
+#: AKPlan/templates/AKPlan/plan_index.html:36
 msgid "Day"
 msgstr "Tag"
 
-#: AKPlan/templates/AKPlan/plan_index.html:42
+#: AKPlan/templates/AKPlan/plan_index.html:46
 msgid "Event"
 msgstr "Veranstaltung"
 
-#: AKPlan/templates/AKPlan/plan_index.html:55
+#: AKPlan/templates/AKPlan/plan_index.html:59
 #: AKPlan/templates/AKPlan/plan_room.html:13
 #: AKPlan/templates/AKPlan/plan_room.html:59
-#: AKPlan/templates/AKPlan/plan_wall.html:54
+#: AKPlan/templates/AKPlan/plan_wall.html:65
 msgid "Room"
 msgstr "Raum"
 
-#: AKPlan/templates/AKPlan/plan_index.html:76
+#: AKPlan/templates/AKPlan/plan_index.html:80
 #: AKPlan/templates/AKPlan/plan_room.html:11
 #: AKPlan/templates/AKPlan/plan_track.html:9
 msgid "AK Plan"
 msgstr "AK-Plan"
 
-#: AKPlan/templates/AKPlan/plan_index.html:88
+#: AKPlan/templates/AKPlan/plan_index.html:92
 #: AKPlan/templates/AKPlan/plan_room.html:49
 msgid "Rooms"
 msgstr "Räume"
 
-#: AKPlan/templates/AKPlan/plan_index.html:101
+#: AKPlan/templates/AKPlan/plan_index.html:105
 #: AKPlan/templates/AKPlan/plan_track.html:36
 msgid "Tracks"
 msgstr "Tracks"
 
-#: AKPlan/templates/AKPlan/plan_index.html:113
+#: AKPlan/templates/AKPlan/plan_index.html:117
 msgid "AK Wall"
 msgstr "AK-Wall"
 
-#: AKPlan/templates/AKPlan/plan_index.html:126
-#: AKPlan/templates/AKPlan/plan_wall.html:119
+#: AKPlan/templates/AKPlan/plan_index.html:130
+#: AKPlan/templates/AKPlan/plan_wall.html:130
 msgid "Current AKs"
 msgstr "Aktuelle AKs"
 
-#: AKPlan/templates/AKPlan/plan_index.html:133
-#: AKPlan/templates/AKPlan/plan_wall.html:124
+#: AKPlan/templates/AKPlan/plan_index.html:137
+#: AKPlan/templates/AKPlan/plan_wall.html:135
 msgid "Next AKs"
 msgstr "Nächste AKs"
 
-#: AKPlan/templates/AKPlan/plan_index.html:141
+#: AKPlan/templates/AKPlan/plan_index.html:145
 msgid "This event is not active."
 msgstr "Dieses Event ist nicht aktiv."
 
-#: AKPlan/templates/AKPlan/plan_index.html:154
+#: AKPlan/templates/AKPlan/plan_index.html:158
 #: AKPlan/templates/AKPlan/plan_room.html:77
 #: AKPlan/templates/AKPlan/plan_track.html:58
 msgid "Plan is not visible (yet)."
@@ -99,7 +99,7 @@ msgstr "Eigenschaften"
 msgid "Track"
 msgstr "Track"
 
-#: AKPlan/templates/AKPlan/plan_wall.html:134
+#: AKPlan/templates/AKPlan/plan_wall.html:145
 msgid "Reload page automatically?"
 msgstr "Seite automatisch neu laden?"
 

AKPlan/models.py

-# Create your models here.

AKPlan/templates/AKPlan/plan_wall.html

@@ -51,6 +51,8 @@
                     start: '{{ start | timezone:event.timezone | date:"Y-m-d H:i:s" }}',
                     end: '{{ end | timezone:event.timezone  | date:"Y-m-d H:i:s"}}',
                 },
+                slotMinTime: '{{ earliest_start_hour }}:00:00',
+                slotMaxTime: '{{ latest_end_hour }}:00:00',
                 eventDidMount: function(info) {
                     $(info.el).tooltip({title: info.event.extendedProps.description});
                 },

AKPlan/templatetags/color_gradients.py

 # gradients based on http://bsou.io/posts/color-gradients-with-python
 
 
-def hex_to_rgb(hex):
+def hex_to_rgb(hex): #pylint: disable=redefined-builtin
     """
     Convert hex color to RGB color code
     :param hex: hex encoded color
@@ -23,8 +23,7 @@ def rgb_to_hex(rgb):
     """
     # Components need to be integers for hex to make sense
     rgb = [int(x) for x in rgb]
-    return "#"+"".join(["0{0:x}".format(v) if v < 16 else
-                        "{0:x}".format(v) for v in rgb])
+    return "#"+"".join([f"0{v:x}" if v < 16 else f"{v:x}" for v in rgb])
 
 
 def linear_blend(start_hex, end_hex, position):

AKPlan/templatetags/tags_AKPlan.py

@@ -11,6 +11,14 @@ register = template.Library()
 
 @register.filter
 def highlight_change_colors(akslot):
+    """
+    Adjust color to highlight recent changes if needed
+
+    :param akslot: akslot to determine color for
+    :type akslot: AKSlot
+    :return: color that should be used (either default color of the category or some kind of red)
+    :rtype: str
+    """
     # Do not highlight in preview mode or when changes occurred before the plan was published
     if akslot.event.plan_hidden or (akslot.event.plan_published_at is not None
                                     and akslot.event.plan_published_at > akslot.updated):
@@ -25,9 +33,14 @@ def highlight_change_colors(akslot):
     # Recent change? Calculate gradient blend between red and
     recentness = seconds_since_update / settings.PLAN_MAX_HIGHLIGHT_UPDATE_SECONDS
     return darken("#b71540", recentness)
-    # return linear_blend("#b71540", "#000000", recentness)
 
 
 @register.simple_tag
 def timestamp_now(tz):
+    """
+    Get the current timestamp for the given timezone
+
+    :param tz: timezone to be used for the timestamp
+    :return: current timestamp in given timezone
+    """
     return date_format(datetime.now().astimezone(tz), "c")

AKPlan/tests.py

 from django.test import TestCase
 
-from AKModel.tests import BasicViewTests
+from AKModel.tests.test_views import BasicViewTests
 
 
 class PlanViewTests(BasicViewTests, TestCase):
+    """
+    Tests for AKPlan
+    """
     fixtures = ['model.json']
     APP_NAME = 'plan'
 
@@ -15,7 +18,10 @@ class PlanViewTests(BasicViewTests, TestCase):
     ]
 
     def test_plan_hidden(self):
-        view_name_with_prefix, url = self._name_and_url(('plan_overview', {'event_slug': 'kif23'}))
+        """
+        Test correct handling of plan visibility
+        """
+        _, url = self._name_and_url(('plan_overview', {'event_slug': 'kif23'}))
 
         self.client.logout()
         response = self.client.get(url)
@@ -28,8 +34,11 @@ class PlanViewTests(BasicViewTests, TestCase):
                                msg_prefix="Plan is not visible for staff user")
 
     def test_wall_redirect(self):
-        view_name_with_prefix, url_wall = self._name_and_url(('plan_wall', {'event_slug': 'kif23'}))
-        view_name_with_prefix, url_plan = self._name_and_url(('plan_overview', {'event_slug': 'kif23'}))
+        """
+        Test: Make sure that user is redirected from wall to overview when plan is hidden
+        """
+        _, url_wall = self._name_and_url(('plan_wall', {'event_slug': 'kif23'}))
+        _, url_plan = self._name_and_url(('plan_overview', {'event_slug': 'kif23'}))
 
         response = self.client.get(url_wall)
         self.assertRedirects(response, url_plan,

AKPlan/views.py

-from datetime import timedelta
+from datetime import datetime, timedelta
 
 from django.conf import settings
 from django.shortcuts import redirect
 from django.urls import reverse_lazy
-from django.utils.datetime_safe import datetime
-from django.views.generic import ListView, DetailView
+from django.views.generic import DetailView, ListView
 
-from AKModel.models import AKSlot, Room, AKTrack
 from AKModel.metaviews.admin import FilterByEventSlugMixin
+from AKModel.models import AKSlot, AKTrack, Room
 
 
 class PlanIndexView(FilterByEventSlugMixin, ListView):
+    """
+    Default plan view
+
+    Shows two lists of current and upcoming AKs and a graphical full plan below
+    """
     model = AKSlot
     template_name = "AKPlan/plan_index.html"
     context_object_name = "akslots"
@@ -60,6 +64,15 @@ class PlanIndexView(FilterByEventSlugMixin, ListView):
 
 
 class PlanScreenView(PlanIndexView):
+    """
+    Plan view optimized for screens and projectors
+
+    This again shows current and upcoming AKs as well as a graphical plan,
+    but no navigation elements and trys to use the available space as best as possible
+    such that no scrolling is needed.
+
+    The view contains a frontend functionality for auto-reload.
+    """
     template_name = "AKPlan/plan_wall.html"
 
     def get(self, request, *args, **kwargs):
@@ -69,11 +82,12 @@ class PlanScreenView(PlanIndexView):
             return redirect(reverse_lazy("plan:plan_overview", kwargs={"event_slug": self.event.slug}))
         return s
 
-    """
+    # pylint: disable=attribute-defined-outside-init
     def get_queryset(self):
-        # Determine interesting range (some hours ago until some hours in the future as specified in the settings)
         now = datetime.now().astimezone(self.event.timezone)
+        # Wall during event: Adjust, show only parts in the future
         if self.event.start < now < self.event.end:
+            # Determine interesting range (some hours ago until some hours in the future as specified in the settings)
             self.start = now - timedelta(hours=settings.PLAN_WALL_HOURS_RETROSPECT)
         else:
             self.start = self.event.start
@@ -81,33 +95,63 @@ class PlanScreenView(PlanIndexView):
 
         # Restrict AK slots to relevant ones
         # This will automatically filter all rooms not needed for the selected range in the orginal get_context method
-        return super().get_queryset().filter(start__gt=self.start)
-    """
+        akslots = super().get_queryset().filter(start__gt=self.start)
+
+        # Find the earliest hour AKs start and end (handle 00:00 as 24:00)
+        self.earliest_start_hour = 23
+        self.latest_end_hour = 1
+        for akslot in akslots.all():
+            start_hour = akslot.start.astimezone(self.event.timezone).hour
+            if start_hour < self.earliest_start_hour:
+                # Use hour - 1 to improve visibility of date change
+                self.earliest_start_hour = max(start_hour - 1, 0)
+            end_hour = akslot.end.astimezone(self.event.timezone).hour
+            # Special case: AK starts before but ends after midnight -- show until midnight
+            if end_hour < start_hour:
+                self.latest_end_hour = 24
+            elif end_hour > self.latest_end_hour:
+                # Always use hour + 1, since AK may end at :xy and not always at :00
+                self.latest_end_hour = min(end_hour + 1, 24)
+        return akslots
 
     def get_context_data(self, *, object_list=None, **kwargs):
         context = super().get_context_data(object_list=object_list, **kwargs)
-        context["start"] = self.event.start
+        context["start"] = self.start
         context["end"] = self.event.end
+        context["earliest_start_hour"] = self.earliest_start_hour
+        context["latest_end_hour"] = self.latest_end_hour
         return context
 
 
 class PlanRoomView(FilterByEventSlugMixin, DetailView):
+    """
+    Plan view for a single room
+    """
     template_name = "AKPlan/plan_room.html"
     model = Room
     context_object_name = "room"
 
     def get_context_data(self, *, object_list=None, **kwargs):
         context = super().get_context_data(object_list=object_list, **kwargs)
+        # Restrict AKSlot list to the given room
+        # while joining AK, room and category information to reduce the amount of necessary SQL queries
         context["slots"] = AKSlot.objects.filter(room=context['room']).select_related('ak', 'ak__category', 'ak__track')
         return context
 
 
 class PlanTrackView(FilterByEventSlugMixin, DetailView):
+    """
+    Plan view for a single track
+    """
     template_name = "AKPlan/plan_track.html"
     model = AKTrack
     context_object_name = "track"
 
     def get_context_data(self, *, object_list=None, **kwargs):
         context = super().get_context_data(object_list=object_list, **kwargs)
-        context["slots"] = AKSlot.objects.filter(event=self.event, ak__track=context['track']).select_related('ak', 'room', 'ak__category')
+        # Restrict AKSlot list to given track
+        # while joining AK, room and category information to reduce the amount of necessary SQL queries
+        context["slots"] = AKSlot.objects. \
+            filter(event=self.event, ak__track=context['track']). \
+            select_related('ak', 'room', 'ak__category')
         return context

AKPlanning/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: 2022-12-27 00:42+0100\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,10 +17,10 @@ msgstr ""
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 
-#: AKPlanning/settings.py:146
+#: AKPlanning/settings.py:148
 msgid "German"
 msgstr "Deutsch"
 
-#: AKPlanning/settings.py:147
+#: AKPlanning/settings.py:149
 msgid "English"
 msgstr "Englisch"

AKPlanning/settings.py

@@ -52,9 +52,9 @@ INSTALLED_APPS = [
     'rest_framework',
     'simple_history',
     'registration',
-    'bootstrap_datepicker_plus',
     'django_tex',
     'compressor',
+    'docs',
 ]
 
 MIDDLEWARE = [
@@ -217,6 +217,9 @@ PLAN_MAX_HIGHLIGHT_UPDATE_SECONDS = 2 * 60 * 60
 DASHBOARD_SHOW_RECENT = True
 # How many entries max?
 DASHBOARD_RECENT_MAX = 25
+# How many events should be featured in the dashboard
+# (active events will always be featured, even if their number is higher than this threshold)
+DASHBOARD_MAX_FEATURED_EVENTS = 3
 
 # Registration/login behavior
 SIMPLE_BACKEND_REDIRECT_URL = "/user/"
@@ -224,7 +227,7 @@ LOGIN_REDIRECT_URL = SIMPLE_BACKEND_REDIRECT_URL
 
 # Content Security Policy
 CSP_DEFAULT_SRC = ("'self'",)
-CSP_SCRIPT_SRC = ("'self'", "'unsafe-inline'")
+CSP_SCRIPT_SRC = ("'self'", "'unsafe-inline'", "'unsafe-eval'")
 CSP_STYLE_SRC = ("'self'", "'unsafe-inline'", "fonts.googleapis.com")
 CSP_IMG_SRC = ("'self'", "data:")
 CSP_FRAME_SRC = ("'self'", )
@@ -234,4 +237,9 @@ CSP_FONT_SRC = ("'self'", "data:", "fonts.gstatic.com")
 SEND_MAILS = True
 EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
 
+# Documentation
+
+DOCS_ROOT = os.path.join(BASE_DIR, 'docs/_build/html')
+DOCS_ACCESS = 'public'
+
 include(optional("settings/*.py"))

AKPlanning/urls.py

-"""AKPlanning URL Configuration
+"""
+AKPlanning URL Configuration
 
 The `urlpatterns` list routes URLs to views. For more information please see:
     https://docs.djangoproject.com/en/2.2/topics/http/urls/
@@ -13,13 +14,15 @@ Including another URLconf
     1. Import the include() function: from django.urls import include, path
     2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
 """
+
 import debug_toolbar
 from django.apps import apps
 from django.contrib import admin
-from django.urls import path, include
+from django.urls import path, include, re_path
 
 urlpatterns = [
     path('admin/', admin.site.urls),
+    re_path(r'^docs/', include('docs.urls')),
     path('accounts/', include('django.contrib.auth.urls')),
     path('accounts/', include('registration.backends.simple.urls')),
     path('', include('AKModel.urls', namespace='model')),

AKScheduling/admin.py

-# Register your models here.

AKScheduling/api.py

@@ -12,20 +12,32 @@ from AKModel.metaviews.admin import EventSlugMixin
 
 
 class ResourceSerializer(serializers.ModelSerializer):
+    """
+    REST Framework Serializer for Rooms to produce format required for fullcalendar resources
+    """
     class Meta:
         model = Room
         fields = ['id', 'title']
 
     title = serializers.SerializerMethodField('transform_title')
 
-    def transform_title(self, obj):
+    @staticmethod
+    def transform_title(obj):
+        """
+        Adapt title, add capacity information if room has a restriction (capacity is not -1)
+        """
         if obj.capacity > 0:
             return f"{obj.title} [{obj.capacity}]"
         return obj.title
 
 
-class ResourcesViewSet(EventSlugMixin, mixins.RetrieveModelMixin, mixins.ListModelMixin, viewsets.GenericViewSet):
-    permission_classes = (permissions.DjangoModelPermissionsOrAnonReadOnly,)
+class ResourcesViewSet(EventSlugMixin, mixins.ListModelMixin, viewsets.GenericViewSet):
+    """
+    API View: Rooms (resources to schedule for in fullcalendar)
+
+    Read-only, adaption to fullcalendar format through :class:`ResourceSerializer`
+    """
+    permission_classes = (permissions.DjangoModelPermissions,)
     serializer_class = ResourceSerializer
 
     def get_queryset(self):
@@ -33,22 +45,34 @@ class ResourcesViewSet(EventSlugMixin, mixins.RetrieveModelMixin, mixins.ListMod
 
 
 class EventsView(LoginRequiredMixin, EventSlugMixin, ListView):
+    """
+    API View: Slots (events to schedule in fullcalendar)
+
+    Read-only, JSON formatted response is created manually since it requires a bunch of "custom" fields that have
+    different names compared to the normal model or are not present at all and need to be computed to create the
+    required format for fullcalendar.
+    """
     model = AKSlot
 
     def get_queryset(self):
-        return super().get_queryset().select_related('ak').filter(event=self.event, room__isnull=False)
+        return super().get_queryset().select_related('ak').filter(
+            event=self.event, room__isnull=False, start__isnull=False
+        )
 
     def render_to_response(self, context, **response_kwargs):
         return JsonResponse(
             [{
                 "slotID": slot.pk,
-                "title": f'{slot.ak.short_name}: \n{slot.ak.owners_list}',
+                "title": f'{slot.ak.short_name}:\n{slot.ak.owners_list}',
                 "description": slot.ak.details,
                 "resourceId": slot.room.id,
                 "start": timezone.localtime(slot.start, self.event.timezone).strftime("%Y-%m-%d %H:%M:%S"),
                 "end": timezone.localtime(slot.end, self.event.timezone).strftime("%Y-%m-%d %H:%M:%S"),
                 "backgroundColor": slot.ak.category.color,
-                "borderColor": "#2c3e50" if slot.fixed else '#e74c3c' if slot.constraintviolation_set.count() > 0 else slot.ak.category.color,
+                "borderColor":
+                    "#2c3e50" if slot.fixed
+                    else '#e74c3c' if slot.constraintviolation_set.count() > 0
+                    else slot.ak.category.color,
                 "constraint": 'roomAvailable',
                 "editable": not slot.fixed,
                 'url': str(reverse('admin:AKModel_akslot_change', args=[slot.pk])),
@@ -59,6 +83,13 @@ class EventsView(LoginRequiredMixin, EventSlugMixin, ListView):
 
 
 class RoomAvailabilitiesView(LoginRequiredMixin, EventSlugMixin, ListView):
+    """
+    API view: Availabilities of rooms
+
+    Read-only, JSON formatted response is created manually since it requires a bunch of "custom" fields that have
+    different names compared to the normal model or are not present at all and need to be computed to create the
+    required format for fullcalendar.
+    """
     model = Availability
     context_object_name = "availabilities"
 
@@ -81,6 +112,13 @@ class RoomAvailabilitiesView(LoginRequiredMixin, EventSlugMixin, ListView):
 
 
 class DefaultSlotsView(LoginRequiredMixin, EventSlugMixin, ListView):
+    """
+    API view: default slots
+
+    Read-only, JSON formatted response is created manually since it requires a bunch of "custom" fields that have
+    different names compared to the normal model or are not present at all and need to be computed to create the
+    required format for fullcalendar.
+    """
     model = DefaultSlot
     context_object_name = "default_slots"
 
@@ -105,6 +143,9 @@ class DefaultSlotsView(LoginRequiredMixin, EventSlugMixin, ListView):
 
 
 class EventSerializer(serializers.ModelSerializer):
+    """
+    REST framework serializer to adapt between AKSlot model and the event format of fullcalendar
+    """
     class Meta:
         model = AKSlot
         fields = ['id', 'start', 'end', 'roomId']
@@ -114,17 +155,31 @@ class EventSerializer(serializers.ModelSerializer):
     roomId = serializers.IntegerField(source='room.pk')
 
     def update(self, instance, validated_data):
+        # Ignore timezone of input (treat it as timezone-less) and set the event timezone
+        # By working like this, the client does not need to know about timezones, since every timestamp it deals with
+        # has the timezone offsets already applied
         start = timezone.make_aware(timezone.make_naive(validated_data.get('start')), instance.event.timezone)
         end = timezone.make_aware(timezone.make_naive(validated_data.get('end')), instance.event.timezone)
         instance.start = start
-        instance.room = get_object_or_404(Room, pk=validated_data.get('room')["pk"])
+        # Also, adapt from start & end format of fullcalendar to our start & duration model
         diff = end - start
         instance.duration = round(diff.days * 24 + (diff.seconds / 3600), 2)
+
+        # Updated room if needed (pk changed -- otherwise, no need for an additional database lookup)
+        new_room_id = validated_data.get('room')["pk"]
+        if instance.room is None or instance.room.pk != new_room_id:
+            instance.room = get_object_or_404(Room, pk=new_room_id)
+
         instance.save()
         return instance
 
 
-class EventsViewSet(EventSlugMixin, viewsets.ModelViewSet):
+class EventsViewSet(EventSlugMixin, mixins.UpdateModelMixin, viewsets.GenericViewSet):
+    """
+    API view: Update scheduling of a slot (event in fullcalendar format)
+
+    Write-only (will however reply with written values to PUT request)
+    """
     permission_classes = (permissions.DjangoModelPermissions,)
     serializer_class = EventSerializer
 
@@ -136,17 +191,26 @@ class EventsViewSet(EventSlugMixin, viewsets.ModelViewSet):
 
 
 class ConstraintViolationSerializer(serializers.ModelSerializer):
+    """
+    REST Framework Serializer for constraint violations
+    """
     class Meta:
         model = ConstraintViolation
-        fields = ['pk', 'type_display', 'aks', 'ak_slots', 'ak_owner', 'room', 'requirement', 'category', 'comment', 'timestamp_display', 'manually_resolved', 'level_display', 'details', 'edit_url']
+        fields = ['pk', 'type_display', 'aks', 'ak_slots', 'ak_owner', 'room', 'requirement', 'category', 'comment',
+                  'timestamp_display', 'manually_resolved', 'level_display', 'details', 'edit_url']
 
 
-class ConstraintViolationsViewSet(EventSlugMixin, viewsets.ModelViewSet):
+class ConstraintViolationsViewSet(EventSlugMixin, mixins.ListModelMixin, viewsets.GenericViewSet):
+    """
+    API View: Constraint Violations of an event
+
+    Read-only, fields and model selected in :class:`ConstraintViolationSerializer`
+    """
     permission_classes = (permissions.DjangoModelPermissions,)
     serializer_class = ConstraintViolationSerializer
 
-    def get_object(self):
-        return get_object_or_404(ConstraintViolation, pk=self.kwargs["pk"])
-
     def get_queryset(self):
-        return ConstraintViolation.objects.select_related('event', 'room').prefetch_related('aks', 'ak_slots', 'ak_owner', 'requirement', 'category').filter(event=self.event).order_by('manually_resolved', '-type', '-timestamp')
+        # Optimize query to reduce database load
+        return (ConstraintViolation.objects.select_related('event', 'room')
+                .prefetch_related('aks', 'ak_slots', 'ak_owner', 'requirement', 'category')
+                .filter(event=self.event).order_by('manually_resolved', '-type', '-timestamp'))

AKScheduling/apps.py

@@ -2,4 +2,7 @@ from django.apps import AppConfig
 
 
 class AkschedulingConfig(AppConfig):
+    """
+    App configuration (default, only specifies name of the app)
+    """
     name = 'AKScheduling'

AKScheduling/forms.py

 from django import forms
+from django.utils.translation import gettext_lazy as _
 
 from AKModel.models import AK
 
 
 class AKInterestForm(forms.ModelForm):
+    """
+    Form for quickly changing the interest count and notes of an AK
+    """
     required_css_class = 'required'
 
     class Meta:
@@ -11,3 +15,18 @@ class AKInterestForm(forms.ModelForm):
         fields = ['interest',
                   'notes',
                   ]
+
+
+class AKAddSlotForm(forms.Form):
+    """
+    Form to create a new slot for an existing AK directly from scheduling view
+    """
+    start = forms.CharField(label=_("Start"), disabled=True)
+    end = forms.CharField(label=_("End"), disabled=True)
+    duration = forms.CharField(label=_("Duration"), disabled=True)
+    room = forms.IntegerField(label=_("Room"), disabled=True, widget=forms.HiddenInput())
+    room_name = forms.CharField(label=_("Room"), disabled=True)
+
+    def __init__(self, event):
+        super().__init__()
+        self.fields['ak'] = forms.ModelChoiceField(event.ak_set.all(), label=_("AK"))