Commit bae2d15eb24b99678532714eba0319452fc63c6c
1 parent
77ef8d7a
Exists in
master
and in
1 other branch
- updated MANUAL.md
Showing
1 changed file
with
46 additions
and
35 deletions
Show diff stats
MANUAL.md
| ... | ... | @@ -17,70 +17,80 @@ New database created: students.db |
| 17 | 17 | ... ... |
| 18 | 18 | 1969 - Linus Torvalds$ mv students.db demo/ |
| 19 | 19 | $ mv students.db demo/ |
| 20 | +$ mkdir demo/ans | |
| 20 | 21 | $ ./serve.py demo/test.yaml |
| 21 | -2016-11-19 15:44:55,401 | INFO | app | ============= Running perguntations ============= | |
| 22 | -2016-11-19 15:44:55,427 | INFO | questions | Loaded 9 questions from "questions.yaml". | |
| 23 | -2016-11-19 15:44:55,427 | INFO | test | Test factory ready for "demo". | |
| 24 | -2016-11-19 15:44:55,449 | INFO | app | Database has 7 students registered. | |
| 25 | -2016-11-19 15:44:55,507 | INFO | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Listening for SIGTERM. | |
| 26 | -2016-11-19 15:44:55,511 | INFO | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Listening for SIGHUP. | |
| 27 | -2016-11-19 15:44:55,511 | INFO | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Listening for SIGUSR1. | |
| 28 | -2016-11-19 15:44:55,511 | INFO | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Bus STARTING | |
| 29 | -2016-11-19 15:44:55,512 | INFO | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Started monitor thread '_TimeoutMonitor'. | |
| 30 | -2016-11-19 15:44:55,631 | INFO | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Serving on http://0.0.0.0:8080 | |
| 31 | -2016-11-19 15:44:55,631 | INFO | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Bus STARTED | |
| 22 | +2017-11-02 10:39:29,683 | INFO | root | =============================================== | |
| 23 | +2017-11-02 10:39:29,683 | INFO | app | Starting application | |
| 24 | +2017-11-02 10:39:29,684 | INFO | app | Loading test configuration "demo/test-tutorial.yaml". | |
| 25 | +2017-11-02 10:39:29,786 | INFO | questions | Loaded 10 questions from "questions-tutorial.yaml". | |
| 26 | +2017-11-02 10:39:29,787 | INFO | test | Checking question "tut-information". | |
| 27 | +2017-11-02 10:39:29,787 | INFO | test | Checking question "tut-success". | |
| 28 | +2017-11-02 10:39:29,787 | INFO | test | Checking question "tut-warning". | |
| 29 | +2017-11-02 10:39:29,788 | INFO | test | Checking question "tut-alert". | |
| 30 | +2017-11-02 10:39:29,788 | INFO | test | Checking question "tut-radio". | |
| 31 | +2017-11-02 10:39:29,788 | INFO | test | Checking question "tut-checkbox". | |
| 32 | +2017-11-02 10:39:29,789 | INFO | test | Checking question "tut-text". | |
| 33 | +2017-11-02 10:39:29,789 | INFO | test | Checking question "tut-text-regex". | |
| 34 | +2017-11-02 10:39:29,789 | INFO | test | Checking question "tut-numeric-interval". | |
| 35 | +2017-11-02 10:39:29,790 | INFO | test | Checking question "tut-textarea". | |
| 36 | +2017-11-02 10:39:29,790 | INFO | test | Test factory ready for "tutorial". | |
| 37 | +2017-11-02 10:39:29,880 | INFO | app | Database has 34 students registered. | |
| 38 | +2017-11-02 10:39:29,891 | INFO | root | Webserver running... | |
| 32 | 39 | ``` |
| 33 | 40 | |
| 34 | -You can now open a browser and point it to the server address, e.g. `http://127.0.0.1:8080`. | |
| 41 | +You can now open a browser and point it to the server address, e.g. `http://127.0.0.1:8443`. | |
| 35 | 42 | |
| 36 | 43 | Enter `0` for the number and choose any password. This will be your password from now on. |
| 37 | 44 | |
| 38 | 45 | After login, you will see an administrator page. This page allows you to: |
| 39 | 46 | |
| 40 | -- Allow students to login to the test. This can be done one at a time, using the checkboxes on the left of each student, or allow all students by clicking the button in the bottom of the page. | |
| 41 | -- Review a test done by a student by clicking the grade colorbar on the right. If a student has multiple tests, then several bars will be shown. A tooltip shows the date/time for each test. | |
| 42 | -- Reset student passwords. Students that already have a password will have a label `PW` next to the student name. To reset the password, go to the bottom of the page and insert the student number in the box and press the button to reset the password. The label `PW` will disappear. | |
| 43 | -- Online students will be highlighted and the table on the top of the page will show some more information (login time, ip address, etc) | |
| 44 | -- If a student moves unfocus the browser window on his computer (e.g. for cheating), a red bar appears along with the status `unfocus`. Screen saver is also reported as unfocus, so some care should be taken... | |
| 45 | -- It is also possible to add new students by clicking the button on the bottom of the page. | |
| 47 | +- **Allow students** to login to the test. This can be done one at a time, using the checkboxes on the left of each student, or allow all students by clicking the menubar. | |
| 48 | +- **Review a test** done by a student by clicking the grade colorbar on the right. If a student has multiple tests, then several bars will be shown. A tooltip shows the date/time for each test. | |
| 49 | +- **Reset passwords**. Students that already have a password will have a key icon next to the student name. To reset the password, go to the menubar `alunos`. The key icon will disappear. | |
| 50 | +- Online students will have a label with the staring time next to the name. | |
| 51 | +~~- If a student moves unfocus the browser window on his computer (e.g. for cheating), a red bar appears along with the status `unfocus`. Screen saver is also reported as unfocus, so some care should be taken...~~ | |
| 52 | +- **Add new students** on the menu `alunos`. | |
| 53 | + | |
| 46 | 54 | |
| 47 | 55 | ## Answering a test |
| 48 | 56 | |
| 49 | -Students are redirected to a test as soon as they login. | |
| 57 | +Students are redirected to a test as soon as they login. The test is a single page showing all questions. | |
| 50 | 58 | |
| 51 | -Just answer the questions. If the answer is unknown, the question should be disabled on the top right corner. This avoids penalties in some questions. | |
| 59 | +If an answer to a question is unknown, the question can be disabled on the top right corner to avoid penalties. | |
| 52 | 60 | |
| 53 | -After answering all the questions, the test is submited by clicking the button on the bottom of the page. A new page is shown with the grade obtained. | |
| 61 | +After answering all the questions, the test is submited by clicking the green button on the bottom of the page. A new page is shown with the grade obtained. At this point the test is terminated and the student has already been logged out. | |
| 54 | 62 | |
| 55 | 63 | ## Creating a new test |
| 56 | 64 | |
| 57 | -A test is specified in a single yaml file. Look at `demo/test.yaml` for an example and documentation. | |
| 65 | +A test is specified in a single `yaml` file. Look at `demo/test.yaml` for an example and documentation. | |
| 58 | 66 | |
| 59 | 67 | ## Creating questions |
| 60 | 68 | |
| 61 | -Questions are defined in yaml files. Each yaml file contains a list of questions from which some can be chosen to be part of a test. | |
| 69 | +Questions are defined in `yaml` files. Each `yaml` file contains a list of questions that can be selected to make up a test. | |
| 62 | 70 | |
| 63 | 71 | The types of questions supported are: |
| 64 | 72 | |
| 65 | -- `radio` questions are multiple choice where only one can be selected. | |
| 66 | -- `checkbox` questions are also multiple choice but several can be selected. | |
| 67 | -- `text` and `text_regex` questions provide a line to write the answer. | |
| 68 | -- `textarea` provide a multiline text box to write the answer (e.g. for computer code). The answer is corrected by calling an external program that is not part of the server and is up to you to right it. | |
| 73 | +- `radio` are single choice questions. | |
| 74 | +- `checkbox` are multiple choice where multiple options can be selected. | |
| 75 | +- `text` answers have one line of text, which is checked against a list of possible accepted answers. | |
| 76 | +- `text-regex` is similar to `text` but answers are checked by a regular expression. | |
| 77 | +- `numeric-interval` provides a line of text where a number can be written. Numbers are converted to a float and checked if they belong to an interval. | |
| 78 | +- `textarea` provide a multiline text box to write the answer (e.g. for computer code). The answer is corrected by calling an external program that is not part of the server and is up to you to develop. | |
| 69 | 79 | |
| 70 | -Besides these, there are `information` and `alert` types which just show text but do not expect answers. | |
| 80 | +Besides these, there are `information`, `warning` and `alert` types which just show text and do not expect answers. | |
| 71 | 81 | |
| 72 | -All the types above are predifined questions. It is also possible to generate questions on the fly. These are defined with type `generator` and an external program must be provided to generate a question of the types above. | |
| 82 | +All the types above are predifined questions. It is also possible to generate questions of any type. These are defined with type `generator` and an external program must be provided to generate a question of the types above. | |
| 73 | 83 | |
| 74 | 84 | An example file with these types of questions is provided in `demo/questions/questions.yaml` along with accompanying files under the directory `demo/questions`. |
| 75 | 85 | |
| 76 | 86 | |
| 77 | -## Testing a new test | |
| 87 | +## Validating a new test | |
| 78 | 88 | |
| 79 | -Before using a test in production you should test is very carefully. After writing the questions and the test configuration, it is recommended to: | |
| 89 | +Tests should be validated carefully before running a test in production one should test it very carefully. After writing the questions and the test configuration, it's recommended to: | |
| 80 | 90 | |
| 81 | 91 | 1. Create a database for debug with `./initdb.py --demo`. |
| 82 | 92 | 2. Run the server with `./serve.py --allow-all new_test.yaml` where the `--allow-all` option avoids having to use a second browser for the admin page to explicitly allow a student. |
| 83 | -3. If bugs are found, try commenting questions in the `new_test.yaml` to isolate the bug. Use the `--debug` option to see more information in the webpage. | |
| 93 | +3. If bugs are found, try commenting questions in the `new_test.yaml` to isolate the bug. Use the `--debug` option to see more information on what is happening. | |
| 84 | 94 | |
| 85 | 95 | |
| 86 | 96 | ## Reviewing tests |
| ... | ... | @@ -97,8 +107,9 @@ To review the tests: |
| 97 | 107 | ## Getting the grades |
| 98 | 108 | |
| 99 | 109 | The grades are stored in the sqlite3 file specified in the test. |
| 100 | -We can get the results from the command line: | |
| 110 | +We can get the results into a csv file and later import it into LibreOffice: | |
| 101 | 111 | |
| 102 | 112 | ```.bash |
| 103 | - $ sqlite3 demo/students.db "select student_id,grade from tests where ref='my-test-reference'" > test_grades.csv | |
| 104 | -``` | |
| 105 | 113 | \ No newline at end of file |
| 114 | + $ sqlite3 demo/students.db "select student_id,grade from tests where ref='my-test-reference'" > grades.csv | |
| 115 | +``` | |
| 116 | + | ... | ... |