Extend documentation

src/abgabesystem/commands.py

@@ -9,6 +9,10 @@ from gitlab.exceptions import GitlabCreateError, GitlabGetError
 
 def enroll_students(gl, args):
     """Creates Gitlab users from exported students list
+
+    Args:
+        gl: API
+        args: command line arguments
     """
 
     student_group = get_student_group(gl, args.course)
@@ -25,6 +29,10 @@ def enroll_students(gl, args):
 
 def projects(gl, args):
     """Creates the projects for all course participants
+
+    Args:
+        gl: API
+        args: command line arguments
     """
     course = None
     for g in gl.groups.list(search=args.course):
@@ -39,7 +47,12 @@ def projects(gl, args):
 
 
 def deadline(gl, args):
-    """Checks deadlines for course and triggers deadline if it is reached"""
+    """Checks deadlines for course and triggers deadline if it is reached
+
+    Args:
+        gl: API
+        args: command line arguments
+    """
 
     deadline_name = args.tag_name
     try:
@@ -63,6 +76,10 @@ def deadline(gl, args):
 
 def plagiates(gl, args):
     """Runs the plagiarism checker (JPlag) for the solutions with a certain tag
+
+    Args:
+        gl: API
+        args: command line arguments
     """
 
     solutions_dir = 'input'
@@ -90,6 +107,10 @@ def plagiates(gl, args):
 
 def course(gl, args):
     """Creates the group for the course
+
+    Args:
+        gl: API
+        args: command line arguments
     """
     try:
         gl.groups.create({

src/abgabesystem/course.py

@@ -2,10 +2,21 @@ import logging as log
 
 
 class InvalidCourse(Exception):
+    """Raised if the selected course is invalid.
+    """
+
     pass
 
 
 def create_subgroup(gl, name, parent_group):
+    """Creates a group with `parent_group` as its parent.
+
+    Args:
+        gl: gitlab API object
+        name: name of the group to be created
+        parent_group: parent group of the created group
+    """
+
     log.info("Creating subgroup %s in group %s" % (name, parent_group.name))
     return gl.groups.create({
         "name": name,
@@ -23,6 +34,15 @@ def create_solutions_group(gl, parent_group):
 
 
 def create_course(gl, course_name):
+    """Creates a complete course as required by the `abgabesystem` including
+    the students and solutions groups.
+
+    Args:
+        gl: gitlab API object
+        course_name: name of the course, may contain any characters from
+                     [0-9,a-z,A-Z,_, ]
+    """
+
     group = gl.groups.create({
         "name": course_name,
         "path": course_name.lower().replace(" ", "_"),

src/abgabesystem/projects.py

@@ -10,7 +10,12 @@ def create_tag(project, tag, ref):
     """Creates protected tag on ref
 
     The tag is used by the abgabesystem to mark the state of a solution at the
-    deadline
+    deadline.
+
+    Args:
+        project: GIT repository to create the tag in
+        tag: name of the tag to be created
+        ref: name of the red (branch / commit) to create the new tag on
     """
 
     print('Project %s. Creating tag %s' % (project.path, tag))
@@ -21,9 +26,17 @@ def create_tag(project, tag, ref):
     })
 
 
-
 def fork_reference(gl, reference, namespace, deploy_key):
     """Create fork of solutions for student.
+
+    Returns the created project.
+
+    Args:
+        gl: gitlab API object
+        reference: project to fork from
+        namespace: namespace to place the created project into
+        deploy_key: will be used by the abgabesystem to access the created
+                    project
     """
 
     fork = reference.forks.create({
@@ -46,6 +59,14 @@ def fork_reference(gl, reference, namespace, deploy_key):
 def create_project(gl, group, user, reference, deploy_key):
     """Creates a namespace (subgroup) and forks the project with
     the reference solutions into that namespace
+
+    Args:
+        gl: Gitlab API object
+        group: project will be created in the namespace of this group
+        user: user to add to the project as a developer
+        reference: project to fork the new project from
+        deploy_key: deploy key used by the `abgabesystem` to access the new
+                    project
     """
 
     subgroup = None
@@ -79,6 +100,14 @@ def create_project(gl, group, user, reference, deploy_key):
 
 
 def create_reference_solution(gl, namespace):
+    """Creates a new project for the reference solutions.
+
+    Args:
+        gl: gitlab API object
+        namespace: namespace to create the project in (that of the solutions for the course)
+    """
+
+
     reference_project = gl.projects.create({
         'name': 'solutions',
         'namespace_id': namespace,
@@ -100,7 +129,12 @@ def create_reference_solution(gl, namespace):
 
 
 def setup_projects(gl, course, deploy_key):
-    """Sets up the internal structure for the group for use with the course
+    """Sets up the internal structure for the group for use with the course.
+
+    Args:
+        gl: gitlab API object
+        course: course to set up projects for
+        deploy_key: will be used to access the solutions from the abgabesystem
     """
 
     solutions = None

src/abgabesystem/students.py

@@ -5,10 +5,17 @@ from gitlab import GUEST_ACCESS
 
 
 class MissingStudentsGroup(Exception):
+    """Raised if a the group for the students has not already been created
+    inside the course.
+    """
+
     pass
 
 
 class MissingCourseGroup(Exception):
+    """Raised if the group for the course is missing.
+    """
+
     pass
 
 
@@ -18,6 +25,12 @@ class Student():
     Students are read from the CSV file that was exported from Stud.IP.
     For each user, a dummy LDAP user is created in Gitlab.
     Upon the first login Gitlab fetches the complete user using LDAP.
+
+    Args:
+        user: user name
+        mail: mail address of the user
+        name: full name of the user
+        group: tutorial group of the user
     """
 
     def __init__(self, user, mail, name, group):
@@ -27,7 +40,11 @@ class Student():
         self.group = group
 
     def from_csv(csvfile):
-        """Creates an iterable containing the users"""
+        """Creates an iterable containing the users
+
+        Args:
+            csvfile: CSV file from Stud.IP (latin-1)
+        """
         reader = csv.DictReader(csvfile, delimiter=';', quotechar='"')
 
         for line in reader:
@@ -36,7 +53,12 @@ class Student():
 
 
 def get_students_csv(gl, students_csv):
-    """Returns already existing GitLab users for students from provided CSV file that have an account.
+    """Returns already existing GitLab users for students from provided CSV
+    file that have an account.
+
+    Args:
+        gl: Gitlab API object
+        students_csv: CSV file from Stud.IP
     """
 
     for student in Student.from_csv(students_csv):
@@ -47,6 +69,10 @@ def get_students_csv(gl, students_csv):
 
 def enrolled_students(gl, course):
     """Returns the students enrolled in the course
+
+    Args:
+        gl: Gitlab API object
+        course: course the students are enrolled in
     """
 
     students = None
@@ -66,6 +92,12 @@ def enrolled_students(gl, course):
 def create_user(gl, student, ldap_base, ldap_provider):
     """Creates a GitLab user account student.
     Requires admin privileges.
+
+    Args:
+        gl: Gitlab API object
+        student: student to create user for
+        ldap_base: the search base string for the LDAP query
+        ldap_provider: LDAP provider configured for Gitlab (usually `main`)
     """
 
     user = gl.users.create({
@@ -84,6 +116,10 @@ def create_user(gl, student, ldap_base, ldap_provider):
 
 def get_student_group(gl, course_name):
     """Gets the `students` subgroup for the course
+
+    Args:
+        gl: Gitlab API objects
+        course_name: name of the course
     """
 
     course = None
@@ -108,6 +144,11 @@ def get_student_group(gl, course_name):
 
 def enroll_student(gl, user, subgroup):
     """Adds a student to the course
+
+    Args:
+        gl: Gitlab API object
+        user: user to add to the course
+        subgroup: student will become member of this group
     """
 
     subgroup.members.create({