From d55129fca1e5b12af434fcd3971e94fe56d4c169 Mon Sep 17 00:00:00 2001
From: Lorenz Zahn <lorenz.zahn@student.uni-halle.de>
Date: Tue, 11 Jul 2023 11:16:58 +0200
Subject: [PATCH] documentation
---
app/vkk/workhours/accounting/__init__.py | 6 +++
app/vkk/workhours/accounting/mixins.py | 8 +++-
app/vkk/workhours/accounting/urls.py | 4 ++
app/vkk/workhours/accounting/views.py | 28 ++++++++++++
app/vkk/workhours/allprojects/views.py | 57 +++++++++++++++++++++++-
5 files changed, 101 insertions(+), 2 deletions(-)
diff --git a/app/vkk/workhours/accounting/__init__.py b/app/vkk/workhours/accounting/__init__.py
index e69de29b..e6624d03 100644
--- a/app/vkk/workhours/accounting/__init__.py
+++ b/app/vkk/workhours/accounting/__init__.py
@@ -0,0 +1,6 @@
+"""
+This module contains the utilities associated with the administration
+ of this page or accontants.
+
+This module's substructure closely resembles the path substructure of the website.
+"""
diff --git a/app/vkk/workhours/accounting/mixins.py b/app/vkk/workhours/accounting/mixins.py
index 244f2fbb..ff6e1036 100644
--- a/app/vkk/workhours/accounting/mixins.py
+++ b/app/vkk/workhours/accounting/mixins.py
@@ -1,7 +1,13 @@
+"""
+This submodule contains some mixin classes used through all other submodules.
+"""
+
from django.contrib.auth.mixins import AccessMixin
class AccountantRequiredMixin(AccessMixin):
- """Verify that the current user has accountant rights."""
+ """
+ A mixin class for checking whether the current user has accounting permissions.
+ """
def dispatch(self, request, *args, **kwargs):
if (not request.user.is_authenticated or
not request.user.is_accountant):
diff --git a/app/vkk/workhours/accounting/urls.py b/app/vkk/workhours/accounting/urls.py
index d5a46a88..0db98667 100644
--- a/app/vkk/workhours/accounting/urls.py
+++ b/app/vkk/workhours/accounting/urls.py
@@ -1,3 +1,7 @@
+"""
+This submodule contains the routing configuration.
+"""
+
from django.urls import include, path
from django.utils.translation import gettext_lazy as _
from .views import AccountingOverView
diff --git a/app/vkk/workhours/accounting/views.py b/app/vkk/workhours/accounting/views.py
index 4ca77497..6e9a6c91 100644
--- a/app/vkk/workhours/accounting/views.py
+++ b/app/vkk/workhours/accounting/views.py
@@ -1,3 +1,7 @@
+"""
+This submodule contains class based views.
+"""
+
from vkk.generic.views import (
CustomDetailView, CustomCreateView, CustomUpdateView,
CustomDeleteView, CustomSuccessView, CustomListView,
@@ -7,25 +11,49 @@ from django.views.generic import TemplateView
from .mixins import AccountantRequiredMixin
class AccountingDetailView(AccountantRequiredMixin, CustomDetailView):
+ """
+ A class based `View` extending the `CustomDetailView` class with the `AccountantRequiredMixin` mixing.
+ """
pass
class AccountingCreateView(AccountantRequiredMixin, CustomCreateView):
+ """
+ A class based `View` extending the `CustomCreateView` class with the `AccountantRequiredMixin` mixin.
+ """
pass
class AccountingUpdateView(AccountantRequiredMixin, CustomUpdateView):
+ """
+ A class based `View` extending the `CustomUpdateView` class with the `AccountantRequiredMixin` mixin.
+ """
pass
class AccountingDeleteView(AccountantRequiredMixin, CustomDeleteView):
+ """
+ A class based `View` extending the `CustomDeleteView` class with the `AccountantRequiredMixin` mixin.
+ """
pass
class AccountingListView(AccountantRequiredMixin, CustomListView):
+ """
+ A class based `View` extending the `CustomListView` class with the `AccountantRequiredMixin` mixin.
+ """
pass
class AccountingFilterView(AccountantRequiredMixin, CustomFilterView):
+ """
+ A class based `View` extending the `CustomFilterView` class with the `AccountantRequiredMixin` mixin.
+ """
pass
class AccountingSuccessView(AccountantRequiredMixin, CustomSuccessView):
+ """
+ A class based `View` extending the `CustomSuccessView` class with the `AccountantRequiredMixin` mixin.
+ """
pass
class AccountingOverView(AccountantRequiredMixin, TemplateView):
+ """
+ A class based `View` extending the `TemplateView` class with the `AccountantRequiredMixin` mixin.
+ """
template_name = 'vkk/workhours/accounting/overview.html'
diff --git a/app/vkk/workhours/allprojects/views.py b/app/vkk/workhours/allprojects/views.py
index 3d57a951..37481bc9 100644
--- a/app/vkk/workhours/allprojects/views.py
+++ b/app/vkk/workhours/allprojects/views.py
@@ -15,7 +15,13 @@ from .forms import AssigneeForm, YearSelectForm, AssgineeClosureForm
class AllProjectYearRedirectView(ProjectManagerRequiredMixin, RedirectView):
+ """
+ A class based `View` providing a functionality for selecting and redirecting for a given year.
+ """
def get_redirect_url(self, *args, **kwargs):
+ """
+ Returns an URL for redirecting.
+ """
# Catches Period Selection from GET
if 'year' in self.request.GET:
form = YearSelectForm(data=self.request.GET)
@@ -27,6 +33,10 @@ class AllProjectYearRedirectView(ProjectManagerRequiredMixin, RedirectView):
class AllProjectAssigneesOverView(ProjectManagerRequiredMixin, CustomListView):
+ """
+ A class based `View` providing functionality for listing all contributors to be
+ managed by the given project manager no matter the specific project.
+ """
model = User
fields = ['first_name', 'last_name', 'email']
action_options = {'update': _('Details')}
@@ -34,6 +44,9 @@ class AllProjectAssigneesOverView(ProjectManagerRequiredMixin, CustomListView):
template_name = 'vkk/workhours/allprojects/overview.html'
def get_context_data(self, **kwargs):
+ """
+ Returns a context for rendering the page.
+ """
context = super().get_context_data(**kwargs)
context["form"] = YearSelectForm(
initial={'year': self.kwargs['year']}
@@ -41,6 +54,10 @@ class AllProjectAssigneesOverView(ProjectManagerRequiredMixin, CustomListView):
return context
def get_queryset(self):
+ """
+ Returns a query set containing all contributors which are assigned to projects, which
+ are managed by the given user as a project manager.
+ """
query_set = super().get_queryset().filter(
projectassignment__project__projectmanager__manager=self.request.user,
projectassignment__project__projectmanager__end__gte=timezone.now().date(),
@@ -49,10 +66,17 @@ class AllProjectAssigneesOverView(ProjectManagerRequiredMixin, CustomListView):
class AssigneeUpdate(ProjectManagerRequiredMixin, FormView):
+ """
+ A class based `View` providing functionality for updating work hours
+ of a selected contributor.
+ """
form_class = AssigneeForm
template_name = 'vkk/workhours/allprojects/assignee_update.html'
def get_form_kwargs(self):
+ """
+ Returns the keyword arguments meant for initializing the associated `Form`.
+ """
kwargs = super().get_form_kwargs()
kwargs.update({
'assignee': self.kwargs['pk'],
@@ -62,25 +86,42 @@ class AssigneeUpdate(ProjectManagerRequiredMixin, FormView):
return kwargs
def get_context_data(self, **kwargs):
+ """
+ Returns a context for rendering the page.
+ """
context = super().get_context_data(**kwargs)
context["assignee"] = User.objects.get(id=self.kwargs['pk'])
return context
def get_success_url(self):
+ """
+ Returns an URL to redirect to after a successfull action.
+ """
return reverse(
'vkk:workhours:allprojects:update_success', kwargs={'year': self.kwargs['year']},
)
def form_valid(self, form):
+ """
+ Saves the Information associated with the `Form`, after valididating it, and returns
+ said instance.
+ """
form.save()
return super().form_valid(form)
class AssigneeClosureView(ProjectManagerRequiredMixin, FormView):
+ """
+ A class based `View` providing functionality for closing a period for a contributor.
+ """
form_class = AssgineeClosureForm
template_name = 'vkk/workhours/contributor/closure.html'
def post(self, request, *args, **kwargs):
+ """
+ Handler for POST request. Returns either a 403 response or redirection after
+ a sucsessful action.
+ """
form = self.form_class(
data={
'period': self.kwargs['period_pk'],
@@ -95,11 +136,17 @@ class AssigneeClosureView(ProjectManagerRequiredMixin, FormView):
return self.handle_no_permission()
def get_context_data(self, **kwargs):
+ """
+ Returns a context for rednering the page.
+ """
context = super().get_context_data(**kwargs)
context.pop('form')
return context
def get_success_url(self):
+ """
+ Returns an URL to redirect to after a successful action.
+ """
url = reverse(
'vkk:workhours:allprojects:closure_success',
args=[self.kwargs['year'], self.kwargs['assignee_pk']],
@@ -108,12 +155,20 @@ class AssigneeClosureView(ProjectManagerRequiredMixin, FormView):
class AssigneeUpdateSuccessView(ProjectManagerRequiredMixin, CustomSuccessView):
+ """
+ A class based `View` providing a success page after updating a contributors workhours.
+ """
pass
class AssigneeClosureSuccessView(ProjectManagerRequiredMixin, CustomSuccessView):
-
+ """
+ A class based `View` providing a success page after closing a contributors period.
+ """
def get_success_url(self):
+ """
+ Returns a URL for a hyperlink.
+ """
url = reverse(
'vkk:workhours:allprojects:update',
args=[self.kwargs['year'], self.kwargs['assignee_pk']],
--
GitLab