Merge TEACH.md into other docs

README.md

@@ -5,6 +5,8 @@
 
 This repo contains (codified) instructions for deploying the eWaterCycle platform. The target audience of these instructions are system administrators. For more information on the eWaterCycle platform (and how to deploy it) see the [eWaterCycle documentation](https://ewatercycle.readthedocs.io/).
 
+With grading setup is [one class, one grader](https://nbgrader.readthedocs.io/en/stable/configuration/jupyterhub_config.html#example-use-case-one-class-one-grader).
+
 For instructions on how to use the machine as deployed by this repo see the [User guide](USER.md).
 
 These instructions assume you have some basic knowledge of [vagrant](https://vagrantup.com) and
@@ -100,7 +102,7 @@ For eWatercycle component following specialization was done
   - Select cloud providers:
     - SURF HPC Cloud, with all non-gpu sizes selected
     - SURF HPC Cloud cluster, with all non-gpu sizes selected
-- Component parameters, all fixed source type and overwitable unless otherwise stated
+- Component parameters, all fixed source type, required and overwitable unless otherwise stated
   - Add `dcache_ro_token` parameter for dcache read-only token aka macaroon.
     The token can be found in the eWaterCycle password manager.
     This token has an expiration date, so it needs to be updated every now and then.
@@ -116,6 +118,7 @@ For eWatercycle component following specialization was done
     This user will also be responsible for setting up the course and assignments.
   - Add `students` parameter with list of student usernames and passwords.
     The value should be a JSON string in format of `[["username1", "password1"]]`. 
+    Use '[]` as initial value.
     Description should be `List of student user name and passwords. Format '[["<username1>","<password1>"]]'. Use '[]' for no students.`.
   - Add `course_repo` parameter with git repository url of the course source material.
     Use default value of `https://github.com/eWaterCycle/teaching.git`
@@ -184,9 +187,8 @@ This chapter is dedicated for application deployers.
 1. Select eWaterCycle application
 1. Select collaborative organisation (CO) for example `ewatercycle-nlesc`
 1. Select size of VM (cpus/memory) based on use case
-1. Select home storage item.
-   - Order in which the storage items are select is important, make sure to select home before cache storage item.
-1. Select cache storage item
+1. Select home storage item and cache storage item. Remember items you picked as you will need them in the workspace parameters.
+1. Fill all the workspace parameters. 
 1. Wait for machine to be running
 1. Visit URL/IP
 1. When done delete machine
@@ -200,6 +202,11 @@ End user should be invited to CO so they can login.
 
 See [User guide](USER.md) to see what users have to do to login or use GitHub repository.
 
+### Students
+
+During creation you can set the `students` parameter to create local posix accounts for students.
+The value for the `students` parameter is a list of [student, password] values. You can use the python script [create_student_passwords.py](create_student_passwords.py) to generate passwords. To use it, create a file "usernames.txt" with one username on each line. Then call the script to generate passwords. They will be stored in a new file called `students.json`. See docs in script for more details. The passwords generated by the script should be distributed to the students.
+
 ### Example notebooks
 
 To get example notebooks end users should use following URL (with `<workspace id>` with your currently running workspace)

USER.md

@@ -1,5 +1,44 @@
 # User guide
 
+- [User guide](#user-guide)
+  - [Grading](#grading)
+    - [Students](#students)
+    - [Create assignment](#create-assignment)
+    - [Fetch assignment](#fetch-assignment)
+  - [Logging into server](#logging-into-server)
+  - [Save notebooks to GitHub](#save-notebooks-to-github)
+    - [1. Create GitHub account](#1-create-github-account)
+    - [2. Create GitHub repository](#2-create-github-repository)
+    - [3. Setup GitHub authentication on server](#3-setup-github-authentication-on-server)
+    - [4. Clone repository](#4-clone-repository)
+    - [5. Add \& commit \& push notebooks on server to GitHub](#5-add--commit--push-notebooks-on-server-to-github)
+    - [6. Pull changes from GitHub to server](#6-pull-changes-from-github-to-server)
+  - [Install own software](#install-own-software)
+
+## Grading
+
+One user is the grader on the machine following section is for that user.
+
+### Students
+
+Assigning students to courses can be managed with [nbgrader labextension & cli](https://nbgrader.readthedocs.io/en/stable/user_guide/managing_the_database.html#managing-students).
+
+The student id is a posix username in the VM.
+In a ewatercycle VM, users can be added during workspace creation or with [Surf Research Access Management](https://sram.surf.nl/) or later with `sudo adduser`.
+After sram invite a cronjob will add the user to the VM. Login with totp as password.
+
+### Create assignment
+
+1. In menu goto Nbgrader -> Formgrader -> Manage Assignments -> Add new Assignment.
+2. Click on edit to navigate to folder (`~/course1/source/<name of assignment>`).
+3. Create a notebook with assignment annotations using the `Create Assignment` sidebar.
+4. In FormGrader press Generate, Preview, Release buttons.
+
+### Fetch assignment
+
+1. In menu got Nbgrader -> Assignments
+2. Press fetch button
+
 ## Logging into server
 
 You should have recieved a invitation to a eWatercycle collaborative organization, please follow instructions in email.
@@ -14,12 +53,6 @@ The username you should use to login can be found on on [SRC dashboard profile p
 The Jupyter notebooks that you write should be saved outside the Jupyter server.
 Code like notebooks can be saved git repositories on [GitHub](https://github.com/).
 
-- [1. Create GitHub account](#1-create-github-account)
-- [2. Create GitHub repository](#2-create-github-repository)
-- [3. Setup authenication on server](#3-setup-authenication-on-server)
-- [4. Clone repository](#4-clone-repository)
-- [5. Add & commit & push notebooks on server to GitHub](#5-add--commit--push-notebooks-on-server-to-github)
-- [6. Pull changes from GitHub to server](#6-pull-changes-from-github-to-server)
 
 ### 1. Create GitHub account