Commit 2beb7df8 authored by Cyril Matthey-Doret's avatar Cyril Matthey-Doret
Browse files

update command examples in README

parent 43636abb
......@@ -22,7 +22,19 @@ cd advanced-teaching-automation
pip install -e .
```
Most script below require a Gitlab API token. By default, you will be prompted for your token upon running the scripts, but you can also provide it as a plain text file with the `--token` option.
Installing the package this way allows you to modify / extend the code to match your personal needs.
If you don't need to modify it, you can also install it directly from the URL without cloning:
```
pip install git+https://renkulab.io/gitlab/learn-renku/teaching-on-renku/advanced-teaching-automation
```
## Usage
Once the package is installed, the command `teach-auto` will be available globally on your system. Each functionality is available as a subcommand. For example `teach-auto collect-forks`. Each command stands in its own python script which can also be executed directly, e.g. `python teach_auto/collect_forks.py`. Each command provides a `--help` flag to print the list of available options and usage information.
Most functionalities below require a Gitlab API token. By default, you will be prompted for your token upon running the scripts, but you can also provide it as a plain text file with the `--token` option.
## Content
......@@ -51,7 +63,7 @@ script: [teach\_utils/invite\_students.py](teach_utils/invite_students.py)
Invite students to `class-group`:
`python invite_students.py emails.txt https://gitlab-instance.com/class-group`
`teach-auto invite-students emails.txt https://gitlab-instance.com/class-group`
</details>
......@@ -72,7 +84,7 @@ script: [teach\_utils/moodle\_to\_student\_groups.py](teach_utils/moodle_to_stud
Create student (sub)groups inside `class-group`:
`python moodle_to_student_groups.py students_moodle.csv https://gitlab-instance.com/class-group`
`create-groups students_moodle.csv https://gitlab-instance.com/class-group`
</details>
......@@ -106,8 +118,9 @@ script: [teach\_utils/collect\_forks.py](teach_utils/collect_forks.py)
Collect all group-owned forks of upstream-project, and write the JSON list to `forks.json`. Commits and autostart URLs will point to the last commit before 23h59 on March 15, 2022:
```sh
python collect_forks.py \
teach-auto collect-forks \
--deadline "2022-03-15T23:59" \
--group-only \
https://gitlab-instance.com/namespace/upstream-project \
> forks.json
```
......@@ -147,19 +160,19 @@ In some cases, the student projects may have to be cloned locally by the teacher
<summary> <b>Read more...</b> </summary>
script: [teach\_utils/clone\_forks\_from\_json.sh](teach_utils/clone_forks_from_json.sh)
script: [teach\_utils/clone\_forks.py](teach_utils/clone_forks.py)
**usage**:
Clone all forks listed in `forks.json` into `clone_dir`:
`./clone_forks_from_json.sh forks.json clone_dir`
`teach-auto clone-forks forks.json clone_dir`
Or reading directly from stdin:
```
python ./collect_forks.py https://gitlab-instance.com/namespace/upstream-project \
| ./clone_forks_from_json.sh clone_dir
teach-auto collect-forks https://gitlab-instance.com/namespace/upstream-project \
| teach-auto clone_forks clone_dir
```
</details>
......@@ -179,7 +192,7 @@ script: [teach\_utils/send\_feedback.py](teach_utils/send_feedback.py)
By default, this script opens issues in all forks listed in `forks.json`. For each fork, fields {grades}, {comments} in the issue description are filled using column values in a CSV file provided with `--feedback`. The issue description uses a default template defined in the script:
`python ./send_feedback.py --feedback grades.csv forks.json`
`teach-auto send-feedback --feedback grades.csv forks.json`
where grades.csv is:
......@@ -194,9 +207,9 @@ A custom template can also be provided, and fields will be replaced by values fr
```
echo ":warning: Your fork is public, please make it private!" > visibility.md
./collect_forks.py https://renkulab.io/gitlab/class/homework \
teach-auto collect-forks https://renkulab.io/gitlab/class/homework \
| jq '.[] | select(.visibility == "public")' \
| ./send_feedback.py --template visibility.md
| teach-auto send-feedback --template visibility.md
```
> Note: `jq` is a tool to process JSON data. It can be used to reformat or filter the output of `collect_forks.py` in many ways. A number of useful one liners are [shown here](./docs/oneliners.md).
......@@ -210,4 +223,4 @@ Testing is done with `pytest --doctest-modules` and can be run with `make test`.
## License
These scripts are provided under the [MIT license](./LICENSE).
These scripts are provided under the [MIT license](./LICENSE).
\ No newline at end of file
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