Miguel Barão / perguntations

Download as
Browse Code »

Commit ca9934fac522d84d5268d2992f0e977259340d24

Authored by Miguel Barao
1 parent 65fc5e2e
Exists in master and in 1 other branch dev

- updated README.md

Showing 2 changed files with 49 additions and 26 deletions   Show diff stats
BUGS.md
  Diff comments   View file @ca9934f
1 1  
2 2 # BUGS
  3 +
  4 +- servidor nao esta a lidar com eventos scroll/resize
3 5 - se um teste tiver a mesma pergunta (ref igual) varias vezes, rebenta na correcçao. As respostas são agregadas numa lista para cada ref. Ex:
4 6 {'ref1': 'resposta1', 'ref2': ['resposta2a', 'resposta2b']}
5 7 possivelmente as referencias das perguntas deveriam ser o "testeRef:numPergunta"... é preciso ver como depois estao associadas às correcções.
6   -- se ocorrer um erro na correcçao avisar aluno para contactar o professor.
7 8 - se directorio logs não existir no directorio actual (não perguntations) rebenta.
8 9 - usar thread.Lock para aceder a variaveis de estado?
9 10  
10 11 # TODO
11 12  
  13 +- se ocorrer um erro na correcçao avisar aluno para contactar o professor.
12 14 - implementar practice mode.
13 15 - usar http://wtfforms.com para radio e checkboxes
14   -- usar http://fontawesome.io/examples/ em vez dos do bootstrap3
15 16 - abrir o teste numa janela maximizada e que nao permite que o aluno a redimensione/mova.
16 17 - detectar scroll e enviar posição para servidor (analise de scroll para detectar copianço? ou simplesmente para analisar como os alunos percorrem o teste)
17 18 - single page web no teste/correcçao. Página construída em javascript, obter perguntas com ajax (para practice?).
... ... @@ -26,6 +27,7 @@ possivelmente as referencias das perguntas deveriam ser o "testeRef:numPergunta"
26 27  
27 28 # FIXED
28 29  
  30 +- usar http://fontawesome.io/examples/ em vez dos do bootstrap3
29 31 - se pergunta tiver 'type:' errado, rebenta.
30 32 - se submeter um teste so com information, da divisao por zero.
31 33 - se save_answers nao existir, da warning que nao serao gravados, mas sao sempre gravados! pagina de administracao diz --not being saved--
... ...
README.md
  Diff comments   View file @ca9934f
1 1 # README #
2 2  
3   -### Requirements:
  3 +1. [Installation](#installation)
  4 +2. [Running a demo](#running-a-demo)
  5 +3. [Troubleshooting](#troubleshooting)
4 6  
5   -The webserver is a python application and requires python 3.5+ to be installed.
  7 +## Installation
6 8  
7   -The following additional python packages are required:
  9 +### Requirements
  10 +
  11 +The webserver is a python application and requires `python3.5` and `pip` to be installed, plus the following additional packages:
8 12  
9 13 - CherryPy
10 14 - Mako
... ... @@ -14,23 +18,43 @@ The following additional python packages are required:
14 18 - SQLAlchemy
15 19 - bcrypt
16 20  
17   -These can be installed globally or in a python virtual environment.
  21 +These can be installed for a single user (recommended), in a python virtual environment or system wide.
  22 +
  23 +#### Installing packages for a single user (recommended)
  24 +
  25 +```.bash
  26 +pip install --user cherrypy
  27 +pip install --user mako
  28 +pip install --user markdown
  29 +pip install --user pyyaml
  30 +pip install --user pygments
  31 +pip install --user sqlalchemy
  32 +pip install --user bcrypt
  33 +```
  34 +
  35 +#### Installing packages in a virtual environment
18 36  
19 37 ```.bash
20   -# install in a virtualenv
21   -pyvenv-3.5 venv/perguntations # or choose another virtualenv directory
  38 +pyvenv-3.5 venv/perguntations # or other virtualenv directory
22 39 source venv/perguntations/bin/activate # activate virtualenv
23 40  
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
  41 +pip install cherrypy
  42 +pip install mako
  43 +pip install markdown
  44 +pip install pyyaml
  45 +pip install pygments
  46 +pip install sqlalchemy
  47 +pip install bcrypt
31 48 ```
32 49  
33   -To install `perguntations`:
  50 +#### Installing packages system wide
  51 +
  52 +I personally prefer python packages to be installed for a single user, but if a system wide installation is required, it is probably better to use the operating system package manager instead of `pip`:
  53 +
  54 +- Linux: apt-get, etc
  55 +- macOS: macports, etc
  56 +
  57 +### Installing perguntations
34 58  
35 59 ```.bash
36 60 cd WHERE/TO/PUT/THE/SOFTWARE
... ... @@ -39,7 +63,7 @@ git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
39 63  
40 64 where USERNAME is your account on bitbucket.
41 65  
42   -### System setup:
  66 +## Running a demo
43 67  
44 68 The following commands will show how to run a demonstration test:
45 69  
... ... @@ -47,8 +71,8 @@ The following commands will show how to run a demonstration test:
47 71 cd WHERE/YOU/INSTALLED/perguntations
48 72  
49 73 # 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
  74 +# a database with fake students is created if no CSV file is provided
  75 +./initdb.py OPTIONAL_CSV_FILE
52 76 mv students.db demo/
53 77  
54 78 # edit test configuration and check if everything looks right
... ... @@ -61,11 +85,8 @@ vi config/server.conf
61 85 We are now ready to run the server:
62 86  
63 87 ```.bash
64   -# get help
65   -./serve.py --help
66   -
67   -# run demo test
68   -./serve.py demo/test.yaml
  88 +./serve.py --help # get help
  89 +./serve.py demo/test.yaml # run demo test
69 90 ```
70 91  
71 92 Open the browser at `http://127.0.0.1:8080/` and login as user number `0` (administrator) and:
... ... @@ -75,12 +96,12 @@ Open the browser at `http://127.0.0.1:8080/` and login as user number `0` (admin
75 96  
76 97 The server can be stoped from the terminal with <kbd>^C</kbd>.
77 98  
78   -### Troubleshooting
  99 +## Troubleshooting
79 100  
80 101 * If you are getting any `UnicodeEncodeError` type of errors that's because the terminal is not supporting UTF-8. Try running `locale` on the terminal and see if there is any error messages. Solutions:
81 102 - debian: fix it with `sudo dpkg-reconfigure locales`, select your UTF-8 locales and try again.
82 103  
83   -### Contribute ###
  104 +## Contribute ###
84 105  
85 106 * Writing questions in yaml format
86 107 * Testing and reporting bugs
... ...