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
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
the browser.
Supported and tested browsers are: Firefox 50+, Chrome 55+, Opera 42+ and Edge
13+. Mobile devices often have problems with internalization and possibly lack
support for some common features of desktop browsers. For us in this stage of
development is not possible to fine tune the interface for major mobile browsers
on all mobile platforms. However, it is confirmed to work with latest Google
Chrome and Gello browser on Android 7.1+. There are reported some issues with
Firefox which may be fixed in future. Also, it is confirmed working with Safari
browser on iOS 10.
Usage of the web application is divided into the sections concerning the
particular user roles. Under these sections all possible use cases can be found.
These sections are inclusive, so more privileged users need to know stuff from
all less or equal privileged sections than their level of privilege.
Described roles are:
13+. Mobile devices often have problems with internationalization and possibly
lack support for some common features of desktop browsers. In this stage of
development is not possible for us to fine tune the interface for major mobile
browsers on all mobile platforms. However, it is confirmed to work with latest
Google Chrome and Gello browser on Android 7.1+. Issues have been reported with
Firefox that will be fixed in the future. Also, it is confirmed to work with
Safari browser on iOS 10.
Usage of the web application is divided into sections concerning particular user
roles. Under these sections all possible use cases can be found. These sections
are inclusive, so more privileged users need to read instructions for all less
privileged users. Described roles are:
- Student
- Group supervisor
@ -1837,26 +1836,26 @@ application follows.
### 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
creating a local account with a specific password, or pairing your new account
with an existing CAS UK account.
If you decide a new "*local*" account using the "*Create ReCodEx account*” form,
you will have to provide your details and choose a password for your account.
Although ReCodEx allows using quite weak passwords, it is wise to use a bit
stronger ones. The actual strength is shown in progress bar near the password
field during registration. You will later sign in using your email address as
your username and the password you select.
If you decide to create a new "*local*" account using the "*Create ReCodEx
account*” form, you will have to provide your details and choose a password for
your account. Although ReCodEx allows using quite weak passwords, it is wise to
use a bit stronger ones The actual strength is shown in progress bar near the
password field during registration. You will later sign in using your email
address as your username and the password you select.
If you decide to use the CAS UK, then ReCodEx will verify your CAS credentials
and create a new account based on information stored there (name and email
address). You can change your personal information later on the "*Settings*"
page.
If you decide to use the CAS UK service, then ReCodEx will verify your CAS
credentials and create a new account based on information stored there (name and
email address). You can change your personal information later on the
"*Settings*" page.
When creating the account both ways, an instance the account will belong to must
be selected. The instance will be most likely your university or other
organization you are a member of.
Regardless of the desired account type, an instance it will belong to must be
selected. The instance will be most likely your university or other organization
you are a member of.
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
@ -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
your name in the left sidebar.
If you do not use ReCodEx for a whole day, you will be logged out automatically.
However, we recommend you sign out of the application after you finished your
interaction with it. The logout button is placed in the top section of the left
sidebar right under your name. You may need to expand the sidebar with a button
next to the "*ReCodEx*” title (also known as _hamburger button_).
If you are not active in ReCodEx for a whole day, you will be logged out
automatically. However, we recommend you sign out of the application after you
finish your interaction with it. The logout button is placed in the top section
of the left sidebar right under your name. You may need to expand the sidebar
with a button next to the "*ReCodEx*” title (informally known as _hamburger
button_), depending on your screen size.
### Forgotten password
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
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.
A message with a link containing a special token will be sent to your address.
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
will be able to select a new password for your account. The token is valid only
for a couple of minutes, so do not forget to reset the password as soon as
possible, or you will have to request a new link with a valid token.
click this link, you will be asked to submit your registration email address. A
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.
When you visit the link, you will be able to enter a new password for your
account. The token is valid only for a couple of minutes, so do not forget to
reset the password as soon as possible, or you will have to request a new link
with a valid token.
If you sign in through CAS UK, then please follow the instructions
provided by the administrators of the service described on their
@ -1902,16 +1902,16 @@ website.
### Dashboard
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
about the groups you are member of. Further description of dashboard will be
provided later on with according roles.
this page you can see some brief information about the groups you are member of.
The information presented there varies with your role in the system -- further
description of dashboard will be provided later on with according roles.
## Student
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
solutions of exercises in some particular groups. These groups should correspond
to courses he/she attend at college.
limited capabilites in ReCodEx. Generally, a student can only submit solutions
of exercises in some particular groups. These groups should correspond to
courses he/she attends.
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
@ -1924,17 +1924,16 @@ provided "Show group's detail" button.
### Join group and start solving assignments
To be able to submit solutions you have to be member of the right group. Each
instance have own group hierarchy, so you can choose only those from your
instance. That is why list of groups is available from instance link located in
sidebar. This link brings you to instance detail page.
To be able to submit solutions you have to be a member of the right group. Each
instance has its own group hierarchy, so you can choose only those within your
instance. That is why a list of groups is available from under an instance link
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
"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
further extended. If you successfully located group you would like to join,
continue by clicking on "See group's page" link following with "Join group"
link.
further extended. When you find a group you would like to join, continue by
clicking on "See group's page" link following with "Join group" link.
**Note:** Some groups can be marked as private and these groups are not visible
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
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
list of fellow students. If supervisors of groups allowed students to see each
others statistics there will also be points which particular students gained.
a list of fellow students. If supervisors of groups allowed students to see each
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
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
of successful solution. Second deadline does not have to be set, but in case of
presence the maximum number of points for successful solution between these two
of successful solution. Second deadline does not have to be set, but in case it
is, the maximum number of points for successful solution between these two
deadlines can be different.
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
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
uploaded all files necessary for your solution, click on "Submit your solution"
button and let ReCodEx do its thing.
solution. Your supervisor can also access this note. After you successfully
upload all files necessary for your solution, click the "Submit your solution"
button and let ReCodEx evaluate the solution.
During the execution ReCodEx backend might send evaluation progress state to
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
look at the results of your solution.
On the results detail page there are a lot of information. Apart assignment
description which is not connected to your results there is also the solution
submitter name (supervisor can submit solution on your behalf), further there
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
submitter name (supervisor can submit a solution on your behalf), further there
are files which were uploaded on submission and most importantly "Evaluation
details" and "Test results" boxes.
Evaluation details contains overall results of your solution. There are
information such as if solution was provided before deadlines, if the evaluation
process successfully finished or if compilation succeeded. After that you can
find a lot of values, most important one is the last, "Total score", consisting
of your score, slash and the maximum number of points for this assignment.
Interestingly the your score value can be higher than the maximum, which is
caused by "Bonus points" item above. If your solution is nice and
information such as whether the solution was provided before deadlines, if the
evaluation process successfully finished or if compilation succeeded. After that
you can find a lot of values, most important one is the last, "Total score",
consisting of your score, slash and the maximum number of points for this
assignment. Interestingly the your score value can be higher than the maximum,
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
the other hand, points can be also subtracted for bad coding habits or even
cheating.
@ -2019,10 +2018,10 @@ mechanism for new comment messages.
## Group supervisor
Group supervisor is ordinarily the lecturer of the corresponding course. With
this role user can modify group description and properties, assign exercises or
manage list of students. Further permissions like managing subgroups or
supervisors is available only for group administrators.
Group supervisor is typically the lecturer of a course. A user in this role can
modify group description and properties, assign exercises or manage list of
students. Further permissions like managing subgroups or supervisors is
available only for group administrators.
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
@ -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:
- 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
Markdown)
- 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
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
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
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
@ -2066,8 +2066,8 @@ signed in to your group.
### Assigning exercises
Before assigning exercise you obviously have to know what exercises are
available. List of all exercises in the system can be found under "Exercises"
Before assigning an exercise, you obviously have to know what exercises are
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
and names of the exercise authors. Further information about exercise is
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
"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
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.
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:
- name of the assignment which will be visible in a group
- visibility, if assignment is under construction then you can mark it as not
visible and students will not see it
- visibility (if an 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
on "Add language variant" button, current one can be deleted with "Remove this
language" button)
- language of description from dropdown field (English, Czech, German)
- 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
configuration can be found further in "Writing score configuration" chapter
- first submission deadline
- maximum gainable points before first deadline; if you want to manage all
points manually, set here 0 and then use concept of bonus points, which is
- maximum points that can be gained before the first deadline; if you want to
manage all points manually, set it to 0 and then use bonus points, which are
described in the next subchapter
- second submission deadline, after that students still can submit exercises but
no points for them (must be after the first deadline)
- maximum gainable points after first deadline and before second deadline
- submission count limit for students' solutions, after this amount students
cannot submit solutions any more
- visibility of memory and time ratios; if true students can see percentage of
used memory and time for each test
- minimum percentage of points which each submission have to gain otherwise it
will gain no points
- assignment is marked as bonus one and points from solving it are not included
into group threshold limit (that means solving it can get you additional
points over the limit)
they are given no points no points (must be after the first deadline)
- maximum points that can be gained between first deadline and second deadline
- submission count limit for students' solutions -- limits the amount of
attempts a student has at solving the problem
- visibility of memory and time ratios; if true students can see the percentage
of used memory and time (with respect to the limit) for each test
- minimum percentage of points which each submission must gain to be considered
correct (if it gets less, it will gain no points)
- whether the assignment is marked as bonus one and points from solving it are
not included into group threshold limit (that means solving it can get you
additional points over the limit)
The form has to be submitted with "Edit settings" button otherwise changes will
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
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 not to use one of those, locate "Remove" button at the bottom of the
box tab which will delete this environment from the assignment. Please note that
this action is irreversible.
The last unexplored area is the time and memory limits form. The whole form is
situated in a box with tabs which are leading to particular runtime
environments. If you wish not to use one of those, locate "Remove" button at the
bottom of the box tab which will delete this environment from the assignment.
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
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
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'
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
One of the most important tasks for a group supervisor is checking student
solutions. As automatic evaluation of them cannot catch all aspects of source
code, it is suitable to do a brief manual review of student's coding style and
reflect that in assignment bonus points.
One of the most important tasks of a group supervisor is checking student
solutions. As automatic evaluation of them cannot catch all problems in the
source code, it is advisable to do a brief manual review of student's coding
style and reflect that in assignment bonus points.
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
@ -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.
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
not private, so the student can see them. More detailed description of this box
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
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
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
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
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
@ -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
editing page (setting limits section).
We are now working on better user interface, which will be available soon. Then
the description will be added here.
We are now working on a better user interface, which will be available soon.
Then its description will be added here.
## Group administrator
@ -2398,16 +2402,16 @@ Roles description:
assigned exercises. On top of that supervisor can create/delete groups too,
but only as subgroup of groups he/she belongs to.
- Superadmin -- Inherits all permissions from supervisor role. Most powerful
user in ReCodEx who should be able to do everything which is provided by
application.
user in ReCodEx who should be able to do access any functionality provided by
the application.
## Writing score configuration
Important thing about assignment is how to assign points to particular
solutions. As mentioned previously whole job is composed of logical tests. All
of these tests have to contain one essential "evaluation" task. Evaluation task
should output one float number which can be further used for scoring of
An important thing about assignment is how to assign points to particular
solutions. As mentioned previously, the whole job is composed of logical tests.
All of these tests have to contain one essential "evaluation" task. Evaluation
task should output one float number which can be further used for scoring of
particular tests.
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
exercise -- not the exercise author.
For now there is only one way how to write score configuration using only simple
score calculator. But the implementation in API is agile enough to handle
For now, there is only one way how to write score configuration using only
simple score calculator. But the implementation in API is agile enough to handle
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
already defined one, but can use its own or different one.
This also means that future calculators do not have to use the YAML format for
configuration. In fact, the configuration can be a string in any format.
### Simple score calculation

Write Preview
Loading…
Cancel
Save