Documentation updates and changed the python3.4 to python3 so that other versions can be used

Miguel Barao
1 parent c8de491d
Showing 7 changed files with 56 additions and 42 deletions Show diff stats
README.md
demo/correct-question.py
demo/generate-question.py
demo/questions.yaml
demo/test.yaml
initdb_from_csv.py
serve.py
@@ -3,38 +3,52 @@
 ### Requirements:
-Installed using `pip3`:
+The webserver is a python3 application and only requires python to be installed. Versions 3.3, 3.4 and 3.5 should be Ok. It does not require any other webserver (apache, ...)
-- CherryPy (3.7.0)
-- Mako (1.0.1)
-- Markdown (2.6.2)
-- PyYAML (3.11)
-- bcrypt (2.0.0)
+Installed using `pip`:
+
+- CherryPy (>=3.7.0)
+- Mako (>=1.0.1)
+- Markdown (>=2.6.2)
+- PyYAML (>=3.11)
+- bcrypt (>=2.0.0)
 ### System setup:
-Open a terminal and navigate to a directory where this software is to be installed, e.g. `/var/www`. Then run the following commands:
+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:
-```
-#!bash
+```.bash
+
+cd WHERE/TO/PUT/THE/SOFTWARE
-# get the software using git
+# get software using git
 git clone https://mjsb@bitbucket.org/mjsb/perguntations.git
 cd perguntations
 # create database in the directory db/
-initdb_from_csv.py siiue.csv
+./initdb_from_csv.py YOUR_CSV_FILE_HERE
 mkdir db
 mv students.db db
-# update test configuration
-vi demo/test.yaml                # update students_db
+# update test configuration with the correct database file.
+vi demo/test.yaml
+# Edit line 7 to something like
+# database: db/students.db
+
+# get help
+./serve.py --help 
 # run demo test
-./serve demo/test.yaml
+./serve.py demo/test.yaml
+
+# open browser at http://127.0.0.1:8080/
+# the professor is number 0
+
+# ^C to terminate the server
 ```
-(For the time being, also create `ans`, `questions`, `tests`, `scripts`, `sessions` in the same directory, until paths are fixed)
+(FIXME For the time being, also create `ans`, `questions`, `tests`, `scripts`, `sessions` in the same directory, until paths are fixed)
 ### Contribute ###
-#!/usr/bin/env python3.4
+#!/usr/bin/env python3
 import re
 import sys
-#!/usr/bin/env python3.4
+#!/usr/bin/env python3
 from random import randint
 import sys
 -
     ref: solar-system-jupiter
     type: radio
-    text: Which one is the largest planet?
+    text: Qual dos seguintes é o maior planeta?
     options:
         - Jupiter
         - Mercury
@@ -10,12 +10,12 @@
     correct: 0
     shuffle: True
     discount: True
-    hint: Just don't choose the wrong ones
+    hint: Também é o mais pesado.
 # ---------------------------------------------------------------------------
 -
     ref: solar-system-mars
     type: checkbox
-    text: Which ones are correct?
+    text: Quais das seguintes expressões são verdadeiras?
     options:
         - $1 > 0$
         - $-1 > 1$
@@ -24,28 +24,28 @@
     correct: [1, -1, 1, 0.5]
     # optional
     discount: True
-    hint:  There are three.
+    hint:  Uma delas é falsa.
 # ---------------------------------------------------------------------------
 -
     ref: question-v1
     type: text
-    text: What's your favorite basic color?
-    correct: ['blue', 'green']
-    hint: It's not red.
+    text: Qual é a minha cor básica favorita?
+    correct: ['Azul', 'Verde']
+    hint: Só há 3 cores básicas e não gosto de vermelho.
 # ---------------------------------------------------------------------------
 -
     ref: question-v2
     type: text_regex
-    text: What's my favorite basic color?
-    correct: '[bB]lue'
-    hint: It's not red.
+    text: Qual é a minha cor básica favorita?
+    correct: '[aA]zul'
+    hint: O céu é...
 # ---------------------------------------------------------------------------
 -
     ref: question-colors
     type: textarea
-    text: Write names of the three basic colors.
+    text: Escreva o nome de três cores básicas.
     correct: correct-question.py
-    hint: They start by RGB and order does not matter.
+    hint: Qualquer ordem serve.
 # ---------------------------------------------------------------------------
 -
     ref: question-whatever
@@ -58,14 +58,14 @@
 -
     ref: one-question
     type: information
-    text: Please do not cheat.
+    text: Não vale fazer batota.
 # ---------------------------------------------------------------------------
 -
     ref: another-question
     # type: information (default)
     text:   |
-            The text of questions is parsed as __markdown__ and can include
-            LaTeX formulas $\sqrt{2\pi}$ and pretty code
+            O texto das perguntas é escrito em __markdown__ e pode incluir formulas em
+            LaTeX $\sqrt{2\pi}$ e código lindinho
             ```.C
             int main() {
@@ -4,7 +4,7 @@ title: Teste de Demonstração
 # database contains students+passwords, final results of the tests, and questions done
 # database: path/to/students.db
-database: inscritos.db
+database: db/students.db
 # this will generate a file for each test done. The file is like a replacement
 # for a test done in paper.
@@ -17,8 +17,8 @@ practice: True
 # debug: False
 #-----------------------------------------------------------------------------
-# This is the base path applied to the questions files and all the scripts
-# including generators and correctors.
+# Base path applied to the questions files and all the scripts
+# including question generators and correctors.
 # Either absolute path or relative to current directory.
 path: demo
 # (Note: answers are saved in a different path defined in answers_dir)
-#!/usr/bin/env python3.4
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 import sqlite3
-#!/usr/bin/env python3.4
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 # The program runs a web server where students login to answer a sequence of questions.
@@ -10,14 +10,14 @@ import argparse
 from os import path
 # path where this file is located
-server_path = path.dirname(path.realpath(__file__))
+SERVER_PATH = path.dirname(path.realpath(__file__))
+TEMPLATES_DIR = SERVER_PATH + '/templates'
 # my code
 from myauth import AuthController, require
 import test
 import database
-TEMPLATES_DIR = server_path + '/templates'
 # ============================================================================
@@ -153,7 +153,7 @@ class Root(object):
 # ============================================================================
 def parse_arguments():
     argparser = argparse.ArgumentParser(description='Server for online tests. Enrolled students and tests have to be previously configured. Please read the documentation included with this software before running the server.')
-    serverconf_file = path.normpath(path.join(server_path, 'config', 'server.conf'))
+    serverconf_file = path.normpath(path.join(SERVER_PATH, 'config', 'server.conf'))
     argparser.add_argument('--server', default=serverconf_file, type=str, help='server configuration file')
     argparser.add_argument('--debug', action='store_true',
         help='Show datastructures when rendering questions')
@@ -178,7 +178,7 @@ if __name__ == &#39;__main__&#39;:
     print('=' * 79)
     print('- Title:      %s' % testconf['title'])
-    print('- StudentsDB: %s' % testconf['database'])
+    print('- Database:   %s' % testconf['database'])
     print('- Questions:\n     ', '\n      '.join(testconf['files']))
     print('      (%i questions read)' % len(testconf['questions']))
     print('-' * 79)
@@ -188,7 +188,7 @@ if __name__ == &#39;__main__&#39;:
     root = Root(testconf)
     # --- Mount and run server.
-    cherrypy.config.update({'tools.staticdir.root': server_path})
+    cherrypy.config.update({'tools.staticdir.root': SERVER_PATH})
     cherrypy.quickstart(root, '/', config=arg.server)
     cherrypy.log('Terminated OK ------------------------', 'APPLICATION')
     print('\n- Server terminated OK')
1	-#!/usr/bin/env python3.4	1	+#!/usr/bin/env python3
2		2
3	import re	3	import re
4	import sys	4	import sys
1	-#!/usr/bin/env python3.4	1	+#!/usr/bin/env python3
2		2
3	from random import randint	3	from random import randint
4	import sys	4	import sys
1	-#!/usr/bin/env python3.4	1	+#!/usr/bin/env python3
2	# -- coding: utf-8 --	2	# -- coding: utf-8 --
3		3
4	import sqlite3	4	import sqlite3