fixed merge conflict in README.md

Miguel Barao
2 parents c3e00c92 2cb7e170
Showing 5 changed files with 65 additions and 39 deletions Show diff stats
README.md
demo/test.yaml
initdb.py
serve.py
test.py
 # README #
  
-
 ### Requirements:
  
-The webserver is a python 3.5+ application.
-
-Requires the following python packages, which can be installed using `pip`:
+The webserver is a python application and requires python 3.5+ to be installed.
  
-- CherryPy (>=3.7.0)
-- Mako (>=1.0.1)
-- Markdown (>=2.6.2)
-- PyYAML (>=3.11)
-- bcrypt (>=2.0.0)
+The following additional python packages are required:
  
-### System setup:
+- CherryPy
+- Mako
+- Markdown
+- PyYAML
+- Pygments
+- SQLAlchemy
+- bcrypt
  
-Open a terminal and navigate to a directory where this software is to be installed, e.g. `/var/www` or `/home/username`. 
-Run the following commands:
+These can be installed globally or in a python virtual environment.
  
 ```.bash
+# install in a virtualenv
+pyvenv-3.5 venv/perguntations         # or choose another virtualenv directory
+source venv/perguntations/bin/activate     # activate virtualenv
+
+pip3.5 install cherrypy
+pip3.5 install mako
+pip3.5 install markdown
+pip3.5 install pyyaml
+pip3.5 install pygments
+pip3.5 install sqlalchemy
+pip3.5 install bcrypt
+```
+
+To install `perguntations`:
  
+```.bash
 cd WHERE/TO/PUT/THE/SOFTWARE
+git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
+```
+
+where USERNAME is your account on bitbucket.
+
+### System setup:
+
+The following commands will show how to run a demonstration test:
  
-# get software using git
-git clone https://USER@bitbucket.org/USER/perguntations.git
-cd perguntations
+```.bash
+cd WHERE/YOU/INSTALLED/perguntations
  
-# create database (if no csv file is provided, a database with 5 fake students is created for debugging)
-./initdb.py CSV_FILE_HERE
-mv students.db SOMEWHERE
+# create database.
+# a database with 5 fake students is created if no CSV file is provided
+./initdb_from_csv.py OPTIONAL_CSV_FILE
+mv students.db demo/
  
-# update test configuration with the correct database file.
+# edit test configuration and check if everything looks right
 vi demo/test.yaml
-# Edit line 7 to something like
-# database: SOMEWHERE/students.db
  
-# edit server configuration if needed
+# edit server configuration and check if everything looks right
 vi config/server.conf
+```
+
+We are now ready to run the server:
  
+```.bash
 # get help
 ./serve.py --help 
  
 # run demo test
 ./serve.py demo/test.yaml
+```
  
-# open browser at http://127.0.0.1:8080/
-# the professor/administrator is number 0
+Open the browser at `http://127.0.0.1:8080/` and login as user number `0` (administrator) and:
  
-# ^C to terminate the server
-```
+1. Authorize students by clicking the checkboxes.
+2. Open a different browser at `http://127.0.0.1:8080/` and login as one of the authorized students. Answer the questions and submit.
+
+The server can be stoped from the terminal with <kbd>^C</kbd>.
  
 ### Troubleshooting
  
@@ -4,7 +4,7 @@ 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
-database: ~/Work/Projects/perguntations/demo/students.db
+database: demo/students.db
  
 # (optional) Generate a file for each test done by a student.
 # It includes the questions, answers and grades.
@@ -35,24 +35,27 @@ Session = sessionmaker(bind=engine)
 try:
     session = Session()
  
-    # add administrator and fake student accounts
-    session.add_all([
-        Student(id='0', name='Professor', password=''),
-        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=''),
-        ])
+    # add administrator
+    session.add(Student(id='0', name='Professor', password=''))
  
-    # add enrolled students from csv file
+    # add students
     if args.csvfile:
+        # from csv file if available
         try:
             csvreader = csv.DictReader(open(args.csvfile, encoding='iso-8859-1'), delimiter=';', quotechar='"')
         except EnvironmentError:
             print('CSV file "{0}" not found!'.format(args.csvfile))
         else:
             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=''),
+            ])
  
     session.commit()
  
@@ -313,7 +313,6 @@ if __name__ == &#39;__main__&#39;:
         app = App(filename, vars(arg))
     except Exception as e:
         logging.critical('Can\'t start application.')
-        raise e  # FIXME just for testing
         sys.exit(1)
  
     # --- create webserver
@@ -179,7 +179,6 @@ class TestFactory(dict):
             'show_points': self['show_points'],
             'show_ref': self['show_ref'],
             'debug': self['debug'],
-            # 'answers_dir': self['answers_dir'],
             'database': self['database'],
             'questions_dir': self['questions_dir'],
             'files': self['files'],
1	1	# README #
2	2
3		-
4	3	### Requirements:
5	4
6		-The webserver is a python 3.5+ application.
7		-
8		-Requires the following python packages, which can be installed using `pip`:
	5	+The webserver is a python application and requires python 3.5+ to be installed.
9	6
10		-- CherryPy (>=3.7.0)
11		-- Mako (>=1.0.1)
12		-- Markdown (>=2.6.2)
13		-- PyYAML (>=3.11)
14		-- bcrypt (>=2.0.0)
	7	+The following additional python packages are required:
15	8
16		-### System setup:
	9	+- CherryPy
	10	+- Mako
	11	+- Markdown
	12	+- PyYAML
	13	+- Pygments
	14	+- SQLAlchemy
	15	+- bcrypt
17	16
18		-Open a terminal and navigate to a directory where this software is to be installed, e.g. `/var/www` or `/home/username`.
19		-Run the following commands:
	17	+These can be installed globally or in a python virtual environment.
20	18
21	19	```.bash
	20	+# install in a virtualenv
	21	+pyvenv-3.5 venv/perguntations # or choose another virtualenv directory
	22	+source venv/perguntations/bin/activate # activate virtualenv
	23	+
	24	+pip3.5 install cherrypy
	25	+pip3.5 install mako
	26	+pip3.5 install markdown
	27	+pip3.5 install pyyaml
	28	+pip3.5 install pygments
	29	+pip3.5 install sqlalchemy
	30	+pip3.5 install bcrypt
	31	+```
	32	+
	33	+To install `perguntations`:
22	34
	35	+```.bash
23	36	cd WHERE/TO/PUT/THE/SOFTWARE
	37	+git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
	38	+```
	39	+
	40	+where USERNAME is your account on bitbucket.
	41	+
	42	+### System setup:
	43	+
	44	+The following commands will show how to run a demonstration test:
24	45
25		-# get software using git
26		-git clone https://USER@bitbucket.org/USER/perguntations.git
27		-cd perguntations
	46	+```.bash
	47	+cd WHERE/YOU/INSTALLED/perguntations
28	48
29		-# create database (if no csv file is provided, a database with 5 fake students is created for debugging)
30		-./initdb.py CSV_FILE_HERE
31		-mv students.db SOMEWHERE
	49	+# create database.
	50	+# a database with 5 fake students is created if no CSV file is provided
	51	+./initdb_from_csv.py OPTIONAL_CSV_FILE
	52	+mv students.db demo/
32	53
33		-# update test configuration with the correct database file.
	54	+# edit test configuration and check if everything looks right
34	55	vi demo/test.yaml
35		-# Edit line 7 to something like
36		-# database: SOMEWHERE/students.db
37	56
38		-# edit server configuration if needed
	57	+# edit server configuration and check if everything looks right
39	58	vi config/server.conf
	59	+```
	60	+
	61	+We are now ready to run the server:
40	62
	63	+```.bash
41	64	# get help
42	65	./serve.py --help
43	66
44	67	# run demo test
45	68	./serve.py demo/test.yaml
	69	+```
46	70
47		-# open browser at http://127.0.0.1:8080/
48		-# the professor/administrator is number 0
	71	+Open the browser at `http://127.0.0.1:8080/` and login as user number `0` (administrator) and:
49	72
50		-# ^C to terminate the server
51		-```
	73	+1. Authorize students by clicking the checkboxes.
	74	+2. Open a different browser at `http://127.0.0.1:8080/` and login as one of the authorized students. Answer the questions and submit.
	75	+
	76	+The server can be stoped from the terminal with <kbd>^C</kbd>.
52	77
53	78	### Troubleshooting
54	79
...	...
...	...	@@ -4,7 +4,7 @@ title: Exame de Demonstração
4	4
5	5	# Database with student credentials and grades of all questions and tests done
6	6	# The database is an sqlite3 file generate with the script initdb_from_csv.py
7		-database: ~/Work/Projects/perguntations/demo/students.db
	7	+database: demo/students.db
8	8
9	9	# (optional) Generate a file for each test done by a student.
10	10	# It includes the questions, answers and grades.
...	...
...	...	@@ -35,24 +35,27 @@ Session = sessionmaker(bind=engine)
35	35	try:
36	36	session = Session()
37	37
38		- # add administrator and fake student accounts
39		- session.add_all([
40		- Student(id='0', name='Professor', password=''),
41		- Student(id='student1', name='Student1', password=''),
42		- Student(id='student2', name='Student2', password=''),
43		- Student(id='student3', name='Student3', password=''),
44		- Student(id='student4', name='Student4', password=''),
45		- Student(id='student5', name='Student5', password=''),
46		- ])
	38	+ # add administrator
	39	+ session.add(Student(id='0', name='Professor', password=''))
47	40
48		- # add enrolled students from csv file
	41	+ # add students
49	42	if args.csvfile:
	43	+ # from csv file if available
50	44	try:
51	45	csvreader = csv.DictReader(open(args.csvfile, encoding='iso-8859-1'), delimiter=';', quotechar='"')
52	46	except EnvironmentError:
53	47	print('CSV file "{0}" not found!'.format(args.csvfile))
54	48	else:
55	49	session.add_all([Student(id=r['N.º'], name=fix(r['Nome']), password='') for r in csvreader])
	50	+ else:
	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	+ ])
56	59
57	60	session.commit()
58	61
...	...
...	...	@@ -313,7 +313,6 @@ if __name__ == '__main__':
313	313	app = App(filename, vars(arg))
314	314	except Exception as e:
315	315	logging.critical('Can\'t start application.')
316		- raise e # FIXME just for testing
317	316	sys.exit(1)
318	317
319	318	# --- create webserver
...	...
...	...	@@ -179,7 +179,6 @@ class TestFactory(dict):
179	179	'show_points': self['show_points'],
180	180	'show_ref': self['show_ref'],
181	181	'debug': self['debug'],
182		- # 'answers_dir': self['answers_dir'],
183	182	'database': self['database'],
184	183	'questions_dir': self['questions_dir'],
185	184	'files': self['files'],
...	...