Package: qudb
Manage a database of questions and use it to generate assessments, e.g.
assignments, quizzes, and exams.qudbis a personal question bank for instructors. It allows you to:Manage your collection of questions for a given course, and assemble
various assessments out of them.Track how you are using your questions. Query your database forquestions,terms,assessments, orassessment types.Anassessment typerefers to a type of assessments that recur at
most once every term, such asquiz1,assignment2, andfinal. It
can be any arbitrary string identifying a type of assessment. Anassessmentis a specific occurrence of anassessment typein a
giventerm, and hence is identified by a pair of atermand anassessment type.Example queries:In which assessments has a given question been used?What questions make up a given assessment?What questions have been used in a given term?What questions have been used in final exams across all terms?Use a template to render an assessment document using its questions.Distinguish between essay questions (default) and multiple-choice
questions.Use arbitrary additional variables in your templates, so you can use
the same templates across courses by introducing, for example, an
additionalcourse namevariable.Getting StartedCreate a database:qm initBy default, this command creates a./qu.dbdatabase file. Use the-D(or--database) option to specify the database file
location.Add questions to assessments (an assessment is identified by atermand anassessment type):qm add --term 151 --assessment-type quiz1 questions/chapter1/whats-your-name.tex
qm add --term 151 --assessment-type quiz1 questions/chapter1/mcq/choose-a-month.texUse the-Q(or--questions-directory) option to specify where
to look for the question files. You can also specify a question’spoints(-p), whether it’s abonusquestion (-b), and itsorderin the assessment (-o) if you want to insert it somewhere
in the middle. Thepoints,bonus, andorderfields of a
question are per assessment, and can change from one assessment to
another.Generate an assessment:qm render --term 151 --assessment-type quiz1 --pdflatex quiz-template.texThe--pdflatexoption (or-P) assumes that your template is a
LaTeX file, requires thepdflatexprogram, and generates a PDF.
Without it, you get a rendered template.The--configoption (or-C) allows specifying additional
arbitrary template variables using anINI-style configuration
file.CommandsAlthough theinit,add, andrendercommands described above
are often enough, there are a few other commands that complement them.
Moreover, these three commands have a few options that control their
operation. Here are all the supported commands and their options.initusage: qm init [-h] [-D DATABASE]

Create a new database file as specified by the -D option. Defaults to ./qu.db.
If the database exists, do nothing

optional arguments:
  -h, --help            show this help message and exit
  -D DATABASE, --database DATABASE
                        SQLite database file pathlistusage: qm list [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] [-t TERM]
               [-y ASSESSMENT_TYPE] [-q QUESTION] [-m]
               {terms,assessment-types,assessments,questions}

List existing entities: terms, assessment-types, assessments, or questions

positional arguments:
  {terms,assessment-types,assessments,questions}
                        what to list

optional arguments:
  -h, --help            show this help message and exit
  -D DATABASE, --database DATABASE
                        SQLite database file path
  -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY
                        where to look for questions. Question paths stored in
                        the database are relative to this path
  -t TERM, --term TERM  academic semester code, e.g. 142
  -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE
                        examples: major1, assignment2, quiz3
  -q QUESTION, --question QUESTION
                        include results related to this question only
  -m, --mcq             whether to retrieve MCQs or non-MCQs. cannot retrieve
                        both at onceaddusage: qm add [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] -t TERM -y
              ASSESSMENT_TYPE [-b] [-p POINTS] [-o ORDER] [-d DATE]
              question

Add a question file to a given assessment, specified by a term and an
assessment-type (required options)

positional arguments:
  question              path to the question file

optional arguments:
  -h, --help            show this help message and exit
  -D DATABASE, --database DATABASE
                        SQLite database file path
  -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY
                        where to look for questions. Question paths stored in
                        the database are relative to this path
  -t TERM, --term TERM  academic semester (3 digits)
  -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE
                        examples: major1, assignment2, quiz3
  -b, --bonus           this is a bonus question
  -p POINTS, --points POINTS
                        default points for question
  -o ORDER, --order ORDER
                        the order of the question in this assessment; defaults
                        to last
  -d DATE, --date DATE  assessment date; format YYYY-MM-DDupdateusage: qm update [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] -t TERM -y
                 ASSESSMENT_TYPE [-b] [-p POINTS] [-o ORDER] [-d DATE]
                 question

Update an existing assessment or question

positional arguments:
  question              path to the question file

optional arguments:
  -h, --help            show this help message and exit
  -D DATABASE, --database DATABASE
                        SQLite database file path
  -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY
                        where to look for questions. Question paths stored in
                        the database are relative to this path
  -t TERM, --term TERM  academic semester (3 digits)
  -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE
                        examples: major1, assignment2, quiz3
  -b, --bonus           this is a bonus question
  -p POINTS, --points POINTS
                        default points for question
  -o ORDER, --order ORDER
                        the order of the question in this assessment; defaults
                        to last
  -d DATE, --date DATE  assessment date; format YYYY-MM-DDremove(orrm)usage: qm remove [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] -t TERM -y
                 ASSESSMENT_TYPE

Remove a question from an assessment

optional arguments:
  -h, --help            show this help message and exit
  -D DATABASE, --database DATABASE
                        SQLite database file path
  -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY
                        where to look for questions. Question paths stored in
                        the database are relative to this path
  -t TERM, --term TERM  academic semester (3 digits)
  -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE
                        examples: major1, assignment2, quiz3renderusage: qm render [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] -t TERM -y
                 ASSESSMENT_TYPE [-O OUTPUT_DIRECTORY] [-C CONFIG] [-P]
                 [-l MATERIAL]
                 template

Generate assessment documents using the specified template. Two documents are
generated: TERM-ASSESSMENT_TYPE.tex and TERM-ASSESSMENT_TYPE-solution.tex,
with the template variable "solution" set to False and True, respectively.
Templates are rendered using the Jinja2 template engine, with the following
delimiters: <% block %><% endblock %>, << variable >>, <# comment #>

positional arguments:
  template              path to the jinja2 template file

optional arguments:
  -h, --help            show this help message and exit
  -D DATABASE, --database DATABASE
                        SQLite database file path
  -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY
                        where to look for questions. Question paths stored in
                        the database are relative to this path
  -t TERM, --term TERM  academic semester (3 digits)
  -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE
                        examples: major1, assignment2, quiz3
  -O OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
                        the directory in which the rendered files will be
                        saved
  -C CONFIG, --config CONFIG
                        ini-style configuration file defining additional
                        template variables. (Use section [templates])
  -P, --pdflatex        process rendered file with pdflatex (4 runs)
  -l MATERIAL, --material MATERIAL
                        specify the material to which this assessment
                        pertains. Available to the template in the "material"
                        variableexportusage: qm export [-h] [-D DATABASE] [--overwrite] file

Export the database to a YAML file (does not include the contents of question
files)

positional arguments:
  file                  YAML file to export to

optional arguments:
  -h, --help            show this help message and exit
  -D DATABASE, --database DATABASE
                        SQLite database file path
  --overwrite           overwrite the file if it already existsimportusage: qm import [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] [-u] file

Import data from a YAML file into the database. To learn the YAML schema,
export a minimal database, or see the README.md file

positional arguments:
  file                  YAML file to import

optional arguments:
  -h, --help            show this help message and exit
  -D DATABASE, --database DATABASE
                        SQLite database file path
  -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY
                        where to look for questions. Question paths stored in
                        the database are relative to this path
  -u, --update          ignore existing, identical questionsExample valid YAML data:'142':# term codequiz1:# assessment type: creates an assessment in the parent term-file:questions/chapter1/q1.tex# each item in the list is a question-file:questions/chapter2/q5.tex# file: the file containing the question textdate:2015-02-14# a date in any question sets the assessment date-bonus:true# set this question as a bonus questionfile:questions/chapter2/arm-gcc.texpoints:20# how many points are assigned to this question in this assessmentquiz2:# another assessment in the same term-date:2015-03-07file:questions/chapter3/q2.tex-file:questions/chapter3/q3.texpoints:20'151':# another termquiz1:# this is a different assessment from the previous quiz1,# because it belongs to a different term-file:questions/chapter6/q3.texTemplatesTemplates use theJinja2template
language. Therendercommand requires the--termand--assessment-typeoptions to specify anassessment. The following
assessment variables are available in the template:term: the term of the specified assessment.title: assessment title, based on its type. For example,quiz1results in the titleQuiz 1, andmajor1results in the titleMajor Exam 1.date: assessment date, as specified using the--dateoption
of theaddandupdatecommands.solution(Boolean): whether we are rendering the solution.qs: an ordered list of question objects belonging to this
assessment. Includes the following fields:question.file: path of the question file.points: question points.bonus(Boolean): whether this is a bonus question.mcqs: an ordered list of multiple-choice question objects,
otherwise similar toqs.questions_relpath: the relative path from the current directory
to the questions as specified by the-Q/--questions-directoryoption.Variables can be referenced in the template by enclosing them in<<and>>. For example,<< title >>renders the assessment’stitle.To use some basic logic in the template, use template statements, such
asforloops orifconditionals, by enclosing them in<%and%>. For example:<% for q in qs %>
    <% if q.bonus %>
        \bonusquestion
    <% else %>
        \question
    <% endif %>
    <% if q.points %>[<< q.points >>]<% endif %>
    \input{<< questions_relpath >>/<< q.question.file >>}
<% endfor %>For information about the template language, consult theJinja2
Template Designer
Documentation.AssumptionsOneSQLitedatabase file per course.Questions and templates are text files.Multiple choice questions have an/mcq/component in their paths.Each question file includes the question’s solution in a way that
allows it to be easily listed or omitted in a template.Although it is not required,qudbworks well with theexamLaTeX package. For example,
each question file can wrap the solution in asolutionenvironment, then the template can easily include or exclude the
solution based on the value of thesolutiontemplate variable as
follows:<% if solution %>
\printanswers
<% endif %>LicenseBSD (2-clause).