From ca9934fac522d84d5268d2992f0e977259340d24 Mon Sep 17 00:00:00 2001 From: Miguel Barao Date: Mon, 24 Oct 2016 14:30:14 +0100 Subject: [PATCH] - updated README.md --- BUGS.md | 6 ++++-- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++------------------------ 2 files changed, 49 insertions(+), 26 deletions(-) diff --git a/BUGS.md b/BUGS.md index de058c2..9ecad8b 100644 --- a/BUGS.md +++ b/BUGS.md @@ -1,17 +1,18 @@ # 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 "testeRef:numPergunta" # 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-- diff --git a/README.md b/README.md index 72b3170..9b98f90 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,14 @@ # 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 ^C. -### 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 -- libgit2 0.21.2