The program doconce must be run to interpret the quiz format, translate
it to LaTeX, HTML, or other formats, and produce the Python representation
of the collection of quizzes in a document. Let the name of the
document with quiz specifications and optional text be myquiz.do.txt.
Documents to play around with are pure_quiz.do.txt or
the present document.
A simple HTML rendering of quizzes is done by
Terminal> doconce format html myquiz
The result myquiz.html can be loaded into a browser.
A more sophisticated rendering is offered if a Bootstrap HTML style is adopted,
Terminal> doconce format html myquiz --html_style=bootstrap
Other variations of this class of styles are bootswatch, and
bootswatch_X, where X is the name of a Bootswatch style, e.g.,
journal.
The Bootstrap-based styles have a striking red color for inline computer
code, which can be avoided by giving the option --html_code_style=inherit
(see the documentation of DocOnce and Bootstrap for details and examples).
By default, there is a horizontal rule enclosing each quiz in the HTML format.
This can be turned off by the option --quiz_horizontal_rule=off.
By inserting !split before headings in a DocOnce document, one can run
Terminal> doconce split_html myquiz.html
to create a multi-page document with navigation arrows. Bootstrap styles
will also have a Contents pull-down menu to the right in the top bar.
Without the split_html command (and !split instructions in the document),
all quizzes will be in one HTML page.
The prefix before a question is Question: and before a choice is Choice X,
where X is a number. To set a different prefix, see the
--quiz_question_prefix and --quiz_choice_prefix commands
when running doconce format --help.
The standard command to produce a LaTeX document is
Terminal> doconce format pdflatex myquiz \
--without_answers --without_solutions \
--latex_code_style=pyg
If desired, the correct answer to each quiz can be included by omitting
--without_answers. Omitting --without_solutions will print
the right answers and the available explanations below the quiz.
The next step is to compile the document:
Terminal> pdflatex -shell-escape myquiz
to produce a PDF myquiz.pdf.
Here, we use the pyg (Pygments, LaTeX package minted) style
for code blocks, which requires the -shell-escape option when running
pdflatex.
A typical session for creating a Sphinx document is
Terminal> doconce format sphinx myquiz
Terminal> doconce split_rst myquiz
Terminal> doconce sphinx_dir dirname=sphinx theme=default myquiz
Terminal> python automake_sphinx.py
A disadvantage of Sphinx in a quiz context is that admonitions cannot contain quizzes. However, an advantage of Sphinx is that one can create RunestoneInteractive Sphinx books, which have nice browser support of quizzes. A RunestoneInteractive version is created by
Terminal> doconce format sphinx myquiz --runestone
Terminal> doconce split_rst myquiz
Terminal> doconce sphinx_dir dirname=sphinx theme=default myquiz
Terminal> python automake_sphinx.py --runestone