Miguel Barão / perguntations

MANUAL.md 5.62 KB

Perguntations user manual

~ Miguel Barão ~

Quick start

After installing python and the required packages as described in the README.md we can run a demonstration:

$ cd PATH/TO/perguntations
$ ./initdb.py --demo
New database created: students.db
8 user(s) inserted:
    0        - Professor (administrator)
    1815     - Ada Lovelace
    ...        ...
    1969     - Linus Torvalds$ mv students.db demo/
$ mv students.db demo/
$ ./serve.py demo/test.yaml
2016-11-19 15:44:55,401 | INFO     | app            | ============= Running perguntations =============
2016-11-19 15:44:55,427 | INFO     | questions      | Loaded 9 questions from "questions.yaml".
2016-11-19 15:44:55,427 | INFO     | test           | Test factory ready for "demo".
2016-11-19 15:44:55,449 | INFO     | app            | Database has 7 students registered.
2016-11-19 15:44:55,507 | INFO     | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Listening for SIGTERM.
2016-11-19 15:44:55,511 | INFO     | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Listening for SIGHUP.
2016-11-19 15:44:55,511 | INFO     | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Listening for SIGUSR1.
2016-11-19 15:44:55,511 | INFO     | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Bus STARTING
2016-11-19 15:44:55,512 | INFO     | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Started monitor thread '_TimeoutMonitor'.
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
2016-11-19 15:44:55,631 | INFO     | cherrypy.error | [19/Nov/2016:15:44:55] ENGINE Bus STARTED

You can now open a browser and point it to the server address, e.g. http://127.0.0.1:8080.

Enter 0 for the number and choose any password. This will be your password from now on.

After login, you will see an administrator page. This page allows you to:

  • 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.
  • 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.
  • 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.
  • Online students will be highlighted and the table on the top of the page will show some more information (login time, ip address, etc)
  • 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...
  • It is also possible to add new students by clicking the button on the bottom of the page.

Answering a test

Students are redirected to a test as soon as they login.

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.

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.

Creating a new test

A test is specified in a single yaml file. Look at demo/test.yaml for an example and documentation.

Creating questions

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.

The types of questions supported are:

  • radio questions are multiple choice where only one can be selected.
  • checkbox questions are also multiple choice but several can be selected.
  • text and text_regex questions provide a line to write the answer.
  • 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.

Besides these, there are information and alert types which just show text but do not expect answers.

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.

An example file with these types of questions is provided in demo/questions/questions.yaml along with accompanying files under the directory demo/questions.

Testing a new test

Before using a test in production you should test is very carefully. After writing the questions and the test configuration, it is recommended to:

  1. Create a database for debug with ./initdb.py --demo.
  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.
  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.

Reviewing tests

The actual tests are saved as individual JSON files. These files are stored in the location answers_dir specified in the test.yaml configuration file.

To review the tests:

  1. Run the server with the test to review
  2. Login as user 0.
  3. Click on a colored grade bar to open the test

Getting the grades

The grades are stored in the sqlite3 file specified in the test. We can get the results from the command line:

sqlite3 demo/students.db "select student_id,grade from tests where ref='my-test-reference'" > test_grades.csv