Add documentation to the education package

website/education/apps.py

+"""Configuration for the education package"""
 from django.apps import AppConfig
 from django.utils.translation import gettext_lazy as _
 
 
 class EducationConfig(AppConfig):
+    """AppConfig for the education package"""
     name = 'education'
     verbose_name = _('Education')

website/education/forms.py

+"""The forms defined by the education package"""
 import datetime
 
 from django.conf import settings
@@ -11,6 +12,7 @@ from .models import Course, Exam, Summary
 
 
 class AddExamForm(ModelForm):
+    """Custom form to add exams, changes the possible years of the date"""
     this_year = datetime.date.today().year
     years = list(reversed(range(this_year - 8, this_year + 1)))
 
@@ -29,6 +31,10 @@ class AddExamForm(ModelForm):
 
 
 class AddSummaryForm(ModelForm):
+    """
+    Custom form to add summaries, orders courses by name and formats the
+    year as lecture years
+    """
     course = ModelChoiceField(
         queryset=Course.objects.order_by('name_' + settings.LANGUAGE_CODE),
         empty_label=None)

website/education/models.py

+"""The models defined by the education package"""
 from django.db import models
 from django.urls import reverse
 from django.utils import timezone
@@ -9,6 +10,7 @@ from utils.translation import ModelTranslateMeta, MultilingualField
 
 
 class Category(models.Model, metaclass=ModelTranslateMeta):
+    """Describes a course category"""
     name = MultilingualField(
         models.CharField,
         max_length=64,
@@ -26,6 +28,7 @@ class Category(models.Model, metaclass=ModelTranslateMeta):
 
 
 class Course(models.Model, metaclass=ModelTranslateMeta):
+    """Describes a course"""
     name = MultilingualField(
         models.CharField,
         max_length=255
@@ -79,6 +82,8 @@ class Course(models.Model, metaclass=ModelTranslateMeta):
 
 
 class Exam(models.Model, metaclass=ModelTranslateMeta):
+    """Describes an exam"""
+
     EXAM_TYPES = (
         ('document', _('Document')),
         ('exam', _('Exam')),
@@ -159,6 +164,7 @@ class Exam(models.Model, metaclass=ModelTranslateMeta):
 
 
 class Summary(models.Model, metaclass=ModelTranslateMeta):
+    """Describes a summary"""
     name = models.CharField(
         max_length=255,
         verbose_name=_('summary name'),

website/education/sitemaps.py

+"""The sitemaps defined by the education package"""
 from django.contrib import sitemaps
 from django.urls import reverse
 
@@ -5,6 +6,7 @@ from . import models
 
 
 class StaticViewSitemap(sitemaps.Sitemap):
+    """Sitemap of the static pages"""
     changefreq = 'daily'
     priority = 0.5
 
@@ -16,6 +18,7 @@ class StaticViewSitemap(sitemaps.Sitemap):
 
 
 class CourseSitemap(sitemaps.Sitemap):
+    """Sitemap of the course pages"""
 
     def items(self):
         return models.Course.objects.all()

website/education/urls.py

+"""The routes defined by the education package"""
 from django.conf.urls import include, url
-from django.views.generic.base import RedirectView
+from django.views.generic.base import RedirectView, TemplateView
 
 from . import views
 
@@ -19,7 +20,9 @@ urlpatterns = [
     url(r'^summaries/(?P<id>[0-9]*)/$', views.summary, name="summary"),
     url(r'^upload-exam/$', views.submit_exam, name="submit-exam"),
     url(r'^upload-summary/$', views.submit_summary, name="submit-summary"),
-    url('^student-participation/$', views.student_participation, name="student-participation"),
+    url('^student-participation/$', TemplateView.as_view(
+        template_name='education/student_participation.html'),
+        name="student-participation"),
     url(r'^$',
         RedirectView.as_view(pattern_name='education:courses',
                              permanent=True), name="index"),

website/education/views.py

+"""Views provided by the education package"""
 import itertools
 import os
 from datetime import datetime, date
@@ -14,6 +15,11 @@ from .models import Category, Course, Exam, Summary
 
 
 def courses(request):
+    """
+    Renders an overview of the courses
+    :param request: the request object
+    :return: HttpResponse 200 containing the HTML as body
+    """
     categories = Category.objects.all()
     objects = Course.objects.order_by('name_' + request.LANGUAGE_CODE).filter(
         until=None)
@@ -22,6 +28,12 @@ def courses(request):
 
 
 def course(request, id):
+    """
+    Renders the detail page of one specific course
+    :param request: the request object
+    :param id: the primary key of the selected course
+    :return: HttpResponse 200 containing the HTML as body
+    """
     obj = get_object_or_404(Course, pk=id)
     courses = list(obj.old_courses.all())
     courses.append(obj)
@@ -47,12 +59,14 @@ def course(request, id):
                   {'course': obj, 'items': items})
 
 
-def student_participation(request):
-    return render(request, 'education/student_participation.html')
-
-
 @login_required
 def exam(request, id):
+    """
+    Fetches and outputs the specified exam
+    :param request: the request object
+    :param id: the id of the exam
+    :return: 302 if not authenticated else 200 with the file as body
+    """
     exam = get_object_or_404(Exam, id=int(id))
 
     exam.download_count += 1
@@ -66,6 +80,12 @@ def exam(request, id):
 
 @login_required
 def summary(request, id):
+    """
+    Fetches and outputs the specified summary
+    :param request: the request object
+    :param id: the id of the summary
+    :return: 302 if not authenticated else 200 with the file as body
+    """
     obj = get_object_or_404(Summary, id=int(id))
 
     obj.download_count += 1
@@ -79,6 +99,12 @@ def summary(request, id):
 
 @login_required
 def submit_exam(request, id=None):
+    """
+    Renders the form to submit a new exam
+    :param request: the request object
+    :param id: the course id (optional)
+    :return: 302 if not authenticated else 200 with the form HTML as body
+    """
     saved = False
 
     if request.POST:
@@ -104,6 +130,12 @@ def submit_exam(request, id=None):
 
 @login_required
 def submit_summary(request, id=None):
+    """
+    Renders the form to submit a new summary
+    :param request: the request object
+    :param id: the course id (optional)
+    :return: 302 if not authenticated else 200 with the form HTML as body
+    """
     saved = False
 
     if request.POST:
@@ -131,6 +163,12 @@ def submit_summary(request, id=None):
 
 @login_required
 def books(request):
+    """
+    Renders a page with information about book sale
+    Only available to members and to-be members
+    :param request: the request object
+    :return: 403 if no active membership else 200 with the page HTML as body
+    """
     if (request.member and request.member.is_authenticated and
             (request.member.current_membership or
              (request.member.earliest_membership and