- updated README.md

Miguel Barao
1 parent 65fc5e2e
Showing 2 changed files with 49 additions and 26 deletions Show diff stats
BUGS.md
README.md
 # BUGS
+
+- servidor nao esta a lidar com eventos scroll/resize
 - 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:
     {'ref1': 'resposta1', 'ref2': ['resposta2a', 'resposta2b']}
 possivelmente as referencias das perguntas deveriam ser o "testeRef:numPergunta"... é preciso ver como depois estao associadas às correcções.
-- se ocorrer um erro na correcçao avisar aluno para contactar o professor.
 - se directorio logs não existir no directorio actual (não perguntations) rebenta.
 - usar thread.Lock para aceder a variaveis de estado?
 # TODO
+- se ocorrer um erro na correcçao avisar aluno para contactar o professor.
 - implementar practice mode.
 - usar http://wtfforms.com para radio e checkboxes
-- usar http://fontawesome.io/examples/ em vez dos do bootstrap3
 - abrir o teste numa janela maximizada e que nao permite que o aluno a redimensione/mova.
 - 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)
 - 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 &quot;testeRef:numPergunta&quot;
 # FIXED
+- usar http://fontawesome.io/examples/ em vez dos do bootstrap3
 - se pergunta tiver 'type:' errado, rebenta.
 - se submeter um teste so com information, da divisao por zero.
 - se save_answers nao existir, da warning que nao serao gravados, mas sao sempre gravados! pagina de administracao diz --not being saved--
 # README #
-### Requirements:
+1. [Installation](#installation)
+2. [Running a demo](#running-a-demo)
+3. [Troubleshooting](#troubleshooting)
-The webserver is a python application and requires python 3.5+ to be installed.
+## Installation
-The following additional python packages are required:
+### Requirements
+
+The webserver is a python application and requires `python3.5` and `pip` to be installed, plus the following additional packages:
 - CherryPy
 - Mako
@@ -14,23 +18,43 @@ The following additional python packages are required:
 - SQLAlchemy
 - bcrypt
-These can be installed globally or in a python virtual environment.
+These can be installed for a single user (recommended), in a python virtual environment or system wide.
+
+#### Installing packages for a single user (recommended)
+
+```.bash
+pip install --user cherrypy
+pip install --user mako
+pip install --user markdown
+pip install --user pyyaml
+pip install --user pygments
+pip install --user sqlalchemy
+pip install --user bcrypt
+```
+
+#### Installing packages in a virtual environment
 ```.bash
-# install in a virtualenv
-pyvenv-3.5 venv/perguntations         # or choose another virtualenv directory
+pyvenv-3.5 venv/perguntations              # or other 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
+pip install cherrypy
+pip install mako
+pip install markdown
+pip install pyyaml
+pip install pygments
+pip install sqlalchemy
+pip install bcrypt
 ```
-To install `perguntations`:
+#### Installing packages system wide
+
+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`:
+
+- Linux: apt-get, etc
+- macOS: macports, etc
+
+### Installing perguntations
 ```.bash
 cd WHERE/TO/PUT/THE/SOFTWARE
@@ -39,7 +63,7 @@ git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
 where USERNAME is your account on bitbucket.
-### System setup:
+## Running a demo
 The following commands will show how to run a demonstration test:
@@ -47,8 +71,8 @@ The following commands will show how to run a demonstration test:
 cd WHERE/YOU/INSTALLED/perguntations
 # create database.
-# a database with 5 fake students is created if no CSV file is provided
-./initdb_from_csv.py OPTIONAL_CSV_FILE
+# a database with fake students is created if no CSV file is provided
+./initdb.py OPTIONAL_CSV_FILE
 mv students.db demo/
 # edit test configuration and check if everything looks right
@@ -61,11 +85,8 @@ 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
+./serve.py --help            # get help
+./serve.py demo/test.yaml    # run demo test
 ```
 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
 The server can be stoped from the terminal with <kbd>^C</kbd>.
-### Troubleshooting
+## Troubleshooting
 * 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:
     - debian: fix it with `sudo dpkg-reconfigure locales`, select your UTF-8 locales and try again.
-### Contribute ###
+## Contribute ###
 * Writing questions in yaml format
 * Testing and reporting bugs