Miguel Barão / perguntations

Download as
Browse Code »

Commit 2cb7e170db30eb8005bdea1d9a40f223ddc3fe83

Authored by Miguel Barao
1 parent 94ba5a95
Exists in master and in 1 other branch dev

- updated README.md documentation. 

- updated init.db so that fake students are added only if no csv is
  provided.
Showing 5 changed files with 65 additions and 40 deletions   Show diff stats
1 # README # 1 # README #
2 2
3 -  
4 ### Requirements: 3 ### Requirements:
5 4
6 -The webserver is a python3 application and only requires python to be installed. Requires python 3.5 or above. It does not require any other webserver (apache, ...)  
7 -  
8 -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 ```.bash 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 cd WHERE/TO/PUT/THE/SOFTWARE 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://mjsb@bitbucket.org/mjsb/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_from_csv.py YOUR_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 vi demo/test.yaml 55 vi demo/test.yaml
35 -# Edit line 7 to something like  
36 -# database: SOMEWHERE/students.db  
37 56
38 -# edit server configuration 57 +# edit server configuration and check if everything looks right
39 vi config/server.conf 58 vi config/server.conf
40 -# Edit lines 26--27 to point to the desired log files location. 59 +```
  60 +
  61 +We are now ready to run the server:
41 62
  63 +```.bash
42 # get help 64 # get help
43 ./serve.py --help 65 ./serve.py --help
44 66
45 # run demo test 67 # run demo test
46 ./serve.py demo/test.yaml 68 ./serve.py demo/test.yaml
  69 +```
47 70
48 -# open browser at http://127.0.0.1:8080/  
49 -# the professor is number 0 71 +Open the browser at `http://127.0.0.1:8080/` and login as user number `0` (administrator) and:
50 72
51 -# ^C to terminate the server  
52 -``` 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>.
53 77
54 ### Troubleshooting 78 ### Troubleshooting
55 79
demo/test.yaml
  Diff comments   View file @2cb7e17
@@ -4,7 +4,7 @@ title: Exame de Demonstração @@ -4,7 +4,7 @@ title: Exame de Demonstração
4 4
5 # Database with student credentials and grades of all questions and tests done 5 # 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 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 # (optional) Generate a file for each test done by a student. 9 # (optional) Generate a file for each test done by a student.
10 # It includes the questions, answers and grades. 10 # It includes the questions, answers and grades.
@@ -35,24 +35,27 @@ Session = sessionmaker(bind=engine) @@ -35,24 +35,27 @@ Session = sessionmaker(bind=engine)
35 try: 35 try:
36 session = Session() 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 if args.csvfile: 42 if args.csvfile:
  43 + # from csv file if available
50 try: 44 try:
51 csvreader = csv.DictReader(open(args.csvfile, encoding='iso-8859-1'), delimiter=';', quotechar='"') 45 csvreader = csv.DictReader(open(args.csvfile, encoding='iso-8859-1'), delimiter=';', quotechar='"')
52 except EnvironmentError: 46 except EnvironmentError:
53 print('CSV file "{0}" not found!'.format(args.csvfile)) 47 print('CSV file "{0}" not found!'.format(args.csvfile))
54 else: 48 else:
55 session.add_all([Student(id=r['N.º'], name=fix(r['Nome']), password='') for r in csvreader]) 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 session.commit() 60 session.commit()
58 61
@@ -313,7 +313,6 @@ if __name__ == &#39;__main__&#39;: @@ -313,7 +313,6 @@ if __name__ == &#39;__main__&#39;:
313 app = App(filename, vars(arg)) 313 app = App(filename, vars(arg))
314 except Exception as e: 314 except Exception as e:
315 logging.critical('Can\'t start application.') 315 logging.critical('Can\'t start application.')
316 - raise e # FIXME just for testing  
317 sys.exit(1) 316 sys.exit(1)
318 317
319 # --- create webserver 318 # --- create webserver
@@ -179,7 +179,6 @@ class TestFactory(dict): @@ -179,7 +179,6 @@ class TestFactory(dict):
179 'show_points': self['show_points'], 179 'show_points': self['show_points'],
180 'show_ref': self['show_ref'], 180 'show_ref': self['show_ref'],
181 'debug': self['debug'], 181 'debug': self['debug'],
182 - # 'answers_dir': self['answers_dir'],  
183 'database': self['database'], 182 'database': self['database'],
184 'questions_dir': self['questions_dir'], 183 'questions_dir': self['questions_dir'],
185 'files': self['files'], 184 'files': self['files'],