Add a lot of comments

apps/participation/views.py

@@ -27,6 +27,10 @@ from .tables import CalendarTable
 
 
 class CreateTeamView(LoginRequiredMixin, CreateView):
+    """
+    Display the page to create a team for new users.
+    """
+
     model = Team
     form_class = TeamForm
     extra_context = dict(title=_("Create team"))
@@ -43,14 +47,24 @@ class CreateTeamView(LoginRequiredMixin, CreateView):
 
     @transaction.atomic
     def form_valid(self, form):
+        """
+        When a team is about to be created, the user automatically
+        joins the team, a mailing list got created and the user is
+        automatically subscribed to this mailing list, and finally
+        a Matrix room is created and the user is invited in this room.
+        """
         ret = super().form_valid(form)
+        # The user joins the team
         user = self.request.user
         registration = user.registration
         registration.team = form.instance
         registration.save()
+
+        # Subscribe the user mail address to the team mailing list
         get_sympa_client().subscribe(user.email, f"equipe-{form.instance.trigram.lower()}", False,
                                      f"{user.first_name} {user.last_name}")
 
+        # Invite the user in the team Matrix room
         Matrix.invite(f"#team-{form.instance.trigram.lower()}:correspondances-maths.fr",
                       f"@{user.registration.matrix_username}:correspondances-maths.fr")
         return ret
@@ -60,6 +74,9 @@ class CreateTeamView(LoginRequiredMixin, CreateView):
 
 
 class JoinTeamView(LoginRequiredMixin, FormView):
+    """
+    Participants can join a team with the access code of the team.
+    """
     model = Team
     form_class = JoinTeamForm
     extra_context = dict(title=_("Join team"))
@@ -76,15 +93,24 @@ class JoinTeamView(LoginRequiredMixin, FormView):
 
     @transaction.atomic
     def form_valid(self, form):
+        """
+        When a user joins a team, the user is automatically subscribed to
+        the team mailing list,the user is invited in the team Matrix room.
+        """
         self.object = form.instance
         ret = super().form_valid(form)
+
+        # Join the team
         user = self.request.user
         registration = user.registration
         registration.team = form.instance
         registration.save()
+
+        # Subscribe to the team mailing list
         get_sympa_client().subscribe(user.email, f"equipe-{form.instance.trigram.lower()}", False,
                                      f"{user.first_name} {user.last_name}")
 
+        # Invite the user in the team Matrix room
         Matrix.invite(f"#team-{form.instance.trigram.lower()}:correspondances-maths.fr",
                       f"@{user.registration.matrix_username}:correspondances-maths.fr")
         return ret
@@ -94,6 +120,10 @@ class JoinTeamView(LoginRequiredMixin, FormView):
 
 
 class MyTeamDetailView(LoginRequiredMixin, RedirectView):
+    """
+    Redirect to the detail of the team in which the user is.
+    """
+
     def get_redirect_url(self, *args, **kwargs):
         user = self.request.user
         registration = user.registration
@@ -105,11 +135,15 @@ class MyTeamDetailView(LoginRequiredMixin, RedirectView):
 
 
 class TeamDetailView(LoginRequiredMixin, FormMixin, ProcessFormView, DetailView):
+    """
+    Display the detail of a team.
+    """
     model = Team
 
     def get(self, request, *args, **kwargs):
         user = request.user
         self.object = self.get_object()
+        # Ensure that the user is an admin or a member of the team
         if user.registration.is_admin or user.registration.participates and user.registration.team.pk == kwargs["pk"]:
             return super().get(request, *args, **kwargs)
         raise PermissionDenied
@@ -120,6 +154,8 @@ class TeamDetailView(LoginRequiredMixin, FormMixin, ProcessFormView, DetailView)
         team = self.get_object()
         context["request_validation_form"] = RequestValidationForm(self.request.POST or None)
         context["validation_form"] = ValidateParticipationForm(self.request.POST or None)
+        # A team is complete when there are at least 3 members that have sent their photo authorization
+        # and confirmed their email address
         context["can_validate"] = team.students.count() >= 3 and \
             all(r.email_confirmed for r in team.students.all()) and \
             all(r.photo_authorization for r in team.students.all()) and \
@@ -188,6 +224,9 @@ class TeamDetailView(LoginRequiredMixin, FormMixin, ProcessFormView, DetailView)
 
 
 class TeamUpdateView(LoginRequiredMixin, UpdateView):
+    """
+    Update the detail of a team
+    """
     model = Team
     form_class = TeamForm
     template_name = "participation/update_team.html"
@@ -218,6 +257,9 @@ class TeamUpdateView(LoginRequiredMixin, UpdateView):
 
 
 class TeamAuthorizationsView(LoginRequiredMixin, DetailView):
+    """
+    Get as a ZIP archive all the authorizations that are sent
+    """
     model = Team
 
     def dispatch(self, request, *args, **kwargs):
@@ -245,6 +287,10 @@ class TeamAuthorizationsView(LoginRequiredMixin, DetailView):
 
 
 class TeamLeaveView(LoginRequiredMixin, TemplateView):
+    """
+    A team member leaves a team
+    """
+
     template_name = "participation/team_leave.html"
 
     def dispatch(self, request, *args, **kwargs):
@@ -258,6 +304,10 @@ class TeamLeaveView(LoginRequiredMixin, TemplateView):
 
     @transaction.atomic()
     def post(self, request, *args, **kwargs):
+        """
+        When the team is left, the user is unsubscribed from the team mailing list
+        and kicked from the team room.
+        """
         team = request.user.registration.team
         request.user.registration.team = None
         request.user.registration.save()
@@ -271,6 +321,9 @@ class TeamLeaveView(LoginRequiredMixin, TemplateView):
 
 
 class MyParticipationDetailView(LoginRequiredMixin, RedirectView):
+    """
+    Redirects to the detail view of the participation of the team.
+    """
     def get_redirect_url(self, *args, **kwargs):
         user = self.request.user
         registration = user.registration
@@ -282,6 +335,9 @@ class MyParticipationDetailView(LoginRequiredMixin, RedirectView):
 
 
 class ParticipationDetailView(LoginRequiredMixin, DetailView):
+    """
+    Display detail about the participation of a team, and manage the video submission.
+    """
     model = Participation
 
     def dispatch(self, request, *args, **kwargs):
@@ -303,6 +359,9 @@ class ParticipationDetailView(LoginRequiredMixin, DetailView):
 
 
 class UploadVideoView(LoginRequiredMixin, UpdateView):
+    """
+    Upload a solution video for a team.
+    """
     model = Video
     form_class = UploadVideoForm
     template_name = "participation/upload_video.html"
@@ -319,11 +378,17 @@ class UploadVideoView(LoginRequiredMixin, UpdateView):
 
 
 class CalendarView(SingleTableView):
+    """
+    Display the calendar of the action.
+    """
     table_class = CalendarTable
     model = Phase
 
 
 class PhaseUpdateView(AdminMixin, UpdateView):
+    """
+    Update a phase of the calendar, if we have sufficient rights.
+    """
     model = Phase
     form_class = PhaseForm