====================================
Tutor's documentation for developers
====================================

Principles and objectives
=========================

No principles yet...

Style guidelines
----------------

No style yet...

User stories and specific goals
===============================

There are three main users of the ``tutor`` system:: the **students** who take 
the questions and exams, the **tutors**/teachers who apply these exams and the
question **creator** who creates and administer the questions database. It is 
common that the **tutor** plays a double role as also a **creator**, but ideally, 
she should be able to select questions from a public or institution's database.   

Each of these roles is addressed in a separate chapter and it is assumed that 
different people will fulfill each of these roles. The development roadmap 
ideally should be concentrated in implementing and improving the *user stories*
associated with each role. A *user story* is a simple description of a desired
functionality of the system from a **user's** point of view. It should not be a
technical description and technical decisions made for implementation of each
user story should not be described in these chapters. 
 
Each user story must follow the ``reST`` template bellow::

  (user story title) Randomized questions printing
  ------------------------------------------------
  
  (concise description) I want to print several randomized versions of a given 
  question template to check for bugs and inconsistencies.   
  
  :Status: implemented
  :Priority: medium
  :Comments: 
      (Document in a language tha is useful for the user) User can generate a 
      ``pdf`` file out of the question file ``question.qst`` with the command 
      ``tutor create pdf question.qst``. The `pdf`` file can be printed from 
      the installed ``pdf`` viewer. 
  :References: See implementation on :mod:`tutor.bin.create`
 
The ``:Priority:`` field can be any of ``low``, ``medium``, ``high`` or 
``critical``. Obviouslly, the developer should dedicate its time to implement
features for the non (or partially) implemented user stories based on their 
priority.

The ``:Status:`` field can be any of ``not implemented``, ``implemented`` or 
``partial (xx%)``. As a general rule, values above 33% should be assigned to 
working versions of an implementation with known (possibly critical) bugs and 
missing features. 

Ideally, user stories should be written in English. Portuguese is tolerated, 
but the sections and roles should keep their English names as in::  

  Imprimindo questões randomizadas
  --------------------------------
  
  Desejo imprimir várias versões aleatorizadas a partir de um modelo de questão
  para procuarar bugs e inconsistências.   
  
  :Status: implemented
  :Priority: medium
  :Comments: 
      O usuário pode gerar um ``pdf`` utilizando o comando 
      ``tutor create pdf question.qst``. Este arquivo `pdf`` pode depois ser 
      imporesso a partir do leitor de ``pdf`` instalado no sistema. 
  :References: Veja implementação em :mod:`tutor.bin.create`

Technical level of different users
----------------------------------

It is assumed that people in each user *role* have at least the following 
technical levels:

**Student**
	Non-skilled computer user. Can deal with printed versions of questions and 
	exams and has only very limited computer skills: can navigate in the web,
	read and send e-mails and view and print common file types. 
**Tutor**
	Basic Linux user. The tutor is a beginner Linux user. It has some 
	familiarity with the command line and man pages. The tutor may need to 
	configure additional services (such as a mail server) in order to deploy
	a fully function installation of ``py-tutor``. The tutor should also be
	able to understand text-based configuration files.  
**Creator**
	The creator is the most skilled user. It has all the previous skills plus
	knowledge of LaTeX and some programming language (preferably Python, but 
	other options such as Maple and Maxima are doable). The creator does not
	need to be familiar with the inner works of ``py-tutor`` such as the main
	developers.

As the system progresses, these requirements can (and should) be loosen, but
we shall never assume additional skills (e.g.: the student should never be 
required to use Linux).

Index of user stories
---------------------

User stories are herein categorized by role and implementation status.

.. toctree::
   :numbered:
   :maxdepth: 2

   user_stories/creator	   
   user_stories/tutor
   user_stories/student

Global Architechture
====================

Chaos.

Modules documentation
=====================

TODO: How modules are organized?

Schemas
-------
.. automodule:: tutor.schemas
   :members: