From edd308283105dbfcdae63be57c9dd20fa675a787 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C3=ABl=20Minelli?= <michael@minelli.me>
Date: Fri, 29 Sep 2023 01:16:56 +0200
Subject: [PATCH] Wiki => Reorganisation
---
Wiki/CLI-user-documentation.md | 230 ------------------
.../0-Exercise-perform.md} | 0
.../1-Assignment-creation.md} | 0
Wiki/UserDocumentation/0-Installation.md | 32 +++
Wiki/UserDocumentation/1-Authentification.md | 48 ++++
.../2-Assignment-creation.md | 66 +++++
Wiki/UserDocumentation/3-Exercise-creation.md | 73 ++++++
Wiki/home.md | 18 +-
8 files changed, 232 insertions(+), 235 deletions(-)
delete mode 100644 Wiki/CLI-user-documentation.md
rename Wiki/{CLI-exercise-perform.md => Tutorials/0-Exercise-perform.md} (100%)
rename Wiki/{CLI-assignment-creation.md => Tutorials/1-Assignment-creation.md} (100%)
create mode 100644 Wiki/UserDocumentation/0-Installation.md
create mode 100644 Wiki/UserDocumentation/1-Authentification.md
create mode 100644 Wiki/UserDocumentation/2-Assignment-creation.md
create mode 100644 Wiki/UserDocumentation/3-Exercise-creation.md
diff --git a/Wiki/CLI-user-documentation.md b/Wiki/CLI-user-documentation.md
deleted file mode 100644
index 38d5e79..0000000
--- a/Wiki/CLI-user-documentation.md
+++ /dev/null
@@ -1,230 +0,0 @@
-# How to use the dojo CLI (version 2.0)
-
-There are four different parts covered in this chapter:
-- [Installation](#installation)
-- [Authentication](#authentication)
-- [Create an assignment](#create-an-assignment)
-- [Create an exercise](#create-an-exercise)
-
-## Installation
-
-1. Download the latest stable version (without "-dev" suffix) from the releases: <https://gitedu.hesge.ch/dojo_project/projects/ui/dojocli/-/releases>
-
-
-
-2. Download the executable corresponding to your OS and architecture.
- - ℹ️ For macOS users you can use the pkg version that install the binary at the right place (so you can ignore the next point).
-3. Put it in your path. For
- - ℹ️ Linux user this may be `$HOME/.local/bin` for example.
-4. Verify your installation is working correctly by calling the `dojo` CLI.
-```bash
-dojo
-```
-```console
-Usage: dojo [options] [command]
-
-CLI of the Dojo application
-
-Options:
- -h, --help display help for command
- -H, --host <string> override the Dojo API endpoint (default: "https://rdps.hesge.ch/dojo/api")
- -V, --version output the version number
-
-Commands:
- assignment manage an assignment
- exercise manage an exercise
- help [command] display help for command
- session manage Dojo and Gitlab sessions
-```
-
-As you can see calling the `dojo` command shows the help menu.
-
-## Authentication
-
-The authentication is done in two steps: login into the dojo app and into https://gitedu.hesge.ch (through an API token).
-
-1. Login into the dojo application:
-```bash
-dojo session application login --user <email>
-```
-```console
-? Please enter your password [hidden]
-Please wait while we are logging in you to Dojo...
-✔ Logged in
- ✔ Teaching staff permissions
- ✔ Student permissions
-```
-2. Register the API token (see below) for Gitlab
-```bash
-dojo session gitlab login <token>
-```
-```console
-Please wait while we are testing your Gitlab token...
-ℹ Checking Gitlab token:
- ✔ Read access
- ✔ Write access
-```
-The API token can be created by (see <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html> for more informations):
-
-- Logging into <https://gitedu.hesge.ch>
-- **Preferences -> Access Tokens**
-- Give a name to your token and a validity
-- Tick the **api** box
-- Click the **Create personal access token**
-
-3. Test if it is working
-```bash
-dojo session test
-```
-```console
-ℹ Checking Dojo session:
- ✔ The session is valid
- ✔ Teaching staff permissions
- ✔ Student permissions
-ℹ Checking Gitlab token:
- ✔ Read access
- ✔ Write access
-```
-
-Good news. You can use the Dojo!
-
-## Create an assignment
-
-The assignment is created by a teacher typically and is the basis for students to perform their exercise.
-
-1. To create an assignment
-```bash
-dojo assignment create --name <unique_name>
-```
-```console
-Please wait while we verify and retrieve data...
-ℹ Checking Dojo session:
- ✔ The session is valid
- ✔ Teaching staff permissions
-ℹ Checking Gitlab token:
- ✔ Read access
- ✔ Write access
-✔ Assignment name "unique_name" is available
-Please wait while we are creating the assignment...
-✔ Assignment successfully created
- ℹ Name: unique_name
- ℹ Web URL: https://gitedu.hesge.ch/dojo/assignment/unique_name
- ℹ HTTP Repo: https://gitedu.hesge.ch/dojo/assignment/unique_name.git
- ℹ SSH Repo: ssh://git@ssh.hesge.ch:10572/dojo/assignment/unique_name.git
-```
-where `<unique_name>` is the name of the assignment. By default only the creator of the exercise is added to
-the assignment (which is just a git repository with some configuration files in it).
-There are several other options that can be provided:
-```bash
-dojo assignment create --name <unique_name> --template <url>
-```
-where `<url>` is the url of the template repository one may want to use as a basis for the assignment-
-```bash
-dojo assignment create --name <unique_name> --members_username <usernames>
-```
-where `<usernames>` is a list of gitedu usernames that will be given the same permissions as the
-user creating the assignment.
-
-As usual one can show the help menu by typing
-```bash
-dojo assignment create --help
-```
-Or you may just enter (`--help` is implicit in most commands)
-```bash
-dojo assignment create
-```
-2. Clone the repository of the assignment that was just created:
-```bash
-git clone ssh://git@ssh.hesge.ch:10572/dojo/assignment/unique_name.git
-```
-3. Modify the `unique_name` assignment as you want (modify the Dockerfile, docker-compose.yml files, add a readme, source code, compilation tools, etc.). Commit and push our work (soon™ more details will be provided on how to create assignment).
-4. Once the assignment is done it must be published to be available to students:
-```bash
-dojo assignment publish unique_name
-```
-```console
-? Are you sure you want to publish this assignment? Yes
-Please wait while we verify and retrieve data...
-ℹ Checking Dojo session:
- ✔ The session is valid
-ℹ Checking assignment:
- ℹ unique_name
- ✔ The assignment exists
- ✔ You are in the staff of this assignment
-Please wait while we publish the assignment...
-✔ Assignment unique_name successfully published
-```
-
-## Create an exercise
-
-The exercise is an instance of a **published assignment** to be performed by students (or group of students).
-
-1. Create an exercise
-```bash
-dojo exercise create --assignment unique_name
-```
-```console
-Please wait while we verify and retrieve data...
-ℹ Checking Dojo session:
- ✔ The session is valid
- ✔ Student permissions
-ℹ Checking Gitlab token:
- ✔ Read access
- ✔ Write access
-ℹ Checking assignment:
- ✔ Assignment "unique_name" exists
- ✔ Assignment "unique_name" is published
-Please wait while we are creating the exercise...
-✔ Exercise successfully created
- ℹ Id: some-long-hash
- ℹ Name: DojoEx - unique_name - your.name
- ℹ Web URL: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_unique_name_some-long-hash
- ℹ HTTP Repo: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_unique_name_some-long-hash.git
- ℹ SSH Repo: ssh://git@ssh.hesge.ch:10572/dojo/exercise/dojo-ex_unique_name_some-long-hash.git
-```
-2. Make changes and try solving the exercise.
-3. The complete tests can be run with the following command.
-```bash
-dojo exercise run
-```
-```console
-Please wait while we are checking and creating dependencies...
- ℹ Checking exercise content:
- ✔ The exercise folder contains all the needed files
- ✔ The dojo_assignment.json file is valid
- ✔ The Docker deamon is running
-Please wait while we are running the exercise...
- ✔ Docker Compose file run successfully
- ✔ Linked services logs acquired
- ✔ Containers stopped and removed
-Please wait while we are checking the results...
- ✔ Results file found
- ✔ Results file is valid
- ✔ Results folder size is in bounds
-
- ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
- ┃ ┃
- ┃ Global result : ✅ Success ┃
- ┃ ┃
- ┃ Execution exit code : 0 ┃
- ┃ ┃
- ┃ Tests passed : 3 ┃
- ┃ Tests failed : 1 ┃
- ┃ ┃
- ┃ Tests : ┃
- ┃ - ✅ ListeOrdonnee ┃
- ┃ - ✅ ListeVide ┃
- ┃ - ✅ ListeOrdreInverse ┃
- ┃ - ❌ ListeRandom ┃
- ┃ ┃
- ┃ Execution results folder : /home/username/DojoExecutions/dojo_execLogs_2023-08-21T21_33_38_684Z ┃
- ┃ ┃
- ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-```
-This command runs the exercise in the current directory or in the path provided by the `--path` option.
-
-4. Once confident enough in the solution, one can commit/push the solution.
-This triggers the CI/CD pipeline on gitedu. In the CI/CD all immutable files are overwritten and
-the docker-compose is executed (only logs from the current container are given) then other logs
-are retrieved from the other images that may be used. The error code of the docker container is retrieved.
-
diff --git a/Wiki/CLI-exercise-perform.md b/Wiki/Tutorials/0-Exercise-perform.md
similarity index 100%
rename from Wiki/CLI-exercise-perform.md
rename to Wiki/Tutorials/0-Exercise-perform.md
diff --git a/Wiki/CLI-assignment-creation.md b/Wiki/Tutorials/1-Assignment-creation.md
similarity index 100%
rename from Wiki/CLI-assignment-creation.md
rename to Wiki/Tutorials/1-Assignment-creation.md
diff --git a/Wiki/UserDocumentation/0-Installation.md b/Wiki/UserDocumentation/0-Installation.md
new file mode 100644
index 0000000..a23cd08
--- /dev/null
+++ b/Wiki/UserDocumentation/0-Installation.md
@@ -0,0 +1,32 @@
+# Installation of the Dojo CLI
+
+1. Download the latest stable version (without "-dev" suffix) from the releases: <https://gitedu.hesge.ch/dojo_project/projects/ui/dojocli/-/releases>
+
+
+
+2. Download the executable corresponding to your OS and architecture.
+ - ℹ️ For macOS users you can use the pkg version that install the binary at the right place (so you can ignore the next point).
+3. Put it in your path. For
+ - ℹ️ Linux user this may be `$HOME/.local/bin` for example.
+4. Verify your installation is working correctly by calling the `dojo` CLI.
+```bash
+dojo
+```
+```console
+Usage: dojo [options] [command]
+
+CLI of the Dojo application
+
+Options:
+ -h, --help display help for command
+ -H, --host <string> override the Dojo API endpoint (default: "https://rdps.hesge.ch/dojo/api")
+ -V, --version output the version number
+
+Commands:
+ assignment manage an assignment
+ exercise manage an exercise
+ help [command] display help for command
+ session manage Dojo and Gitlab sessions
+```
+
+As you can see calling the `dojo` command shows the help menu.
\ No newline at end of file
diff --git a/Wiki/UserDocumentation/1-Authentification.md b/Wiki/UserDocumentation/1-Authentification.md
new file mode 100644
index 0000000..16cc47b
--- /dev/null
+++ b/Wiki/UserDocumentation/1-Authentification.md
@@ -0,0 +1,48 @@
+# Authentication to the Dojo
+
+The authentication is done in two steps: login into the dojo app and into https://gitedu.hesge.ch (through an API token).
+
+1. Login into the dojo application:
+```bash
+dojo session application login --user <email>
+```
+```console
+? Please enter your password [hidden]
+Please wait while we are logging in you to Dojo...
+✔ Logged in
+ ✔ Teaching staff permissions
+ ✔ Student permissions
+```
+2. Register the API token (see below) for Gitlab
+```bash
+dojo session gitlab login <token>
+```
+```console
+Please wait while we are testing your Gitlab token...
+ℹ Checking Gitlab token:
+ ✔ Read access
+ ✔ Write access
+```
+The API token can be created by (see <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html> for more informations):
+
+- Logging into <https://gitedu.hesge.ch>
+- **Preferences -> Access Tokens**
+- Give a name to your token and a validity
+- Tick the **api** box
+- Click the **Create personal access token**
+
+3. Test if it is working
+```bash
+dojo session test
+```
+```console
+ℹ Checking Dojo session:
+ ✔ The session is valid
+ ✔ Teaching staff permissions
+ ✔ Student permissions
+ℹ Checking Gitlab token:
+ ✔ Read access
+ ✔ Write access
+```
+
+Good news. You can use the Dojo!
diff --git a/Wiki/UserDocumentation/2-Assignment-creation.md b/Wiki/UserDocumentation/2-Assignment-creation.md
new file mode 100644
index 0000000..15c7392
--- /dev/null
+++ b/Wiki/UserDocumentation/2-Assignment-creation.md
@@ -0,0 +1,66 @@
+# Assignment creation
+
+The assignment is created by a member of the teaching staff and is the basis for students to perform their exercise.
+
+1. To create an assignment
+```bash
+dojo assignment create --name <unique_name>
+```
+```console
+Please wait while we verify and retrieve data...
+ℹ Checking Dojo session:
+ ✔ The session is valid
+ ✔ Teaching staff permissions
+ℹ Checking Gitlab token:
+ ✔ Read access
+ ✔ Write access
+✔ Assignment name "unique_name" is available
+Please wait while we are creating the assignment...
+✔ Assignment successfully created
+ ℹ Name: unique_name
+ ℹ Web URL: https://gitedu.hesge.ch/dojo/assignment/unique_name
+ ℹ HTTP Repo: https://gitedu.hesge.ch/dojo/assignment/unique_name.git
+ ℹ SSH Repo: ssh://git@ssh.hesge.ch:10572/dojo/assignment/unique_name.git
+```
+where `<unique_name>` is the name of the assignment. By default only the creator of the exercise is added to
+the assignment (which is just a git repository with some configuration files in it).
+There are several other options that can be provided:
+```bash
+dojo assignment create --name <unique_name> --template <url>
+```
+where `<url>` is the url of the template repository one may want to use as a basis for the assignment-
+```bash
+dojo assignment create --name <unique_name> --members_username <usernames>
+```
+where `<usernames>` is a list of gitedu usernames that will be given the same permissions as the
+user creating the assignment.
+
+As usual one can show the help menu by typing
+```bash
+dojo assignment create --help
+```
+Or you may just enter (`--help` is implicit in most commands)
+```bash
+dojo assignment create
+```
+2. Clone the repository of the assignment that was just created:
+```bash
+git clone ssh://git@ssh.hesge.ch:10572/dojo/assignment/unique_name.git
+```
+3. Modify the `unique_name` assignment as you want (modify the Dockerfile, docker-compose.yml files, add a readme, source code, compilation tools, etc.). Commit and push our work (soon™ more details will be provided on how to create assignment).
+4. Once the assignment is done it must be published to be available to students:
+```bash
+dojo assignment publish unique_name
+```
+```console
+? Are you sure you want to publish this assignment? Yes
+Please wait while we verify and retrieve data...
+ℹ Checking Dojo session:
+ ✔ The session is valid
+ℹ Checking assignment:
+ ℹ unique_name
+ ✔ The assignment exists
+ ✔ You are in the staff of this assignment
+Please wait while we publish the assignment...
+✔ Assignment unique_name successfully published
+```
\ No newline at end of file
diff --git a/Wiki/UserDocumentation/3-Exercise-creation.md b/Wiki/UserDocumentation/3-Exercise-creation.md
new file mode 100644
index 0000000..a4e8a19
--- /dev/null
+++ b/Wiki/UserDocumentation/3-Exercise-creation.md
@@ -0,0 +1,73 @@
+# Exercise creation
+
+The exercise is an instance of a **published assignment** to be performed by students (or group of students).
+
+1. Create an exercise
+```bash
+dojo exercise create --assignment unique_name
+```
+```console
+Please wait while we verify and retrieve data...
+ℹ Checking Dojo session:
+ ✔ The session is valid
+ ✔ Student permissions
+ℹ Checking Gitlab token:
+ ✔ Read access
+ ✔ Write access
+ℹ Checking assignment:
+ ✔ Assignment "unique_name" exists
+ ✔ Assignment "unique_name" is published
+Please wait while we are creating the exercise...
+✔ Exercise successfully created
+ ℹ Id: some-long-hash
+ ℹ Name: DojoEx - unique_name - your.name
+ ℹ Web URL: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_unique_name_some-long-hash
+ ℹ HTTP Repo: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_unique_name_some-long-hash.git
+ ℹ SSH Repo: ssh://git@ssh.hesge.ch:10572/dojo/exercise/dojo-ex_unique_name_some-long-hash.git
+```
+2. Make changes and try solving the exercise.
+3. The complete tests can be run with the following command.
+```bash
+dojo exercise run
+```
+```console
+Please wait while we are checking and creating dependencies...
+ ℹ Checking exercise content:
+ ✔ The exercise folder contains all the needed files
+ ✔ The dojo_assignment.json file is valid
+ ✔ The Docker deamon is running
+Please wait while we are running the exercise...
+ ✔ Docker Compose file run successfully
+ ✔ Linked services logs acquired
+ ✔ Containers stopped and removed
+Please wait while we are checking the results...
+ ✔ Results file found
+ ✔ Results file is valid
+ ✔ Results folder size is in bounds
+
+ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+ ┃ ┃
+ ┃ Global result : ✅ Success ┃
+ ┃ ┃
+ ┃ Execution exit code : 0 ┃
+ ┃ ┃
+ ┃ Tests passed : 3 ┃
+ ┃ Tests failed : 1 ┃
+ ┃ ┃
+ ┃ Tests : ┃
+ ┃ - ✅ ListeOrdonnee ┃
+ ┃ - ✅ ListeVide ┃
+ ┃ - ✅ ListeOrdreInverse ┃
+ ┃ - ❌ ListeRandom ┃
+ ┃ ┃
+ ┃ Execution results folder : /home/username/DojoExecutions/dojo_execLogs_2023-08-21T21_33_38_684Z ┃
+ ┃ ┃
+ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+This command runs the exercise in the current directory or in the path provided by the `--path` option.
+
+4. Once confident enough in the solution, one can commit/push the solution.
+This triggers the CI/CD pipeline on gitedu. In the CI/CD all immutable files are overwritten and
+the docker-compose is executed (only logs from the current container are given) then other logs
+are retrieved from the other images that may be used. The error code of the docker container is retrieved.
+
diff --git a/Wiki/home.md b/Wiki/home.md
index cc7e0cc..8845268 100644
--- a/Wiki/home.md
+++ b/Wiki/home.md
@@ -2,12 +2,20 @@
In this wiki you will find the documentation related to the `dojo` CLI.
-* [User documentation](CLI-user-documentation)
-## Assignment documentation
-* [Assignment creation](CLI-assignment-creation)
-## Exercise documentation
+## User documentation
-* [How to perform an exercise](CLI-exercise-perform)
+* [Installation of the CLI](UserDocumentation/0-Installation)
+* [Authentification](UserDocumentation/1-Authentification)
+* [Assignment creation](UserDocumentation/2-Assignment-creation)
+* [Exercice creation](UserDocumentation/3-Exercise-creation)
+
+## Tutorials / Exemples
+
+### Students / Everyone
+* [How to perform an exercise](Tutorials/0-Exercise-perform)
+
+### Teaching staff
+* [How to create and publish an assignment](Tutorials/1-Assignment-creation)
--
GitLab