This is Python software to easily build GIFT -based question banks in Moodle. Other similar tools are available (you can search for Tools that create or process GIFTs in Moodle's GIFT page) but none of them fitted well my workflow. What I need is (the goals of gift-wrapper are):
- to write questions in plain text, and as many as I like in a single file
- to write latex formulas directly
- to easily/seamlessly include images
The most interesting point is probably the last one.
Python requirements are:
Now, if you want to make the most of the software you also need:
pip install gift-wrapper
should suffice.
If you rather clone this repository, (in order to, potentially, get the latest additions/modifications)
pip install pyyaml paramiko tqdm colorama
should install all the additional requirements. If you use Anaconda, the bash script make_conda_environment.sh will make a proper environment (named gift).
After that, you should be able to run the program.
The main program is wrap.py and you can check the available command-line options with
wrap.py -h
or
python wrap.py -h
if you did a manual installation and wrap.py doesn't have execution permissions.
If you don't pass any argument, parameters.yaml and bank.yaml files are expected. The former is a settings file whereas the latter is the actual input file in which you must write the questions.
The output will be a text file in GIFT format with the same name as the input (the file with the questions) but .gift.txt extension (thus, bank.gift.txt, by default). It seems that sometimes Moodle has troubles importing (recognizing) a text file if the extension is not .txt.
parameters.yaml is a YAML file intended to hold settings that you only need to specify once. Right now, it only contains parameters related to images hosting (needed to copy your images to a remote server). All the options are either self-explanatory or explained through comments. It should be fairly easy to tweak the included example for your own setup.
Questions are specified through another YAML file. The first parameter, pictures base directory, refers to the base directory that will be created in the remote host to accommodate your images (only meaningful if images are not embedded in the questions, i.e., if not passing -e). It is meant to separate different question banks (so that you can have, e.g., directories quiz 1 and quiz 2). The rest of the file is a list of categories, and inside each one there is a list of questions. Hopefully, the format is clear from either the name of the settings and/or its companion comments. You are probably better off taking a look at the provided example.
If you run the program inside the gift-wrapper directory as is, it will process the sample bank.yaml which includes a .tex, a .svg and some mathematical formulas, and will generate a bank.gift.txt file which you can import from Moodle (choosing the GIFT format when asked). If the parameters file (by default, parameters.yaml) is not found, images are embedded into the corresponding questions (tantamount to passing -e).
gift-wrapper has been designed to work with svg images. Then, in order to include any image in a question, two scenarios are contemplated:
- you already have an svg
- you have a TeX file that can be compiled with pdflatex
In any case, you just need to write the path to the file inside the text of the question (whether in the statement, the answer or the feedbak). If in the second scenario, i.e., you are including a TeX file, this will be compiled into a pdf with pdflatex, and then converted to an svg with pdf2svg. Hence, a svg file will be, in the end, available for every image.
Images (svgs) are either copied to a remote host (and properly linked in the output GIFT file), or directly embedded into their corresponding questions.
Characters allowed in a path (to either a .tex or a .svg) are:
- alphanumeric (A-Z, a-z, 0-9)
- underscore, '_', and dash, '-'
- '/' and '\' (path separators).
It seems (it has been reported) not every browser properly handles svg images (maybe other types too) embedded in a question as an URL. My experience so far is both Firefox and Chromium (at the time of writing this) work just fine.
Only if you want automatic conversion from .tex (passing through .pdf) to .svg, i.e., only if you embed a .tex somewhere.
Also, there is (probably) nothing special about pdf2svg and, in principle, you can use any command-line program that takes as arguments the input pdf and the output svg. However, I've only tested the program with pdf2svg since it's the one included in Gentoo Linux.
If a parameters file (e.g., parameters.yaml) is found, images are by default copied to the specified remote host (within a publicly visible directory) so that they can be accessed by Moodle. This is done automatically for every embedded image (svg or tex). For this to work, in the parameters.yaml file, within ssh either
- user and password, or
- user and path to a public key file
(but not both) should be specified.
You can inhibit this behavior and run the program locally (omitting the transferring of the images to a remote host) by using -l command line argument. This is especially meaningful if you don't have any embedded image in your questions (and hence nothing needs to be copied to a remote host).
Formulas inside $s are processed and, within them, these are the commands/symbols that have been tested so far
- greek letters
- subindexes
- calligraphic symbols, i.e., prefixed by
\cal - fractions with
\frac{}{} \underline\left(and\right)\left[and\right]\begin{bmatrix}and\end{bmatrix}- symbols
\sim,\approx
More things are probably OK, but I have not tested them yet.
Inside text, only commands \textit and \textbf are supported for the time being.
By default, wrap.py checks whether or not the formulas you wrote between $'s can actually be compiled. Right now this involves a call to pdflatex for every formula, meaning that it can significantly slow down the process. It can be disabled by passing --no-checks (or simply -n). It is probably a good idea to actually check the formulas every once in a while (e.g., every time you add a new one), though, since bad latex formulas will be (silently) imported by Moodle anyway, and not only will they be incorrectly rendered but they may also mess up subsequent content.
-
only numerical and multiple-choice questions are supported (notice that the GIFT format itself doesn't support every type of question available in Moodle)
-
the latex support is very basic
-
one is in for troubles if embedding remote URLs pointing to
.svgor.texfiles since the file part will, most likely, be parsed and replaced
If you are comfortable with Python and Jupyter notebooks, you might also be interested in py2gift.