DocOnce offers some special features that can greatly aid development of effective teaching material:
Need to notify, warn, summarize, ask a question, give a tip,
dive into less important details, or really emphasize a result?
DocOnce features special
notice, warning, summary,
and question boxes called admonitions. These can be typeset in a
variety of versions, depending on the output format
(check out doconce format --help and the many options with admon
in the name).
Put a box around something important:
pyoptpro code environment
To illustrate program flow, you can step through code
(as in a debugger, just more illustrative) using the
pyoptpro code environment. Here is an example:
In HTML and Sphinx format this code can be stepped through in the browser, while in LaTeX one gets a link to a web page with this functionality.
pyscpro code environment
The SageMathCell server
enables live Python code in web documents. Using the
pyscpro code environment, Python code can be embedded in a
for interactive computing:
We can even plot:
HTML and Sphinx output has such interactive Sage Cells, while other output formats can just show the code.
DocOnce supports exercise subsections, which are subsections with some extra tagging for exercises. Important features are:
There is also a quote environment (invisible box with larger margins).
We're programmers. Programmers are, in their hearts, architects, and the first thing they want to do when they get to a site is to bulldoze the place flat and build something grand. We're not excited by incremental renovation: tinkering, improving, planting flower beds.There's a subtle reason that programmers always want to throw away the code and start over. The reason is that they think the old code is a mess. And here is the interesting observation: they are probably wrong. The reason that they think the old code is a mess is because of a cardinal, fundamental law of programming: It's harder to read code than to write it. This is why code reuse is so hard. This is why everybody on your team has a different function they like to use for splitting strings into arrays of strings. They write their own function because it's easier and more fun than figuring out how the old function works.
Joel Spolsky, 2000
Question: Does DocOnce feature multiple-choice questions or quizzes?
Quite often we need mathematics and computer code in questions and answers.
Question: Compute the integral $$ \int_0^{2\pi} e^{-x}\sin^2 x\,dx $$ and report the formula in verbatim LaTeX code,
\[ \int_0^{2\pi} e^{-x}\sin^2 x\,dx = ... \]
>>> from sympy import *
>>> x = symbols('x')
>>> F = integrate(exp(-x)*sin(x)**2, (x, 0, 2*pi))
>>> F
-2*exp(-2*pi)/5 + 2/5
>>> latex(F)
'- \\frac{2}{5 e^{2 \\pi}} + \\frac{2}{5}'
so the answer is
\[ \int_0^{2\pi} e^{-x}\sin^2 x\,dx =
- \frac{2}{5 e^{2 \pi}} + \frac{2}{5} \]
\[ \int_0^{2\pi} e^{-x}\sin^2 x\,dx =
- \frac{3}{4 e^{2 \pi}} + \frac{3}{4} \]
\[ \int_0^{2\pi} e^{-x}\sin^2 x\,dx =
- {2\over5}{5 exp^{2 pi}} + \frac{2}{5} \]
The typesetting of a quiz depends on the output format.
One can output in plain HTML
and Sphinx formats,
hover over the choice and get a pop-up tooltip with the
right answer and an explanation (if defined).
The explanation can only show plain text, so it is empty if it
contains math or code blocks, or figures.
With HTML Bootstrap styles one can click on a symbol to open up
the answer and the explanation.
RunestoneInteractive books (Sphinx) offers a
button for the same purpose, but the explanation can only be
plain text so any math or code block makes the explanation empty.
LaTeX output can feature the choices only (no answer, no explanation:
--without_solutions --without_answers), the short answer only
(--without_solutions) or both the answer and all explanations
(the case in this demo).
Can you think of applications of the above mentioned features?