Commit 50ba4000 authored by Cyril Matthey-Doret's avatar Cyril Matthey-Doret
Browse files

Write readme with utilities description

parent 2bacdf96
Pipeline #326963 passed with stage
in 18 seconds
# advanced-teaching-automation
# Advanced teaching automation
Leverage Renku and Gitlab to automate class management
Leverage Renku and Gitlab to automate class management.
## Introduction
## Target audience
This is a Renku project - basically a git repository with some
bells and whistles. You'll find we have already created some
useful things like `data` and `notebooks` directories and
a `Dockerfile`.
This repository is intended for technically inclined teachers who use Renku and/or Gitlab in their class and wish to automate repetitive tasks related to student and project management.
## Working with the project
## Purpose
The simplest way to start your project is right from the Renku
platform - just click on the `Environments` tab and start a new session.
This will start an interactive environment right in your browser.
We showcase the potential of Renku + Gitlab through a few scripts covering common use-cases.
These scripts can be used as-provided, but are also meant to be extended and adapted by teachers for their own use-cases.
To work with the project anywhere outside the Renku platform,
click the `Settings` tab where you will find the
git repo URLs - use `git` to clone the project on whichever machine you want.
## Content
### Changing interactive environment dependencies
The following tasks are covered:
Initially we install a very minimal set of packages to keep the images small.
However, you can add python and conda packages in `requirements.txt` and
`environment.yml` to your heart's content. If you need more fine-grained
control over your environment, please see [the documentation](https://renku.readthedocs.io/en/latest/user/advanced_interfaces.html#dockerfile-modifications).
### Inviting students to the class group
## Project configuration
Creating a single group for the class allows to have a centralizd place to store all materials, students repositories and exercises. In some cases, one may also want to make this group private.
Project options can be found in `.renku/renku.ini`. In this
project there is currently only one option, which specifies
the default type of environment to open, in this case `/lab` for
JupyterLab. You may also choose `/tree` to get to the "classic" Jupyter
interface.
The manual process of inviting the whole class to the group can be automated using Gitlab's invitation API. Given a list of student email addresses (e.g. exported from moodle) and the URL to a gitlab group, we provide a script to automatically send an invitation email to each student.
## Moving forward
script: [scripts/invite_students.py](scripts/invite_students.py)
Once you feel at home with your project, we recommend that you replace
this README file with your own project documentation! Happy data wrangling!
\ No newline at end of file
usage: `python invite_moodle.py moodle_students_list.csv https://gitlab-instance.com/group-name`
### Creating student groups
When students work on graded assignments, they will usually have to work in private groups. The groups must be accessible to the teachers in order to grade the assignments.
One way to achieve this is to have the teacher create all private student groups (they will therefore be the group owner) and then invite students to their respective groups. We provide a script to automate the group creation and invitation process.
script: [scripts/create_student_groups.py](scripts/create_student_groups.py)
usage: `python create_student_groups.py] students_moodle.csv`
### Gathering all forks of a project
Homework assignment can be provided by the teachers in the form of a repository containing instructions and depencencies required. Students can then fork this project into their own private groups (e.g. created with the script above).
The teacher can then use the Gitlab API to keep track of all student's forks. We provide a script to gather metadata about all student-group forks of a given project, with the option to retrieve the last commit before a deadline. That script will output the metadata as a JSON structure containing the following fields for each fork:
* id: The gitlab project ID of the fork
* url: The https URL to reach the fork
* group: The student group name
* members: The members of the group. For each member the following fields are provided:
+ username: The gitlab username
+ name: The full name (First_name Last_name)
+ email: The email address of the student
* commit: The hash of the last commit before the deadline, used for grading the assignment.
* autostart_url: A URL to directly start a Renku session at the last commit before the deadline.
script: [scripts/collect_forks.py](scripts/collect_forks.py)
usage:
```sh
python collect_forks.py \
--token token.asc \
--deadline "YYYY-MM-DDThh-mm-ss" \
https://gitlab-instance.com/namespace/upstream-project \
> forks.json
```
### Cloning all forks of a project
In some cases, the student projects may have to be cloned locally by the teacher. We provide a shell script to automate this process. This script will read the JSON output from `collect_forks.py` and clone all the forks at the deadline commit into a target directory.
script: [scripts/clone_forks.sh](scripts/clone_forks.sh)
usage: `python clone_forks.sh forks.json clone_dir`
### Sending feedback
After grading student assignment, the teacher may want to send student groups their grades, as well as positive or critical comments on their solution. This can be automated as well, using the Gitlab issues API. We provide a script to read a csv file containing grades and comments for each student group and open issues in the corresponding repositories automatically.
> TODO
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment