Merge branch 'feature/documents-documentation' into 'master'

Add documentation to the documents package

Closes #573

See merge request !811

docs/documents.rst

@@ -32,6 +32,14 @@ documents\.apps module
     :undoc-members:
     :show-inheritance:
 
+documents\.forms module
+-----------------------
+
+.. automodule:: documents.forms
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 documents\.models module
 ------------------------
 

website/documents/admin.py

-from django import forms
+"""Registers admin interfaces for the documents module"""
 from django.contrib import admin
 
+from documents.forms import GeneralMeetingForm
 from documents.models import (AnnualDocument, AssociationDocument,
                               GeneralMeeting, Minutes,
                               MiscellaneousDocument)
@@ -8,22 +9,14 @@ from utils.translation import TranslatedModelAdmin
 
 
 class MinutesInline(admin.StackedInline):
+    """Inline for minutes of a general meeting"""
     model = Minutes
     fields = ('file_nl', 'file_en', 'members_only',)
 
 
-class GeneralMeetingForm(forms.ModelForm):
-    class Meta:
-        model = GeneralMeeting
-        exclude = ()
-        widgets = {
-            'documents': admin.widgets.FilteredSelectMultiple(
-                'documents', is_stacked=False)
-        }
-
-
 @admin.register(GeneralMeeting)
 class GeneralMeetingAdmin(TranslatedModelAdmin):
+    """Manage the general meetings"""
     form = GeneralMeetingForm
     inlines = [
         MinutesInline,
@@ -33,17 +26,20 @@ class GeneralMeetingAdmin(TranslatedModelAdmin):
 
 @admin.register(AnnualDocument)
 class AnnualDocument(TranslatedModelAdmin):
+    """Manage the annual documents"""
     fields = ('file', 'subcategory', 'year', 'members_only',)
     list_filter = ('year', 'created', 'last_updated',)
 
 
 @admin.register(AssociationDocument)
 class AssociationDocumentAdmin(TranslatedModelAdmin):
+    """Manage the association documents"""
     fields = ('name', 'file', 'members_only',)
     list_filter = ('created', 'last_updated',)
 
 
 @admin.register(MiscellaneousDocument)
 class MiscellaneousDocumentAdmin(TranslatedModelAdmin):
+    """Manage the miscellaneous documents"""
     fields = ('name', 'file', 'members_only',)
     list_filter = ('created', 'last_updated',)

website/documents/forms.py

+"""The forms defined by the documents package"""
+from django import forms
+from django.contrib import admin
+
+from documents.models import GeneralMeeting
+
+
+class GeneralMeetingForm(forms.ModelForm):
+    """Custom form for general meetings with a custom widget for documents"""
+    class Meta:
+        model = GeneralMeeting
+        exclude = ()
+        widgets = {
+            'documents': admin.widgets.FilteredSelectMultiple(
+                'documents', is_stacked=False)
+        }

website/documents/models.py

@@ -8,6 +8,7 @@ from utils.validators import validate_file_extension
 
 
 class Document(models.Model, metaclass=ModelTranslateMeta):
+    """Describes a base document"""
     class Meta:
         verbose_name = _('Document')
         verbose_name_plural = _('Documents')
@@ -59,6 +60,7 @@ class Document(models.Model, metaclass=ModelTranslateMeta):
 
 
 class AnnualDocument(Document):
+    """Describes an annual document"""
     class Meta:
         verbose_name = _('Annual document')
         verbose_name_plural = _('Annual documents')
@@ -97,11 +99,13 @@ class AnnualDocument(Document):
 
 
 class AssociationDocumentManager(models.Manager):
+    """Custom manager to filter for association documents"""
     def get_queryset(self):
         return super().get_queryset().filter(category='association')
 
 
 class AssociationDocument(Document):
+    """Describes an association document"""
     class Meta:
         verbose_name = _('Miscellaneous association document')
         verbose_name_plural = _('Miscellaneous association documents')
@@ -115,11 +119,13 @@ class AssociationDocument(Document):
 
 
 class MiscellaneousDocumentManager(models.Manager):
+    """Custom manager to filter for misc documents"""
     def get_queryset(self):
         return super().get_queryset().filter(category='misc')
 
 
 class MiscellaneousDocument(Document):
+    """Describes a miscellaneous document"""
     class Meta:
         verbose_name = _('Miscellaneous document')
         verbose_name_plural = _('Miscellaneous documents')
@@ -133,6 +139,7 @@ class MiscellaneousDocument(Document):
 
 
 class GeneralMeeting(models.Model, metaclass=ModelTranslateMeta):
+    """Describes a general meeting"""
     class Meta:
         verbose_name = _('General meeting')
         verbose_name_plural = _('General meetings')
@@ -159,6 +166,7 @@ class GeneralMeeting(models.Model, metaclass=ModelTranslateMeta):
 
 
 class Minutes(Document):
+    """Describes a minutes document"""
     class Meta:
         verbose_name = _('Minutes')
         verbose_name_plural = _('Minutes')

website/documents/sitemaps.py

+"""The sitemaps defined by the documents package"""
 from django.contrib import sitemaps
 from django.urls import reverse
 
@@ -5,6 +6,7 @@ from . import models
 
 
 class StaticViewSitemap(sitemaps.Sitemap):
+    """Sitemap for the static pages"""
     priority = 0.5
     changefreq = 'daily'
 
@@ -16,6 +18,7 @@ class StaticViewSitemap(sitemaps.Sitemap):
 
 
 class MiscellaneousDocumentsSitemap(sitemaps.Sitemap):
+    """Sitemap for misc documents"""
 
     def items(self):
         return models.MiscellaneousDocument.objects.exclude(members_only=True)

website/documents/urls.py

-from django.conf.urls import include, url
+"""The routes defined by the documents package"""
+from django.conf.urls import url
 
 from . import views
 

website/documents/views.py

+"""Views provided by the documents package"""
 import os
 
 from django.conf import settings
@@ -13,6 +14,11 @@ from utils.snippets import datetime_to_lectureyear
 
 
 def index(request):
+    """
+    View that renders the documents index page
+    :param request: the request object
+    :return: HttpResponse 200 containing the page HTML
+    """
     lectureyear = datetime_to_lectureyear(timezone.now())
 
     years = {x: {} for x in range(1990, lectureyear + 1)}
@@ -46,6 +52,13 @@ def index(request):
 # TODO verify if we need to check a permission instead.
 # This depends on how we're dealing with ex-members.
 def get_document(request, pk):
+    """
+    View that allows you to download a specific document based on it's and your
+    permissions settings
+    :param request: the request object
+    :param pk: primary key of the document
+    :return: either a 302 redirect to the login page or a 200 with the document
+    """
     document = get_object_or_404(Document, pk=int(pk))
 
     if document.members_only and not request.user.is_authenticated: