Commits

Martin Czygan committed edb36db

more docs

  • Participants
  • Parent commits f5d4c06

Comments (0)

Files changed (9)

audrid/validators.py

     required('task'): all(unicode, length(min=10, max=65535)),    
     required('text'): unicode,
     required('gaps'): dict,
-    required('answer'): dict,
+    'answer': dict,
 })
 
 text = Schema({
     'options' : dict,
     required('id'): all(unicode, length(min=6, max=10)),
     required('task'): all(unicode, length(min=10, max=65535)),    
-    required('answer'): unicode,
+    'answer': unicode,
 })
 
 single = Schema({
     'options' : dict,    
     required('id'): all(unicode, length(min=6, max=10)),
     required('task'): all(unicode, length(min=10, max=65535)),
-    required('answer'): unicode,
+    'answer': unicode,
 })
 
 choice = Schema({
     required('id'): all(unicode, length(min=6, max=10)),
     required('task'): all(unicode, length(min=10, max=65535)),
     required('choices'): [choice],
-    required('answer'): list,
+    'answer': list,
 })
 
 mapping = Schema({
     required('id'): all(unicode, length(min=6, max=10)),
     required('task'): all(unicode, length(min=10, max=65535)),
     required('mapping'): dict,
-    required('answer'): dict,
+    'answer': dict,
 })
 
 task = Schema(any(mapping, multiple_choice, single, text, cloze))

docs/source/api.rst

-API
-===
-
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
-quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
-consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
-proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+API Reference
+=============
+
+Users
+-----
+
+Users are minimal at the moment. They come with a unique username, a unique email
+and a group, which is just a string, which can be one of:
+
+* Guest
+* Editor
+* Admin
+
+Pools
+-----
+
+Pools are the content-backbone of tests. 
+
+Exams
+-----
+
+Exams are what candidates like to take.
+
+Audits
+------
+
+Audits represent the actions of an candidate during a test.

docs/source/frontend.rst

+Frontend
+========
+
+The frontend uses a responsive design. The following screens have been implemented:
+
+* Registration
+* Login
+* Request Password Reset
+* Password Reset
+* Index (default screen when not logged in)
+
+For admins:
+
+* Home (default, when logged in, with Activity Feed)
+* Create Pool
+* Edit Pool
+* Create Exam
+* Show Audits (Registrations)
+
+For editor:
+
+* Home (default, when logged in, Activity Feed, Show uncorrected audits)
+* Correct Audit
+
+For guests:
+
+* Show available exams
+* Register for exam
+* The audit-in-progress screen

docs/source/index.rst

    intro
    models
    validators
-   api
+   api
+   testing
+   frontend

docs/source/intro.rst

 Introduction
 ============
 
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
-quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
-consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
-proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Audrid is an experimental web-based e-assessment application. It tries to say
+no to overweight task specifications and to embrace a document-oriented
+approach, while staying as sane as possible. And yes, it strives to offer a
+fully equipped REST-API as well.

docs/source/models.rst

 Models
 ======
 
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
-quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
-consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
-proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+There are three domain models in the system:
+
+* Pools
+* Exams
+* Audits
+
+Furthermore there are models for essential services,
+such as
+
+* Users
+* PoolVersions
+* Log
+
+The finer grained models for pools, tasks and answers
+are specified in a document-oriented manner. These
+objects are explained in the validators chapter.

docs/source/testing.rst

+Testing
+=======
+
+There are 50 unittest implemented. Most easily run via:
+
+::
+
+	$ nosetests tests/

docs/source/validators.rst

 
 Validators are a core part of the application, since most content is persisted
 in a document-oriented fashion. Validators are used to check all incoming data
-for sanity. There are 3-5 types of payloads: 
+for sanity. There are four types of payloads: 
 
 * Tasks
 * Pools
 * Exams
 * Audits
-* Answers
 
 There are `many validation libraries <http://stackoverflow.com/q/12235120>`_
 available for Python. We will use `voluptuous <https://github.com/alecthomas/voluptuous>`_.
 ::
 
     single = Schema({
-        required('kind') : 'single',
+        required('kind'): 'single',
         required('id'): all(unicode, length(min=6, max=10)),
         required('task'): all(unicode, length(min=10, max=65535)),
-        required('answer'): unicode,
-        'options' : dict,            
+        'answer': all(unicode, length(min=10, max=140)),
+        'options': dict,
     })
 
 An example input would be:
 
     {
         "id" : "text-0",
-        "task" : "Write a poem",
-        "answer" : "",
+        "task" : "What is the answer to all questions?",
         "kind" : "single"
     }
 
 
+The **answer** key is specified as a optional key within the question. That way it is
+possible to define validation functions, that relate the form of the answer to the 
+form of the question. E.g. a mapping task data structure should not be considered
+valid, if the answer contains keys that were not part of the question.
+
+In the example above, the answer is specified as a unicode field with 
+a length between 10 and 140 characters.
+
+During a test, only the answers can be exchanged. The answer is temporary
+merged with the task datastructure to check for formal compliance. If the
+data structure validates, the answer is saved in the answers column
+of the Audit table. (Suggested serialization):
+
+::
+
+    {
+        "text-0" : "42"
+        "geocap" : {
+            "Berlin" : "Germany",
+            "Paris" : "France"
+        }
+    }
+
+The corresponding REST API entry points would be (example with curl):
+
+::
+
+    $ curl -XGET localhost:8000/api/v2/audits/1/answers
+    $ curl -XGET localhost:8000/api/v2/audits/1/answers/geocap
+
+As an example, we want to add the above answers to the system via curl:
+
+::
+
+    $ curl -XPUT -H 'Content-Type: application/json' \
+        http://localhost:8000/api/v2/audits/1/answers/geocap \
+        -d '{"Berlin" : "Germany", "Paris" : "France"}'
+
+    $ curl -XPUT -H 'Content-Type: application/json' \
+        http://localhost:8000/api/v2/audits/1/answers/text-0 \
+        -d '42'
+
+Every interaction with the answers subsystem is intercepted to 
+ensure some rules:
+
+* modify answers only when the audits status is *started* (once the time for the exam is over, this gets set to finished by the client)
+* answers conform to specification
+* log everything
+
+At the end, the answers field of the Audit table contains a dictionary, that
+contains one key for every task attempted.
+
 Pools
 -----
 
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
-quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
-consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
-proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Pools are mainly a collection of tasks. The schema for a pool is as follows:
+
+::
+
+    pool = Schema({
+        required('id'): all(unicode, length(min=2, max=36)),
+        required('tasks'): unique([any(
+            cloze,
+            mapping,
+            multiple_choice,
+            single,
+            text,
+        )]),
+    })
+
+Pools have an unicode ID, which is also part of the URL.
+
+::
+
+    $ curl localhost:5000/api/v2/pools/econ101
+    $ curl localhost:5000/api/v2/pools/econ201
+
+Each pool is versioned in the background. When an *exam* is
+created, it is a version of the pool, that is referenced, not the
+pool directly. This way it is possible to keep all revisions
+of pools in the system, which is important, because one might want
+to evolve a question pool while retaining historical records for 
+the exams already performed. It is possible to access previous
+versions of a pool via API:
+
+::
+
+    $ curl localhost:5000/api/v2/pools/econ101/versions
+
+This also provides data to perform quality assurance (QA)
+since it is traceable who edit which question when and optionally
+why (through a comment field).
 
 Exams
 -----
 
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
-quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
-consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
-proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Exams are pools, that made public for examination.
 
 Audits
 ------
 
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
-quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
-consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
-proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Answers
--------
-
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
-quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
-consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
-proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
+Audits combine exams and users. This is where all the
+answers are stored.

tests/test_validators.py

         """
         valid_files = [
             "documents/cloze0.json",
+            "documents/cloze3.json",
         ]
         invalid_files = [
             ("documents/cloze1.json", InvalidList),
             ("documents/cloze2.json", InvalidList),
-            ("documents/cloze3.json", InvalidList),
             ("documents/cloze4.json", InvalidList),
             ("documents/empty.json", ValueError),
         ]