Improve docs for the announcements module

Also makes the view that handles marking announcements as closed much more robust

See #570

website/announcements/admin.py

+"""Registers admin interfaces for the announcements module"""
 from django.contrib import admin
 from django.template.defaultfilters import striptags
 
@@ -9,22 +10,37 @@ from .models import Announcement, FrontpageArticle
 
 @admin.register(Announcement)
 class AnnouncementAdmin(TranslatedModelAdmin):
+    """Manage the admin pages for the announcements"""
+
+    #: show these fields in the admin overview list
+    #: see :py:method:content_html for the 'content_html' field
+    #: see :py:method:visible for the visible field
     list_display = ('content_html', 'since', 'until', 'visible')
 
-    def content_html(self, obj):
+    def content_html(self, obj):  # pylint: disable=no-self-use
+        """Get the content of the object as html
+
+        :param obj: the object to render for
+        :return: the stripped html
+        """
         # Both bleach and striptags.
         # First to convert HTML entities and second to strip all HTML
         return bleach(striptags(obj.content))
 
-    def visible(self, obj):
+    def visible(self, obj):  # pylint: disable=no-self-use
+        """Is the object visible"""
         return obj.is_visible
     visible.boolean = True
 
 
 @admin.register(FrontpageArticle)
 class FrontpageArticleAdmin(TranslatedModelAdmin):
+    """Manage front page articles"""
+
+    #: available fields in the admin overview list
     list_display = ('title', 'since', 'until', 'visible')
 
-    def visible(self, obj):
+    def visible(self, obj):  # pylint: disable=no-self-use
+        """Is the object visible"""
         return obj.is_visible
     visible.boolean = True

website/announcements/apps.py

+"""Configuration for the announcement package"""
 from django.apps import AppConfig
 from django.utils.translation import gettext_lazy as _
 
 
 class AnnouncementsConfig(AppConfig):
+    """AppConfig for the announcement package"""
     name = 'announcements'
     verbose_name = _('Site header announcements')

website/announcements/context_processors.py

+"""
+These context processors can be used to expand the context provided
+to admin views.
+"""
 from .models import Announcement
 
 
 def announcements(request):
+    """
+    Gets a list of announcements.
+
+    Filters out announcements that have been closed already.
+
+    :param request: the request object
+    :return: a dict containing the list announcements
+    :rtype: dict
+    """
     closed_announcements = request.session.get('closed_announcements', [])
-    announcements = [a for a in Announcement.objects.all()
-                     if a.is_visible and a.pk not in closed_announcements]
-    return {'announcements': announcements}
+    announcements_list = [a for a in Announcement.objects.all()
+                          if a.is_visible and a.pk not in closed_announcements]
+    return {'announcements': announcements_list}

website/announcements/models.py

+"""The models defined by the announcement package"""
 from django.db import models
 from django.utils.translation import ugettext_lazy as _
 from django.utils import timezone
@@ -7,6 +8,8 @@ from utils.translation import ModelTranslateMeta, MultilingualField
 
 
 class Announcement(models.Model, metaclass=ModelTranslateMeta):
+    """Describes an announcement"""
+
     content = MultilingualField(
         HTMLField,
         verbose_name=_('Content'),
@@ -53,6 +56,7 @@ class Announcement(models.Model, metaclass=ModelTranslateMeta):
 
 
 class FrontpageArticle(models.Model, metaclass=ModelTranslateMeta):
+    """Front page articles"""
     title = MultilingualField(
         models.CharField,
         verbose_name=_('Title'),

website/announcements/urls.py

+"""The routes defined by this package"""
+# pylint: disable=invalid-name
 from django.conf.urls import url
 
-from . import views
+from announcements import views
 
+#: the name of this app
 app_name = "announcements"
 
+#: the actual routes
 urlpatterns = [
-    url(r'^close-announcement$', views.close_announcement, name='close-announcement')
+    url(r'^close-announcement$',
+        views.close_announcement,
+        name='close-announcement')
 ]

website/announcements/views.py

-from django.http import HttpResponse
+"""Views provided by the announcements package"""
+from django.http import HttpResponse, HttpResponseBadRequest
+from django.views.decorators.http import require_POST
 
 
+@require_POST
 def close_announcement(request):
-    id = int(request.POST['id'])
+    """Close an announcement
+
+    :param: request
+    :return: Http 204 No Content if successful
+    """
+    if 'id' not in request.POST:
+        return HttpResponseBadRequest("no id specified")
+    announcement_id = int(request.POST['id'])
     # if we do not have a list of closed announcements yet:
     if 'closed_announcements' not in request.session:
         request.session['closed_announcements'] = []  # cannot use sets here :(
     # duplicates should never occur anyway, but it does not hurt to check
-    if id not in request.session['closed_announcements']:
-        request.session['closed_announcements'].append(id)
+    if announcement_id not in request.session['closed_announcements']:
+        request.session['closed_announcements'].append(announcement_id)
     # needs to be explicitly marked since we only edited an existing object
     request.session.modified = True
     return HttpResponse(status=204)  # 204: No Content