README

   1 Break learning up into small task-based tests for focused study.
   2
   3 Tests can be defined with prerequites so a student wishing to learn a
   4 higher level task, but out of their depth with the task itself, can
   5 easily go back through the basics.  By default, only the leaf
   6 questions (i.e. questions that are not dependencies of other question)
   7 are asked.  If the user gets one wrong, we push the question back on
   8 the stack (so they can try again later), and also push all of that
   9 questions direct dependencies onto the stack (so they can get the
  10 background they need to answer the question they got wrong).
  11
  12 There are a number of example quizzes available in the ``quizzes``
  13 directory.  The example quizzes mostly focus on teaching software
  14 development tasks (POSIX shell utilities, Git version control, …), but
  15 any material that can be presented in a textual prompt/response/check
  16 process should be fairly easy to develop.  The quiz files are written
  17 in JSON, and the format should be fairly easy to understand after
  18 looking through the examples.
  19
  20 The quiz framework and answer processing are independent of the user
  21 interface used to present the prompts and collect responses.
  22 Currently only a ``input()`` based command line interface exists, but
  23 other interfaces (e.g. a web server for browser-based interaction)
  24 should be fairly straightforward.
  25
  26 Here's an example typescript for one of the sample quizzes::
  27
  28   $ ./pq.py quizzes/monty-python.json
  29   What is your favourite color?
  30   ? blue
  31   correct
  32
  33   What is the capital of Assyria?
  34   ? Hmm…
  35   incorrect
  36
  37   What is your quest?
  38   ? To seek the Holy Grail
  39   correct
  40
  41   What is the capital of Assyria?
  42   ? ?
  43
  44   What is the capital of Assyria?
  45   Sir Robin didn't know it either
  46   ? I don't know that
  47   correct
  48
  49   results:
  50   question:     What is your quest?
  51   answers: 1/1 (1.00)
  52     you answered: To seek the Holy Grail
  53        which was: correct
  54
  55   question:     What is your favourite color?
  56   answers: 1/1 (1.00)
  57     you answered: blue
  58        which was: correct
  59
  60   question:     What is the capital of Assyria?
  61   answers: 1/2 (0.50)
  62     you answered: Hmm…
  63        which was: incorrect
  64     you answered: I don't know that
  65        which was: correct
  66
  67   answered 3 of 4 questions
  68   of the answered questions, 3 (1.00) were answered correctly
  69
  70 The unanswered question (“What is your name?”) wasn't asked because
  71 the user successfully answered the question that depended on it (“What
  72 is your quest?”).
  73
  74 Quizzer requires Python ≥ 3.2.  If Pygments is installed, the command
  75 line prompt will be colored.
  76
  77 Types of questions:
  78
  79 * ``Question``: An open ended question with a single correct answer
  80   (or accepting any answer).
  81 * ``NormalizedStringQuestion``: Like ``Question``, but normalizes the
  82   given answer with ``string.strip().lower()`` before comparing with
  83   the correct answer.
  84 * ``ChoiceQuestion``: A question with multiple valid answers.  With
  85   ``display_choices``, this is a standard multiple choice question.
  86   With ``multiple_answers``, it is “chose all that apply”.
  87 * ``ScriptQuestion``: A question which checks scripting answers by
  88   running the given answer and correct answer in temporary
  89   directories.  There are hooks for setting up and tearing down the
  90   temporary directories, and we judge success by comparing the output
  91   of the teardown phase (and optionally the output of the answer
  92   phase).  You can optionally set a timeout to catch answers that
  93   hang, although this requires Python ≥ 3.3.  There is no sandboxing
  94   (other than working in a scratch directory), so it's not a good idea
  95   to serve questions like this on a public interface (stick to
  96   ``cli``).