LEdoian
/
recodex-wiki
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'master' of https://github.com/ReCodEx/wiki.wiki

Browse Source
master
Petr Stefan 8 years ago
parent 8cdac3f704 625fbf917f
commit 21eb77aed1
1 changed files with 126 additions and 122 deletions
Show Stats Download Patch File Download Diff File

248
Rewritten-docs.md
Unescape Escape View File

@ -1770,24 +1770,23 @@ modern web applications.
# User documentation # User documentation
Users interact with the ReCodEx through the web application. It is required to Users interact with the ReCodEx through the web application. It is required to
use a modern web browser with good HTML5 and CSS3 support. Among others cookies use a modern web browser with good HTML5 and CSS3 support. Among others, cookies
and local storage are used. Also a decent JavaScript runtime must be provided by and local storage are used. Also a decent JavaScript runtime must be provided by
the browser. the browser.
Supported and tested browsers are: Firefox 50+, Chrome 55+, Opera 42+ and Edge Supported and tested browsers are: Firefox 50+, Chrome 55+, Opera 42+ and Edge
13+. Mobile devices often have problems with internalization and possibly lack 13+. Mobile devices often have problems with internationalization and possibly
support for some common features of desktop browsers. For us in this stage of lack support for some common features of desktop browsers. In this stage of
development is not possible to fine tune the interface for major mobile browsers development is not possible for us to fine tune the interface for major mobile
on all mobile platforms. However, it is confirmed to work with latest Google browsers on all mobile platforms. However, it is confirmed to work with latest
Chrome and Gello browser on Android 7.1+. There are reported some issues with Google Chrome and Gello browser on Android 7.1+. Issues have been reported with
Firefox which may be fixed in future. Also, it is confirmed working with Safari Firefox that will be fixed in the future. Also, it is confirmed to work with
browser on iOS 10. Safari browser on iOS 10.
Usage of the web application is divided into the sections concerning the Usage of the web application is divided into sections concerning particular user
particular user roles. Under these sections all possible use cases can be found. roles. Under these sections all possible use cases can be found. These sections
These sections are inclusive, so more privileged users need to know stuff from are inclusive, so more privileged users need to read instructions for all less
all less or equal privileged sections than their level of privilege. privileged users. Described roles are:
Described roles are:
- Student - Student
- Group supervisor - Group supervisor
@ -1837,26 +1836,26 @@ application follows.
### First steps in ReCodEx ### First steps in ReCodEx
You can create an account if you click on the "*Create account*" menu item in You can create an account by clicking the "*Create account*" menu item in
the left sidebar. You can choose between two types of registration methods -- by the left sidebar. You can choose between two types of registration methods -- by
creating a local account with a specific password, or pairing your new account creating a local account with a specific password, or pairing your new account
with an existing CAS UK account. with an existing CAS UK account.
If you decide a new "*local*" account using the "*Create ReCodEx account*” form, If you decide to create a new "*local*" account using the "*Create ReCodEx
you will have to provide your details and choose a password for your account. account*” form, you will have to provide your details and choose a password for
Although ReCodEx allows using quite weak passwords, it is wise to use a bit your account. Although ReCodEx allows using quite weak passwords, it is wise to
stronger ones. The actual strength is shown in progress bar near the password use a bit stronger ones The actual strength is shown in progress bar near the
field during registration. You will later sign in using your email address as password field during registration. You will later sign in using your email
your username and the password you select. address as your username and the password you select.
If you decide to use the CAS UK, then ReCodEx will verify your CAS credentials If you decide to use the CAS UK service, then ReCodEx will verify your CAS
and create a new account based on information stored there (name and email credentials and create a new account based on information stored there (name and
address). You can change your personal information later on the "*Settings*" email address). You can change your personal information later on the
page. "*Settings*" page.
When creating the account both ways, an instance the account will belong to must Regardless of the desired account type, an instance it will belong to must be
be selected. The instance will be most likely your university or other selected. The instance will be most likely your university or other organization
organization you are a member of. you are a member of.
To log in, go to the homepage of ReCodEx and in the left sidebar choose the menu To log in, go to the homepage of ReCodEx and in the left sidebar choose the menu
item "*Sign in*". Then you must enter your credentials into one of the two forms item "*Sign in*". Then you must enter your credentials into one of the two forms
@ -1876,24 +1875,25 @@ There are several options you can edit in your user account:
You can access the settings page through the "*Settings*" button right under You can access the settings page through the "*Settings*" button right under
your name in the left sidebar. your name in the left sidebar.
If you do not use ReCodEx for a whole day, you will be logged out automatically. If you are not active in ReCodEx for a whole day, you will be logged out
However, we recommend you sign out of the application after you finished your automatically. However, we recommend you sign out of the application after you
interaction with it. The logout button is placed in the top section of the left finish your interaction with it. The logout button is placed in the top section
sidebar right under your name. You may need to expand the sidebar with a button of the left sidebar right under your name. You may need to expand the sidebar
next to the "*ReCodEx*” title (also known as _hamburger button_). with a button next to the "*ReCodEx*” title (informally known as _hamburger
button_), depending on your screen size.
### Forgotten password ### Forgotten password
If you cannot remember your password and you do not use CAS UK authentication, If you cannot remember your password and you do not use CAS UK authentication,
then you can reset your password. You will find a link saying "Cannot remember then you can reset your password. You will find a link saying "Cannot remember
what your password was? Reset your password." under the sign in form. After you what your password was? Reset your password." under the sign in form. After you
click on this link, you will be asked to submit your registration email address. click this link, you will be asked to submit your registration email address. A
A message with a link containing a special token will be sent to your address. message with a link containing a special token will be sent to you by e-mail --
We make sure that the person who requested password resetting is really you. we make sure that the person who requested password resetting is really you.
When you click on the link (or you copy & paste it into your web browser) you When you visit the link, you will be able to enter a new password for your
will be able to select a new password for your account. The token is valid only account. The token is valid only for a couple of minutes, so do not forget to
for a couple of minutes, so do not forget to reset the password as soon as reset the password as soon as possible, or you will have to request a new link
possible, or you will have to request a new link with a valid token. with a valid token.
If you sign in through CAS UK, then please follow the instructions If you sign in through CAS UK, then please follow the instructions
provided by the administrators of the service described on their provided by the administrators of the service described on their
@ -1902,16 +1902,16 @@ website.
### Dashboard ### Dashboard
When you log into the system you should be redirected to your "*Dashboard*". On When you log into the system you should be redirected to your "*Dashboard*". On
this page according to your role in system you can see some brief information this page you can see some brief information about the groups you are member of.
about the groups you are member of. Further description of dashboard will be The information presented there varies with your role in the system -- further
provided later on with according roles. description of dashboard will be provided later on with according roles.
## Student ## Student
Student is a default role for every newly registered user. This role has quite Student is a default role for every newly registered user. This role has quite
limited range what can to do in ReCodEx. Generally student can only submit limited capabilites in ReCodEx. Generally, a student can only submit solutions
solutions of exercises in some particular groups. These groups should correspond of exercises in some particular groups. These groups should correspond to
to courses he/she attend at college. courses he/she attends.
On the "*Dashboard*" page there is "Groups you are student of" section where you On the "*Dashboard*" page there is "Groups you are student of" section where you
can find list of your student groups. In first column of every row there is a can find list of your student groups. In first column of every row there is a
@ -1924,17 +1924,16 @@ provided "Show group's detail" button.
### Join group and start solving assignments ### Join group and start solving assignments
To be able to submit solutions you have to be member of the right group. Each To be able to submit solutions you have to be a member of the right group. Each
instance have own group hierarchy, so you can choose only those from your instance has its own group hierarchy, so you can choose only those within your
instance. That is why list of groups is available from instance link located in instance. That is why a list of groups is available from under an instance link
sidebar. This link brings you to instance detail page. located in the sidebar. This link brings you to instance detail page.
In there you can see a description of the instance and most importantly in In there you can see a description of the instance and most importantly in
"Groups hierarchy" box there is a hierarchical list of all public groups in the "Groups hierarchy" box there is a hierarchical list of all public groups in the
instance. Please note that groups with plus sign are collapsible and can be instance. Please note that groups with plus sign are collapsible and can be
further extended. If you successfully located group you would like to join, further extended. When you find a group you would like to join, continue by
continue by clicking on "See group's page" link following with "Join group" clicking on "See group's page" link following with "Join group" link.
link.
**Note:** Some groups can be marked as private and these groups are not visible **Note:** Some groups can be marked as private and these groups are not visible
in hierarchy and membership cannot be established by students themselves. in hierarchy and membership cannot be established by students themselves.
@ -1942,17 +1941,17 @@ link.
On the group detail page there are multiple interesting things for you. First On the group detail page there are multiple interesting things for you. First
one is brief overview with information describing the group, there is list with one is brief overview with information describing the group, there is list with
supervisors and also hierarchy of subgroups. Most importantly there is supervisors and also hierarchy of subgroups. Most importantly, there is the
"Student's dashboard" section. This section contains list of assignments and "Student's dashboard" section. This section contains list of assignments and
list of fellow students. If supervisors of groups allowed students to see each a list of fellow students. If supervisors of groups allowed students to see each
others statistics there will also be points which particular students gained. other's statistics there will also be the number of points the students gained.
In the "Assignments" box on the group detail page there is list of assigned In the "Assignments" box on the group detail page there is a list of assigned
exercises which students are supposed to solve. The assignments are displayed exercises which students are supposed to solve. The assignments are displayed
with their names and deadlines. There are possibly two deadlines, the first one with their names and deadlines. There are possibly two deadlines, the first one
means that till this datetime student will receive full amount of points in case means that till this datetime student will receive full amount of points in case
of successful solution. Second deadline does not have to be set, but in case of of successful solution. Second deadline does not have to be set, but in case it
presence the maximum number of points for successful solution between these two is, the maximum number of points for successful solution between these two
deadlines can be different. deadlines can be different.
An assignment link will lead you to assignment detail page where are presented An assignment link will lead you to assignment detail page where are presented
@ -1968,28 +1967,28 @@ to submit solution of the assignment.
After clicking on submit button, dialog window will show up. In here you can After clicking on submit button, dialog window will show up. In here you can
upload files representing your solution, you can even add some notes to mark the upload files representing your solution, you can even add some notes to mark the
solution. Your supervisor can also access the note. After you successfully solution. Your supervisor can also access this note. After you successfully
uploaded all files necessary for your solution, click on "Submit your solution" upload all files necessary for your solution, click the "Submit your solution"
button and let ReCodEx do its thing. button and let ReCodEx evaluate the solution.
During the execution ReCodEx backend might send evaluation progress state to During the execution ReCodEx backend might send evaluation progress state to
your browser which will be displayed in another dialog window. When the whole your browser which will be displayed in another dialog window. When the whole
execution is finished then a "See the results" button will appear and you can execution is finished then a "See the results" button will appear and you can
look at the results of your solution. look at the results of your solution.
On the results detail page there are a lot of information. Apart assignment On the results detail page there are a lot of information. Apart from assignment
description which is not connected to your results there is also the solution description, which is not connected to your results, there is also the solution
submitter name (supervisor can submit solution on your behalf), further there submitter name (supervisor can submit a solution on your behalf), further there
are files which were uploaded on submission and most importantly "Evaluation are files which were uploaded on submission and most importantly "Evaluation
details" and "Test results" boxes. details" and "Test results" boxes.
Evaluation details contains overall results of your solution. There are Evaluation details contains overall results of your solution. There are
information such as if solution was provided before deadlines, if the evaluation information such as whether the solution was provided before deadlines, if the
process successfully finished or if compilation succeeded. After that you can evaluation process successfully finished or if compilation succeeded. After that
find a lot of values, most important one is the last, "Total score", consisting you can find a lot of values, most important one is the last, "Total score",
of your score, slash and the maximum number of points for this assignment. consisting of your score, slash and the maximum number of points for this
Interestingly the your score value can be higher than the maximum, which is assignment. Interestingly the your score value can be higher than the maximum,
caused by "Bonus points" item above. If your solution is nice and which is caused by "Bonus points" item above. If your solution is nice and
supervisor notices it, he/she can assign you additional points for effort. On supervisor notices it, he/she can assign you additional points for effort. On
the other hand, points can be also subtracted for bad coding habits or even the other hand, points can be also subtracted for bad coding habits or even
cheating. cheating.
@ -2019,10 +2018,10 @@ mechanism for new comment messages.
## Group supervisor ## Group supervisor
Group supervisor is ordinarily the lecturer of the corresponding course. With Group supervisor is typically the lecturer of a course. A user in this role can
this role user can modify group description and properties, assign exercises or modify group description and properties, assign exercises or manage list of
manage list of students. Further permissions like managing subgroups or students. Further permissions like managing subgroups or supervisors is
supervisors is available only for group administrators. available only for group administrators.
On "Dashboard" page you can find "Groups you supervise" section. Here there are On "Dashboard" page you can find "Groups you supervise" section. Here there are
boxes representing your groups with the list of students attending course and boxes representing your groups with the list of students attending course and
@ -2044,7 +2043,8 @@ at the top of the page. Following this link will take you to group editation
page with form containing these fields: page with form containing these fields:
- group name which is visible to other users - group name which is visible to other users
- external identification which may be used for ID from school system - external identification which may be used for pairing with entries in an
information system
- description of group which will be available to users in instance (in - description of group which will be available to users in instance (in
Markdown) Markdown)
- set if group is publicly visible (and joinable by students) or private - set if group is publicly visible (and joinable by students) or private
@ -2058,7 +2058,7 @@ group" button and all changes will be applied.
For students management there are "Students" and "Add student" boxes. The first For students management there are "Students" and "Add student" boxes. The first
one is simple list of all students which are attending the course with the one is simple list of all students which are attending the course with the
possibility of delete them from the group. That can be done by hitting "Leave possibility of delete them from the group. That can be done by hitting "Leave
group" button near particular user. Second box serves to adding students to the group" button near particular user. The second box is for adding students to the
group. There is a text field for typing name of the student and after clicking group. There is a text field for typing name of the student and after clicking
on the magnifier image or pressing enter key there will appear list of matched on the magnifier image or pressing enter key there will appear list of matched
users. At this moment just click on the "Join group" button and student will be users. At this moment just click on the "Join group" button and student will be
@ -2066,8 +2066,8 @@ signed in to your group.
### Assigning exercises ### Assigning exercises
Before assigning exercise you obviously have to know what exercises are Before assigning an exercise, you obviously have to know what exercises are
available. List of all exercises in the system can be found under "Exercises" available. A list of all exercises in the system can be found under "Exercises"
link in sidebar. This page contains a table with exercises names, difficulties link in sidebar. This page contains a table with exercises names, difficulties
and names of the exercise authors. Further information about exercise is and names of the exercise authors. Further information about exercise is
available by clicking on its name. available by clicking on its name.
@ -2080,9 +2080,9 @@ where some important information can be found. And most notably there is an
information about available programming languages for this exercise, under information about available programming languages for this exercise, under
"Supported runtime environments" section. "Supported runtime environments" section.
If you decide that the exercise is suitable for any of your groups, please note If you decide that the exercise is suitable for one of your groups, look for the
"Groups" box at the bottom of the page. There is a list of all groups you "Groups" box at the bottom of the page. There is a list of all groups you
supervise with quick "Assign" button which will assign the exercise to the supervise with an "Assign" button which will assign the exercise to the
selected group. selected group.
After clicking on the "Assign" button you should be redirected to assignment After clicking on the "Assign" button you should be redirected to assignment
@ -2092,10 +2092,10 @@ meta information and the second one for setting exercise time and memory limits.
In meta information form you can fill these options: In meta information form you can fill these options:
- name of the assignment which will be visible in a group - name of the assignment which will be visible in a group
- visibility, if assignment is under construction then you can mark it as not - visibility (if an assignment is under construction then you can mark it as not
visible and students will not see it visible and students will not see it)
- subform for localized descriptions (new localization can be added by clicking - subform for localized descriptions (new localization can be added by clicking
on "Add language variant" button, current one deleted with "Remove this on "Add language variant" button, current one can be deleted with "Remove this
language" button) language" button)
- language of description from dropdown field (English, Czech, German) - language of description from dropdown field (English, Czech, German)
- description in selected language - description in selected language
@ -2103,21 +2103,21 @@ In meta information form you can fill these options:
can find some very simple one already in here, description of score can find some very simple one already in here, description of score
configuration can be found further in "Writing score configuration" chapter configuration can be found further in "Writing score configuration" chapter
- first submission deadline - first submission deadline
- maximum gainable points before first deadline; if you want to manage all - maximum points that can be gained before the first deadline; if you want to
points manually, set here 0 and then use concept of bonus points, which is manage all points manually, set it to 0 and then use bonus points, which are
described in the next subchapter described in the next subchapter
- second submission deadline, after that students still can submit exercises but - second submission deadline, after that students still can submit exercises but
no points for them (must be after the first deadline) they are given no points no points (must be after the first deadline)
- maximum gainable points after first deadline and before second deadline - maximum points that can be gained between first deadline and second deadline
- submission count limit for students' solutions, after this amount students - submission count limit for students' solutions -- limits the amount of
cannot submit solutions any more attempts a student has at solving the problem
- visibility of memory and time ratios; if true students can see percentage of - visibility of memory and time ratios; if true students can see the percentage
used memory and time for each test of used memory and time (with respect to the limit) for each test
- minimum percentage of points which each submission have to gain otherwise it - minimum percentage of points which each submission must gain to be considered
will gain no points correct (if it gets less, it will gain no points)
- assignment is marked as bonus one and points from solving it are not included - whether the assignment is marked as bonus one and points from solving it are
into group threshold limit (that means solving it can get you additional not included into group threshold limit (that means solving it can get you
points over the limit) additional points over the limit)
The form has to be submitted with "Edit settings" button otherwise changes will The form has to be submitted with "Edit settings" button otherwise changes will
not be saved. not be saved.
@ -2127,27 +2127,27 @@ only creation. That is why on bottom of the page "Delete the assignment" box
can be found. Clearly the button "Delete" in there can be used to unassign can be found. Clearly the button "Delete" in there can be used to unassign
exercise from group. exercise from group.
The last unexplored area is time and memory limits form. The whole form is The last unexplored area is the time and memory limits form. The whole form is
situated in box with tabs which are leading to particular runtime environments. situated in a box with tabs which are leading to particular runtime
If you wish not to use one of those, locate "Remove" button at the bottom of the environments. If you wish not to use one of those, locate "Remove" button at the
box tab which will delete this environment from the assignment. Please note that bottom of the box tab which will delete this environment from the assignment.
this action is irreversible. Please note that this action is irreversible.
In general one tab in environments box contains some basic information about In general, every tab in environments box contains some basic information about
runtime environment and another nested tabbed box. In there you can find all runtime environment and another nested tabbed box. In there you can find all
hardware groups which are available for exercise and set limits for all test hardware groups which are available for the exercise and set limits for all test
cases. The time limits have to be filled in seconds (float), memory limits are cases. The 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 in bytes (int). If you are interested in some reference values to particular
test case then you can take a peek on collapsible "Reference solutions' test case then you can take a peek on collapsible "Reference solutions'
evaluations" items. If you are satisfied with changes you made to the limits, evaluations" items. If you are satisfied with changes you made to the limits,
save form with "Change limits" button right under environments box. save the form with "Change limits" button right under environments box.
### Students' solutions management ### Students' solutions management
One of the most important tasks for a group supervisor is checking student One of the most important tasks of a group supervisor is checking student
solutions. As automatic evaluation of them cannot catch all aspects of source solutions. As automatic evaluation of them cannot catch all problems in the
code, it is suitable to do a brief manual review of student's coding style and source code, it is advisable to do a brief manual review of student's coding
reflect that in assignment bonus points. style and reflect that in assignment bonus points.
On "Assignment detail" page there is an "View student results" button near top On "Assignment detail" page there is an "View student results" button near top
of the page (next to "Edit assignment settings" button). This will redirect you of the page (next to "Edit assignment settings" button). This will redirect you
@ -2166,6 +2166,8 @@ updated. To remove assigned bonus points, submit just the zero number. The bonus
points are not additive, newer value overrides older values. points are not additive, newer value overrides older values.
It is useful to give a feedback about the solution back to the user. For this It is useful to give a feedback about the solution back to the user. For this
you can use the "Commens and notes" box. Make sure that the messages are not
private, so that the student can see them. More detailed description of this box
can be nicely used the "Comments and notes" box. Make sure that the messages are can be nicely used the "Comments and notes" box. Make sure that the messages are
not private, so the student can see them. More detailed description of this box not private, so the student can see them. More detailed description of this box
is available in student part of user documentation. is available in student part of user documentation.
@ -2243,7 +2245,7 @@ runtime configurations" button. If you want to delete some particular runtime
just hit "Remove" button in the right tab, please note that after this operation just hit "Remove" button in the right tab, please note that after this operation
runtime configurations form has to be again saved to apply changes. runtime configurations form has to be again saved to apply changes.
All runtime configurations which was added to exercise will be visible to All runtime configurations which were added to exercise will be visible to
supervisors and all can be used in assignment, so please be sure that all of the supervisors and all can be used in assignment, so please be sure that all of the
languages and job configurations are working. languages and job configurations are working.
@ -2259,6 +2261,8 @@ time and memory limits of assignments. Values of used time and memory for each
solution are displayed in yellow boxes under forms for setting assignment limits solution are displayed in yellow boxes under forms for setting assignment limits
as described earlier. as described earlier.
However, there is currently no user interface to upload and evaluate reference
solutions. It is possible to use direct REST API calls, but it is not very user
However, there is currently no user interface to upload and evaluate reference However, there is currently no user interface to upload and evaluate reference
solutions. It is possible to use direct REST API calls, but it is not much user solutions. It is possible to use direct REST API calls, but it is not much user
friendly. If you are interested, please look at [API friendly. If you are interested, please look at [API
@ -2268,8 +2272,8 @@ reference solution files, create a new reference solution and then evaluate the
solution. After that, measured data will be available in the box at assignment solution. After that, measured data will be available in the box at assignment
editing page (setting limits section). editing page (setting limits section).
We are now working on better user interface, which will be available soon. Then We are now working on a better user interface, which will be available soon.
the description will be added here. Then its description will be added here.
## Group administrator ## Group administrator
@ -2398,16 +2402,16 @@ Roles description:
assigned exercises. On top of that supervisor can create/delete groups too, assigned exercises. On top of that supervisor can create/delete groups too,
but only as subgroup of groups he/she belongs to. but only as subgroup of groups he/she belongs to.
- Superadmin -- Inherits all permissions from supervisor role. Most powerful - Superadmin -- Inherits all permissions from supervisor role. Most powerful
user in ReCodEx who should be able to do everything which is provided by user in ReCodEx who should be able to do access any functionality provided by
application. the application.
## Writing score configuration ## Writing score configuration
Important thing about assignment is how to assign points to particular An important thing about assignment is how to assign points to particular
solutions. As mentioned previously whole job is composed of logical tests. All solutions. As mentioned previously, the whole job is composed of logical tests.
of these tests have to contain one essential "evaluation" task. Evaluation task All of these tests have to contain one essential "evaluation" task. Evaluation
should output one float number which can be further used for scoring of task should output one float number which can be further used for scoring of
particular tests. particular tests.
Total resulting score of the students solution is then calculated according to a Total resulting score of the students solution is then calculated according to a
@ -2416,11 +2420,11 @@ score is also a float between 0 and 1. This number is then multiplied by the
maximum of points awarded for the assignment by the teacher assigning the maximum of points awarded for the assignment by the teacher assigning the
exercise -- not the exercise author. exercise -- not the exercise author.
For now there is only one way how to write score configuration using only simple For now, there is only one way how to write score configuration using only
score calculator. But the implementation in API is agile enough to handle simple score calculator. But the implementation in API is agile enough to handle
upcoming score calculators which might use some more complex scoring algorithms. upcoming score calculators which might use some more complex scoring algorithms.
This also means that future calculators do not have to use YAML format as the This also means that future calculators do not have to use the YAML format for
already defined one, but can use its own or different one. configuration. In fact, the configuration can be a string in any format.
### Simple score calculation ### Simple score calculation

Write Preview
Loading…
Cancel
Save