- messages from initdb.py in english

- documentation improvements

- messages from initdb.py in english
- documentation improvements
Miguel Barao
1 parent 9f66ec18
Showing 4 changed files with 114 additions and 34 deletions Show diff stats
MANUAL.md
demo/questions/questions.yaml
demo/test.yaml
initdb.py
-# Perguntations
+# Perguntations user manual
  
-### Requirements and instalation
+## Quick start
  
-Install python 3.4 and the following packages from pip:
+After installing python and the required packages as described in the `README.md` you can run a demonstration:
+
+```
+$ cd PATH/TO/perguntations
+$ ./initdb.py
+New database created: students.db
+10 users inserted:
+    0        - Professor (administrator)
+    1465     - Gil Vicente
+    .
+    .
+    .
+    1924     - Alexandre O'Neill
+$ 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
+```
+
+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 any password. This will be your password from now on.
+
+After login, you will see an administrator page. This page allows you to:
+
+- Generate a sample test just for you to see if it looks right.
+- 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 marked and the table on the top of the page will show some more information (login time, ip address, etc)
+- If a student moves away from the browser (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 just a yaml file with the configuration for that test. Look at `demo/test.yaml` for an example.
+
+## Creating questions
+
+Questions are defined in yaml files. Each yaml file contains a list of questions
  
-- CherryPy (3.7.0)
-- Mako (1.0.1)
-- Markdown (2.6.2)
-- PyYAML (3.11)
-- bcrypt (2.0.0)
  
 Before using the program you need to
  
@@ -28,13 +28,14 @@
         solar_system_planets: images/planets.png
     text: Qual é o maior planeta do Sistema Solar? <img src="solar_system_planets" width="100%"/>
     options:
-        - Júpiter
         - Mercúrio
         - Marte
+        - Júpiter
+        - Têm todos o mesmo tamanho
     # opcional
-    correct: 0
     title: Sistema solar
-    shuffle: True
+    correct: 2
+    shuffle: False
     discount: True
     hint: Se usar o markdown `!(text)[imagem]` a imagem fica com tamanho fixo. É preferível usar a tag html `<img with="100%" src="...">` para ter sempre a largura correcta.
 # ---------------------------------------------------------------------------
 #=============================================================================
+# The test reference should be a unique identifier. It is saved in the database
+# so that queries for the results can be done in the terminal with
+#   $ sqlite3 students.db "select * from tests where ref='demo'"
 ref: demo
+
+# (optional, default: '') You may wish to refer the course, year or kind of test
 title: Exame de Demonstração
  
 # Database with student credentials and grades of all questions and tests done
-# The database is an sqlite3 file generate with the script initdb_from_csv.py
+# The database is an sqlite3 file generate with the script initdb.py
 database: demo/students.db
  
 # (optional) Generate a file for each test done by a student.
 # It includes the questions, answers and grades.
-# If undefined, then no tests are saved (useful for debug and training)
+# If undefined, then no tests are saved (useful for debug and training).
 save_answers: yes
 answers_dir: demo/ans
  
-# Show points for each question, scale 0-20 (default: False)
+# (optional, default: False) Show points for each question, scale 0-20.
 show_points: True
  
-# Show question's hint if available (default: False)
+# (optional, default: False) Show hints if available
 show_hints: True
  
-# Show lots of information for debugging (default: False)
+# (optional, default: False) Show lots of information for debugging
 # debug: True
  
 #-----------------------------------------------------------------------------
 # Base path applied to the questions files and all the scripts
 # including question generators and correctors.
-# Either absolute path or relative to current directory.
+# Either absolute path or relative to current directory can be used.
 questions_dir: demo/questions
  
 # (optional) List of files containing questions in yaml format.
 # Selected questions will be obtained from these files.
-# If undefined, all files in questions_dir are loaded.
+# If undefined, all yaml files in questions_dir are loaded (not recommended).
 files:
     - questions.yaml
  
-# This is the list of questions. If a "ref:" has a list of keys, then
-# one question is selected from the list.
-# The following example will generate a test with 3 questions.
+# This is the list of questions that will make up the test.
+# The order is preserved.
+# There are several ways to define each question (explained below).
 questions:
-    - instructions
+    # show question where ref=instructions
+    - ref: instructions
+
+    # show question where ref=flags and assigns 0.5 points (unnormalized)
     - ref: flags
       points: 0.5
+
+    # idem
     - ref: math-expressions
       points: 2.0
+
+    # show question where ref=solar-system and assign the default of 1.0 point (unnormalized)
     - ref: solar-system
-      # points: 1.0 is the default, if omitted
-    - ref:   # choose one of the following list of questions
+
+    # select one questions from the list [our_planet1, our_planet2]
+    # and assign 0.75 points (unnormalized)
+    - ref:
         - our_planet1
         - our_planet2
       points: 0.75
-    - basic-colors    # same as `ref: basic-colors`
+
+    # the key 'ref:' can be  omitted, a default of 1.0 points is assigned
+    - basic-colors
+
     - question-whatever
+
     - markdown_instructions
@@ -49,23 +49,37 @@ try:
             session.add_all([Student(id=r['N.º'], name=fix(r['Nome']), password='') for r in csvreader])
     else:
         # otherwise add 5 fake students
-        session.add_all([
-            Student(id='student1', name='Student1', password=''),
-            Student(id='student2', name='Student2', password=''),
-            Student(id='student3', name='Student3', password=''),
-            Student(id='student4', name='Student4', password=''),
-            Student(id='student5', name='Student5', password=''),
-            ])
+        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'],
+        ]
+        session.add_all([Student(id=i, name=name, password='') for i,name in fakes])
  
     session.commit()
  
 except Exception:
     session.rollback()
-    print('Erro: Dados já existentes na base de dados?')
+    print('Error: Database already exists.')
     sys.exit(1)
  
 else:
     n = session.query(Student).count()
-    print('Base de dados inicializada com {} utilizadores.'.format(n))
+    print('New database created: {0}\n{1} users inserted:'.format(args.db, n))
+
+    users = session.query(Student).order_by(Student.id).all()
+    print('    {0:8} - {1} (administrator)'.format(users[0].id, users[0].name))
+    if n > 1:
+        print('    {0:8} - {1}'.format(users[1].id, users[1].name))
+    if n > 3:
+        print('    .\n    .\n    .')
+    if n > 2:
+        print('    {0:8} - {1}'.format(users[-1].id, users[-1].name))
  
 # --- end session ---
1		-# Perguntations
	1	+# Perguntations user manual
2	2
3		-### Requirements and instalation
	3	+## Quick start
4	4
5		-Install python 3.4 and the following packages from pip:
	5	+After installing python and the required packages as described in the `README.md` you can run a demonstration:
	6	+
	7	+```
	8	+$ cd PATH/TO/perguntations
	9	+$ ./initdb.py
	10	+New database created: students.db
	11	+10 users inserted:
	12	+ 0 - Professor (administrator)
	13	+ 1465 - Gil Vicente
	14	+ .
	15	+ .
	16	+ .
	17	+ 1924 - Alexandre O'Neill
	18	+$ mv students.db demo/
	19	+$ ./serve.py demo/test.yaml
	20	+2016-07-13 15:19:21,718 \| INFO \| app \| ============= Running perguntations =============
	21	+2016-07-13 15:19:21,740 \| INFO \| questions \| Loaded 9 questions from "questions.yaml".
	22	+2016-07-13 15:19:21,740 \| INFO \| test \| Test factory ready for "demo".
	23	+2016-07-13 15:19:21,756 \| INFO \| app \| Database has 9 students registered.
	24	+...
	25	+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
	26	+2016-07-13 15:19:21,919 \| INFO \| cherrypy.error \| [13/Jul/2016:15:19:21] ENGINE Bus STARTED
	27	+```
	28	+
	29	+You can now open a browser and point it to the server address, e.g. `http://127.0.0.1:8080`.
	30	+
	31	+Enter `0` for the number and any password. This will be your password from now on.
	32	+
	33	+After login, you will see an administrator page. This page allows you to:
	34	+
	35	+- Generate a sample test just for you to see if it looks right.
	36	+- 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.
	37	+- 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.
	38	+- 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.
	39	+- Online students will be marked and the table on the top of the page will show some more information (login time, ip address, etc)
	40	+- If a student moves away from the browser (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...
	41	+- It is also possible to add new students by clicking the button on the bottom of the page.
	42	+
	43	+## Answering a test
	44	+
	45	+Students are redirected to a test as soon as they login.
	46	+
	47	+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.
	48	+
	49	+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.
	50	+
	51	+## Creating a new test
	52	+
	53	+A test is just a yaml file with the configuration for that test. Look at `demo/test.yaml` for an example.
	54	+
	55	+## Creating questions
	56	+
	57	+Questions are defined in yaml files. Each yaml file contains a list of questions
6	58
7		-- CherryPy (3.7.0)
8		-- Mako (1.0.1)
9		-- Markdown (2.6.2)
10		-- PyYAML (3.11)
11		-- bcrypt (2.0.0)
12	59
13	60	Before using the program you need to
14	61
...	...
...	...	@@ -28,13 +28,14 @@
28	28	solar_system_planets: images/planets.png
29	29	text: Qual é o maior planeta do Sistema Solar? <img src="solar_system_planets" width="100%"/>
30	30	options:
31		- - Júpiter
32	31	- Mercúrio
33	32	- Marte
	33	+ - Júpiter
	34	+ - Têm todos o mesmo tamanho
34	35	# opcional
35		- correct: 0
36	36	title: Sistema solar
37		- shuffle: True
	37	+ correct: 2
	38	+ shuffle: False
38	39	discount: True
39	40	hint: Se usar o markdown `!(text)[imagem]` a imagem fica com tamanho fixo. É preferível usar a tag html `<img with="100%" src="...">` para ter sempre a largura correcta.
40	41	# ---------------------------------------------------------------------------
...	...
1	1	#=============================================================================
	2	+# The test reference should be a unique identifier. It is saved in the database
	3	+# so that queries for the results can be done in the terminal with
	4	+# $ sqlite3 students.db "select * from tests where ref='demo'"
2	5	ref: demo
	6	+
	7	+# (optional, default: '') You may wish to refer the course, year or kind of test
3	8	title: Exame de Demonstração
4	9
5	10	# Database with student credentials and grades of all questions and tests done
6		-# The database is an sqlite3 file generate with the script initdb_from_csv.py
	11	+# The database is an sqlite3 file generate with the script initdb.py
7	12	database: demo/students.db
8	13
9	14	# (optional) Generate a file for each test done by a student.
10	15	# It includes the questions, answers and grades.
11		-# If undefined, then no tests are saved (useful for debug and training)
	16	+# If undefined, then no tests are saved (useful for debug and training).
12	17	save_answers: yes
13	18	answers_dir: demo/ans
14	19
15		-# Show points for each question, scale 0-20 (default: False)
	20	+# (optional, default: False) Show points for each question, scale 0-20.
16	21	show_points: True
17	22
18		-# Show question's hint if available (default: False)
	23	+# (optional, default: False) Show hints if available
19	24	show_hints: True
20	25
21		-# Show lots of information for debugging (default: False)
	26	+# (optional, default: False) Show lots of information for debugging
22	27	# debug: True
23	28
24	29	#-----------------------------------------------------------------------------
25	30	# Base path applied to the questions files and all the scripts
26	31	# including question generators and correctors.
27		-# Either absolute path or relative to current directory.
	32	+# Either absolute path or relative to current directory can be used.
28	33	questions_dir: demo/questions
29	34
30	35	# (optional) List of files containing questions in yaml format.
31	36	# Selected questions will be obtained from these files.
32		-# If undefined, all files in questions_dir are loaded.
	37	+# If undefined, all yaml files in questions_dir are loaded (not recommended).
33	38	files:
34	39	- questions.yaml
35	40
36		-# This is the list of questions. If a "ref:" has a list of keys, then
37		-# one question is selected from the list.
38		-# The following example will generate a test with 3 questions.
	41	+# This is the list of questions that will make up the test.
	42	+# The order is preserved.
	43	+# There are several ways to define each question (explained below).
39	44	questions:
40		- - instructions
	45	+ # show question where ref=instructions
	46	+ - ref: instructions
	47	+
	48	+ # show question where ref=flags and assigns 0.5 points (unnormalized)
41	49	- ref: flags
42	50	points: 0.5
	51	+
	52	+ # idem
43	53	- ref: math-expressions
44	54	points: 2.0
	55	+
	56	+ # show question where ref=solar-system and assign the default of 1.0 point (unnormalized)
45	57	- ref: solar-system
46		- # points: 1.0 is the default, if omitted
47		- - ref: # choose one of the following list of questions
	58	+
	59	+ # select one questions from the list [our_planet1, our_planet2]
	60	+ # and assign 0.75 points (unnormalized)
	61	+ - ref:
48	62	- our_planet1
49	63	- our_planet2
50	64	points: 0.75
51		- - basic-colors # same as `ref: basic-colors`
	65	+
	66	+ # the key 'ref:' can be omitted, a default of 1.0 points is assigned
	67	+ - basic-colors
	68	+
52	69	- question-whatever
	70	+
53	71	- markdown_instructions
...	...
...	...	@@ -49,23 +49,37 @@ try:
49	49	session.add_all([Student(id=r['N.º'], name=fix(r['Nome']), password='') for r in csvreader])
50	50	else:
51	51	# otherwise add 5 fake students
52		- session.add_all([
53		- Student(id='student1', name='Student1', password=''),
54		- Student(id='student2', name='Student2', password=''),
55		- Student(id='student3', name='Student3', password=''),
56		- Student(id='student4', name='Student4', password=''),
57		- Student(id='student5', name='Student5', password=''),
58		- ])
	52	+ fakes = [
	53	+ ['1888', 'Fernando Pessoa'],
	54	+ ['1799', 'Almeida Garrett'],
	55	+ ['1845', 'José Maria Eça de Queirós'],
	56	+ ['1465', 'Gil Vicente'],
	57	+ ['1825', 'Camilo Castelo Branco'],
	58	+ ['1842', 'Antero de Quental'],
	59	+ ['1907', 'Miguel Torga'],
	60	+ ['1810', 'Alexandre Herculano'],
	61	+ ['1924', 'Alexandre O\'Neill'],
	62	+ ]
	63	+ session.add_all([Student(id=i, name=name, password='') for i,name in fakes])
59	64
60	65	session.commit()
61	66
62	67	except Exception:
63	68	session.rollback()
64		- print('Erro: Dados já existentes na base de dados?')
	69	+ print('Error: Database already exists.')
65	70	sys.exit(1)
66	71
67	72	else:
68	73	n = session.query(Student).count()
69		- print('Base de dados inicializada com {} utilizadores.'.format(n))
	74	+ print('New database created: {0}\n{1} users inserted:'.format(args.db, n))
	75	+
	76	+ users = session.query(Student).order_by(Student.id).all()
	77	+ print(' {0:8} - {1} (administrator)'.format(users[0].id, users[0].name))
	78	+ if n > 1:
	79	+ print(' {0:8} - {1}'.format(users[1].id, users[1].name))
	80	+ if n > 3:
	81	+ print(' .\n .\n .')
	82	+ if n > 2:
	83	+ print(' {0:8} - {1}'.format(users[-1].id, users[-1].name))
70	84
71	85	# --- end session ---
...	...