diff --git a/Rewritten-docs.md b/Rewritten-docs.md index 6614975..114792a 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -1637,7 +1637,7 @@ we will re-evaluate this decision. #### Communication with the backend -##### Backend failiure reporting +##### Backend failure reporting The backend is a separate component which does not communicate with the administrators directly. When it encounters an error it stores it in a log file. @@ -1777,6 +1777,7 @@ Described roles are: - Student - Group supervisor - Group administrator +- Instance administrator - Superadministrator ## Terminology @@ -1804,6 +1805,10 @@ They can be shared by the teachers using an exercise database in ReCodEx. **Assignment** -- An exercise assigned to a group, possibly with modifications. +**Runtime environment** -- @todo + +**Hardware group** -- @todo + ## General basics Description of general basics which are the same for all users of ReCodEx web @@ -2040,11 +2045,80 @@ to your group. ### Assigning exercises -@todo: Describe how to access the database of the exercises and what are -the possibilities of assignment setup – availability, deadlines, points, -score configuration, limits - -@todo: How can I assign some exercises only to some students of the group? Describe how to achieve this using subgroups +Before assigning exercise you obviously have to know what exercises are +available. List of all exercises in system can be found under "Exercises" link +in sidebar. This page contains table with exercises names, difficulties and +names of the authors of exercises. Further information about exercise is +available by clicking on its name. + +On the exercise details page can be found numerous information about it. There +is box with all possible localized descriptions and also box with some +additional information. Like when was exercise created by whom, what is +difficulty of it, what version is it. There is also description for supervisors +by exercise author under "Exercise overview" option, where some important +information can be found. And most notably there is information in what +programming languages can be exercises solved, this is available under +"Supported runtime environments" row. + +If you decide that exercise is suitable for some of your groups, please note +"Groups" box at the bottom of the page. There is list of all groups you +supervise with quick "Assign" button which will assign exercise to some +particular group. + +After clicking on "Assign" button you should be redirected to assignment +editation page. In there you can find two forms, one for editation of assignment +meta information and the second one for setting exercise time and memory limits. + +In meta information form you can fill these options: + +- name of the assignment which will be visible in group +- visibility, if assignment is under construction then you can mark it as not + visible and students will not see it +- subform for localized descriptions (new localization can be added by clicking + on "Add language variant" button, current one deleted with "Remove this + language" button) + - language of description from dropdown field (english, czech, german) + - description in selected language +- score configuration which will be used on students solution evaluation, + description of score configuration can be found further in "Writing score + configuration" chapter +- first submission deadline +- maximum gainable points before first deadline +- second submission deadline, after that students still can submit exercises but + no points for them +- maximum gainable points after first deadline and before second deadline +- submission count limit for students' solutions, after this amount students + cannot submit any other solutions +- visibility of memory and time ratios, if true then students can see for each + test percentage of used memory and time +- minimum percentage of points which submission have to gain otherwise it will + gain no points +- assignment is bonus one and points from it are not included in students + overall score + +Form has to be submitted with "Edit settings" button otherwise changes will not +be saved. + +The same editation page serves also for the purpose of assignment editation, not +only creation. That is why on the bottom of the page "Delete the assignment" box +can be found. Clearly the button "Delete" in there can be used to unassign +exercise from group. + +The last unexplored area is time and memory limits form. The whole form is +situated in box with tabs which are leading to particular runtime environments. +If you wish to not use one of these, locate "Remove" button at the bottom of the +box tab which will delete this environment from assignment. Please note that +this action is irreversible. + +In general one tab in environments box contains some basic information about +runtime environment and another nested tabbed box. In there you can find all +hardware groups which are available for exercise and you can set here particular +limits for all test cases. Time and memory limits can be set to all test cases, +time limits have to be filled in seconds (float), memory limits are in bytes +(int). If you are interested in some reference values to particular test case +then you can take a peek on collapsable "Reference solutions' evaluations" item. +If you are satisfied with changes you made to limits save form with "Change +limits" button right under environments box. ### Students' solutions management @@ -2113,6 +2187,13 @@ clicking on it some particular supervisor should not be supervisor of the group anymore. +## Instance administrator + +@todo: who is this? + +@todo: creating groups right in the instance + + ## Superadministrator Superadmin is user with the most priviledges and as such superadmin should be @@ -2153,6 +2234,38 @@ Roles description: application. +## Writing score configuration + +@todo: introduction to scoring, mention that there can be more implementation but for now only simple is available + +### Simple score calculation + +First implemented calculator is simple score calculator with test weights. This +calculator just looks at the score of each test and put them together according +to the test weights specified in assignment configuration. Resulting score is +calculated as a sum of products of score and weight of each test divided by the +sum of all weights. The algorithm in Python would look something like this: + +``` +sum = 0 +weightSum = 0 +for t in tests: + sum += t.score * t.weight + weightSum += t.weight +score = sum / weightSum +``` + +Sample score config in YAML format: + +```{.yml} +testWeights: + a: 300 # test with id 'a' has a weight of 300 + b: 200 + c: 100 + d: 100 +``` + + ## Writing job configuration To run and evaluate an exercise the backend needs to know the steps how to do