Examples of generating Canvas "quizzes" using Markdown

This repo gives several examples of Geoffrey Poore's text2qti to generate Canvas quizzes using Markdown.

The advantages of this approach are:

• You can get Canvas' intrusive UI out of your way
• Your questions are now plain text, meaning that you can version control them using GitHub, bitbucket, etc..
• You can collaborate on questions just as you would for regular source code hosted on GitHub or bitbucket.
• You can use GitHub/bitbucket releases to create "version numbers" for each year.
• You can finally write questions with random data and have the answers validated on the fly. Here, we can use python to generate questions and the answers. Thus, there should only be one point of failure, which is the code to generate the answers. This approach lets you generate dozens or hundreds of permutations of a single question!
• You can use Python to generate graphics for the questions.
• For many faculty and students, we can leverage skills we've already developed elsewhere: Python programming, content generation via markdown, and using version control software are daily activities for many of us.

The disadvantages are:

• You need to learn markdown. Fortunately, that is relatively rather easy. In fact, Rstudio users, etc., will already know the basics here.
• Knowledge of LaTeX and Python add considerable value, but some people may be unfamiliar with one or both.

General comments

• Please read the README file for text2qti, which is here
• The README is missing a key point, which is that the code fence probably needs to say {.python3 .run} for most people most of the time.
• You need a text editor to edit questions. It doesn't matter which one, but you need to be editing in plain text. (Not .doc/docx, not .rtf!)
• It is a good time to think about adding copyright information to all of your Canvas questions. At UCI, we have a serious problem with our course material being remixed and resold back to students by a company. I am adding explicit copyright info to each and every question. (A good text editor helps to automate this!)
• If you generate graphics with commercial software, then you'll need to export to png or jpeg. See below for alternatives.
• Always check the formatting of your work! One way is to do a "dummy" upload to Canvas. (Pretty fast to do.) You can also unzip the QTI zip file and inspect the images manually.
• If you make images with commercial tools, do not store them in the same folder as your markdown files! The reason is that the messy build outputs (see below) mean that you may end up with a clutter of jpg files that you made in Illustrator and jpg ouput from Python scripts, making an rm -f *.jpg cleanup step a bad idea.
• The quizzes are built using pandoc to render any mathematics. If you include LaTeX in quiz answers and then edit them in Canvas, the questions get "mangled". A better solution is to follow guidelines re: LaTeX in the text2qti README concerning LaTeX.

Python dependencies

The Python dependencies are listed in reuirements.txt. Install them via:

pip3 install -r requirements.txt

Or, if you don't clone this repo:

pip3 install text2qti numpy pandas

If you use conda (or brew), feel free to install pandas and numpy using those tools.

Other dependencies

• LaTeX. For macOS users, install MacTex.
• ImageMagick
• pandoc

From the above list, only pandoc is truly required. The others are used for specific example questions:

• LaTeX is used to render tables as pdf. (One could also generate graphics directly using tikz.)
• The convert tool from ImageMagick takes the pdf output from LaTeX and generates a png file, which is used in the question.

How to install these

Linux

They are available via your distro's package manager

macOS/Windows

I recommend conda. Windows 10 users can probably use a Linux installation of conda into the bash/Ubuntu subsystem.

Gotchas

• On some systems, you may get an error when trying to use convert to manipulate pdf files. This error is a safety check because of the potential security issues involving executing malicious code. This SO post has advice on how to undo this check. (I have to do all of this on each of my Linux machines.)

Building the quizzes

For each markdown file, execute

text2qti --run-code-blocks --pandoc-mathml foo.md

Note that foo.md is a placeholder. Your actual quiz will have a name like Lecture1.md and the quiz names provided here are visible in quizzes/.

One a Unix-like system (Linux, macOS, or Windows 10 with the bash subsystem), the Makefile will build the examples in quizzes:

cd quizzes
make

Gotchas

• The builds are messy. A lot of extra files end up in quizzes/. I need to see if this can be fixed.
• You cannot do parallel builds! (make -j 4, etc.). The system runs through an intermediate file with a fixed name.

Image generation with Inkscape and krita

Inkscape and krita are two open source programs for creating images. The former is a vector graphics package, works through svg files and is well-suited for technical diagrams. The latter is a very capable drawing program. As with their Adobe counterparts, both have fairly steep learning curves. One very nice feature is that both provide command line interfaces for exporting to standard graphics formats. The following show the terminal commands and the corresponding Makefile rules for converting svg and krita files to png.

For inkscape svg, the terminal command is

inkscape --export-png image.png -D image.svg

The corresponding make rule is:

%.png: %.svg
    inkscape --export-png $@ -D $<

For krita, we have:

krita --export image.kra --export-filename image.png

%.png: %.kra
    krita --export $@ --export-filename $<

Both programs have more options to control the output dpi, etc., and convert can be used for resizing, etc..

The advantage of this approach is that you only ever need to store your inkscape and krita files. (Both formats are not very git-friendly, however.)

Uploading to Canvas

Settings -> Upload Course Content and probably create a new question bank. Remember to "bookmark" it if it is uploaded to a "sandbox" course. You'll also need to burn sage or perform a sacrifice of some sort.

Advanced example of coupled questions

Canvas does not support a question group from which two questions are pulled where they both use the same data, or the answer of the second builds on the answer to the first. A workaround is given in quizzes/quiztemplate.md, where we change the work flow:

• quizzes/quiztemplate.md is now an "upstream" quiz template, from which we will generate some number of quizzes.
• This quiz template contains a Python block that generates two "paired" questions based on random data using Python.
• If we copy this template to quiz1.md through quizN.md and process each with text2qti, we have effectively generated random paired questions from a "group".

My approach to building these metaprogramming quizzes again uses a Makefile. However, I use a potentially non-portable trick to use the bash shell for file pattern expansion. Thus, I've written a separate Makefile, which you can execute as:

cd quizzes
make -f Makefile.quiztemplate