- minor documentation update.

Miguel Barão
1 parent 92d262e8
Showing 4 changed files with 64 additions and 37 deletions Show diff stats
BUGS.md
MANUAL.md
README.md
initdb.py
@@ -2,10 +2,13 @@
 # BUGS
  
 - servidor nao esta a lidar com eventos scroll/resize. ignorar?
-- testar SSL
  
 # TODO
  
+- configurar pf em freebsd, port forward 80 -> 8080. documentacao
+- testar SSL
+- manter registo dos unfocus durante o teste e de qual a pergunta visivel nesse momento
+
 - permitir varios testes, aluno escolhe qual o teste que quer fazer.
 - usar thread.Lock para aceder a variaveis de estado?
 - se ocorrer um erro na correcçao avisar aluno para contactar o professor.
 # Perguntations user manual
  
+~ [Miguel Barão](mjsb@uevora.pt) ~
+
+
 ## Quick start
  
-After installing python and the required packages as described in the `README.md` you can run a demonstration:
+After installing python and the required packages as described in the `README.md` we can run a demonstration:
  
-```
+```.bash
 $ cd PATH/TO/perguntations
 $ ./initdb.py --demo
 New database created: students.db
-10 users inserted:
+8 user(s) inserted:
     0        - Professor (administrator)
-    1465     - Gil Vicente
-    ...      - ...
-    1924     - Alexandre O'Neill
+    1815     - Ada Lovelace
+    ...        ...
+    1969     - Linus Torvalds$ mv students.db demo/
 $ mv students.db demo/
 $ ./serve.py demo/test.yaml
-2016-07-13 15:19:21,718 | INFO     | app            | ============= Running perguntations =============
-2016-07-13 15:19:21,740 | INFO     | questions      | Loaded 9 questions from "questions.yaml".
-2016-07-13 15:19:21,740 | INFO     | test           | Test factory ready for "demo".
-2016-07-13 15:19:21,756 | INFO     | app            | Database has 9 students registered.
-...
-2016-07-13 15:19:21,919 | INFO     | cherrypy.error | [13/Jul/2016:15:19:21] ENGINE Serving on http://0.0.0.0:8080
-2016-07-13 15:19:21,919 | INFO     | cherrypy.error | [13/Jul/2016:15:19:21] ENGINE Bus STARTED
+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`.
@@ -30,7 +37,7 @@ Enter `0` for the number and choose any password. This will be your password fro
  
 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.
+- 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)
@@ -62,14 +69,34 @@ The types of questions supported are:
  
 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 by code. These are defined as type `generator` and an external program must be provided to generate a question of the types above.
+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 product you should test is very carefully. After writing the questions and the test configuration, my recommendation is to:
+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:
  
-1. `./serve.py --allow-all shiny_new_test.yaml` where the `--allow-all` option avoids having to use a second browser for the admin page to explicitly allow a student.
-2. If bugs are found, try commenting questions in the `shiny_new_test.yaml` to isolate the bug. Use the `--debug` option to add more information in the webpage.
+    sqlite3 demo/students.db "select student_id,grade from tests where ref='my-test-reference'" > test_grades.csv
@@ -100,14 +100,14 @@ iptables -t nat -I PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-ports 8
  
 Explanation:
  
-    - `-t nat` is the table consulted when a packet creates a new connection.
-    - `-I PREROUTING` inserts rules at the head of the chain.
-    - `-p tcp` selected protocol.
-    - `-s 0/0` source network address/mask.
-    - `-i eth0` interface via which the packet was received.
-    - `--dport 80` destination port.
-    - `-j REDIRECT` what to do when packet matches the rule.
-    - `--to-ports 8080` where to redirect the packets.
+- `-t nat` is the table consulted when a packet creates a new connection.
+- `-I PREROUTING` inserts rules at the head of the chain.
+- `-p tcp` selected protocol.
+- `-s 0/0` source network address/mask.
+- `-i eth0` interface via which the packet was received.
+- `--dport 80` destination port.
+- `-j REDIRECT` what to do when packet matches the rule.
+- `--to-ports 8080` where to redirect the packets.
  
 ### freebsd
  
@@ -53,15 +53,13 @@ try:
     elif args.demo:
         # add a few fake students
         fakes = [
-            ['1888', 'Fernando Pessoa'],
-            ['1799', 'Almeida Garrett'],
-            ['1845', 'José Maria Eça de Queirós'],
-            ['1465', 'Gil Vicente'],
-            ['1825', 'Camilo Castelo Branco'],
-            ['1842', 'Antero de Quental'],
-            ['1907', 'Miguel Torga'],
-            ['1810', 'Alexandre Herculano'],
-            ['1924', 'Alexandre O\'Neill'],
+            ['1915', 'Alan Turing'],
+            ['1938', 'Donald Knuth'],
+            ['1815', 'Ada Lovelace'],
+            ['1969', 'Linus Torvalds'],
+            ['1955', 'Tim Burners-Lee'],
+            ['1916', 'Claude Shannon'],
+            ['1903', 'John von Neumann'],
         ]
         session.add_all([Student(id=i, name=name, password='') for i,name in fakes])
  
@@ -82,7 +80,6 @@ else:
         print('    {0:8} - {1}'.format(users[1].id, users[1].name))
     if n > 3:
         print('    ...        ...')
-        # print('    .\n    .\n    .')
     if n > 2:
         print('    {0:8} - {1}'.format(users[-1].id, users[-1].name))
...	...	@@ -2,10 +2,13 @@
2	2	# BUGS
3	3
4	4	- servidor nao esta a lidar com eventos scroll/resize. ignorar?
5		-- testar SSL
6	5
7	6	# TODO
8	7
	8	+- configurar pf em freebsd, port forward 80 -> 8080. documentacao
	9	+- testar SSL
	10	+- manter registo dos unfocus durante o teste e de qual a pergunta visivel nesse momento
	11	+
9	12	- permitir varios testes, aluno escolhe qual o teste que quer fazer.
10	13	- usar thread.Lock para aceder a variaveis de estado?
11	14	- se ocorrer um erro na correcçao avisar aluno para contactar o professor.
...	...
1	1	# Perguntations user manual
2	2
	3	+~ [Miguel Barão](mjsb@uevora.pt) ~
	4	+
	5	+
3	6	## Quick start
4	7
5		-After installing python and the required packages as described in the `README.md` you can run a demonstration:
	8	+After installing python and the required packages as described in the `README.md` we can run a demonstration:
6	9
7		-```
	10	+```.bash
8	11	$ cd PATH/TO/perguntations
9	12	$ ./initdb.py --demo
10	13	New database created: students.db
11		-10 users inserted:
	14	+8 user(s) inserted:
12	15	0 - Professor (administrator)
13		- 1465 - Gil Vicente
14		- ... - ...
15		- 1924 - Alexandre O'Neill
	16	+ 1815 - Ada Lovelace
	17	+ ... ...
	18	+ 1969 - Linus Torvalds$ mv students.db demo/
16	19	$ mv students.db demo/
17	20	$ ./serve.py demo/test.yaml
18		-2016-07-13 15:19:21,718 \| INFO \| app \| ============= Running perguntations =============
19		-2016-07-13 15:19:21,740 \| INFO \| questions \| Loaded 9 questions from "questions.yaml".
20		-2016-07-13 15:19:21,740 \| INFO \| test \| Test factory ready for "demo".
21		-2016-07-13 15:19:21,756 \| INFO \| app \| Database has 9 students registered.
22		-...
23		-2016-07-13 15:19:21,919 \| INFO \| cherrypy.error \| [13/Jul/2016:15:19:21] ENGINE Serving on http://0.0.0.0:8080
24		-2016-07-13 15:19:21,919 \| INFO \| cherrypy.error \| [13/Jul/2016:15:19:21] ENGINE Bus STARTED
	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
25	32	```
26	33
27	34	You can now open a browser and point it to the server address, e.g. `http://127.0.0.1:8080`.
...	...	@@ -30,7 +37,7 @@ Enter `0` for the number and choose any password. This will be your password fro
30	37
31	38	After login, you will see an administrator page. This page allows you to:
32	39
33		-- 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.
	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.
34	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.
35	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.
36	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)
...	...	@@ -62,14 +69,34 @@ The types of questions supported are:
62	69
63	70	Besides these, there are `information` and `alert` types which just show text but do not expect answers.
64	71
65		-All the types above are predifined questions. It is also possible to generate questions by code. These are defined as type `generator` and an external program must be provided to generate a question of the types above.
	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.
66	73
67	74	An example file with these types of questions is provided in `demo/questions/questions.yaml` along with accompanying files under the directory `demo/questions`.
68	75
69	76
70	77	## Testing a new test
71	78
72		-Before using a test in product you should test is very carefully. After writing the questions and the test configuration, my recommendation is to:
	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:
	80	+
	81	+1. Create a database for debug with `./initdb.py --demo`.
	82	+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.
	84	+
	85	+
	86	+## Reviewing tests
	87	+
	88	+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.
	89	+
	90	+To review the tests:
	91	+
	92	+1. Run the server with the test to review
	93	+2. Login as user `0`.
	94	+3. Click on a colored grade bar to open the test
	95	+
	96	+
	97	+## Getting the grades
	98	+
	99	+The grades are stored in the sqlite3 file specified in the test.
	100	+We can get the results from the command line:
73	101
74		-1. `./serve.py --allow-all shiny_new_test.yaml` where the `--allow-all` option avoids having to use a second browser for the admin page to explicitly allow a student.
75		-2. If bugs are found, try commenting questions in the `shiny_new_test.yaml` to isolate the bug. Use the `--debug` option to add more information in the webpage.
	102	+ sqlite3 demo/students.db "select student_id,grade from tests where ref='my-test-reference'" > test_grades.csv
...	...
...	...	@@ -100,14 +100,14 @@ iptables -t nat -I PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-ports 8
100	100
101	101	Explanation:
102	102
103		- - `-t nat` is the table consulted when a packet creates a new connection.
104		- - `-I PREROUTING` inserts rules at the head of the chain.
105		- - `-p tcp` selected protocol.
106		- - `-s 0/0` source network address/mask.
107		- - `-i eth0` interface via which the packet was received.
108		- - `--dport 80` destination port.
109		- - `-j REDIRECT` what to do when packet matches the rule.
110		- - `--to-ports 8080` where to redirect the packets.
	103	+- `-t nat` is the table consulted when a packet creates a new connection.
	104	+- `-I PREROUTING` inserts rules at the head of the chain.
	105	+- `-p tcp` selected protocol.
	106	+- `-s 0/0` source network address/mask.
	107	+- `-i eth0` interface via which the packet was received.
	108	+- `--dport 80` destination port.
	109	+- `-j REDIRECT` what to do when packet matches the rule.
	110	+- `--to-ports 8080` where to redirect the packets.
111	111
112	112	### freebsd
113	113
...	...
...	...	@@ -53,15 +53,13 @@ try:
53	53	elif args.demo:
54	54	# add a few fake students
55	55	fakes = [
56		- ['1888', 'Fernando Pessoa'],
57		- ['1799', 'Almeida Garrett'],
58		- ['1845', 'José Maria Eça de Queirós'],
59		- ['1465', 'Gil Vicente'],
60		- ['1825', 'Camilo Castelo Branco'],
61		- ['1842', 'Antero de Quental'],
62		- ['1907', 'Miguel Torga'],
63		- ['1810', 'Alexandre Herculano'],
64		- ['1924', 'Alexandre O\'Neill'],
	56	+ ['1915', 'Alan Turing'],
	57	+ ['1938', 'Donald Knuth'],
	58	+ ['1815', 'Ada Lovelace'],
	59	+ ['1969', 'Linus Torvalds'],
	60	+ ['1955', 'Tim Burners-Lee'],
	61	+ ['1916', 'Claude Shannon'],
	62	+ ['1903', 'John von Neumann'],
65	63	]
66	64	session.add_all([Student(id=i, name=name, password='') for i,name in fakes])
67	65
...	...	@@ -82,7 +80,6 @@ else:
82	80	print(' {0:8} - {1}'.format(users[1].id, users[1].name))
83	81	if n > 3:
84	82	print(' ... ...')
85		- # print(' .\n .\n .')
86	83	if n > 2:
87	84	print(' {0:8} - {1}'.format(users[-1].id, users[-1].name))
88	85
...	...