4. Module Authoring¶
OpenDSA modules are authored using
reStructuredText
(also known as ReST). The source files for these modules (which
can be found in OpenDSA/RST/source
) are compiled to HTML
(or, in theory, other formats – but we do not support that) by
Sphinx.
To create a “book”, you must invoke OpenDSA/tools/configure.py
,
being sure to specify a configuration file (sample of which can be
found in OpenDSA/config
.
Sample books can be compiled using OpenDSA/Makefile
.
If the python virtual environment is already active, a sample
command (run from the OpenDSA toplevel directory) looks like:
python tools/configure.py config/OpenDSA.json
.
A number of special directives have been created, which are documented in OpenDSA ReST Extensions.
Documentation for writing OpenDSA exercises using the Khan Academy infrastructure is in Using OpenDSA with Khan Academy infrastructure.
Documentation for writing pure JSAV-based proficiency exercises is in Using OpenDSA with Khan Academy infrastructure.
The best way to get a sense for how things work is to look at some existing modules.
4.1. Module Structure¶
Each module is basically a single ReST file.
The first thing that will normally appear is the
avmetadata
directive block.
Among other things, this will define the module within the
prerequisite structure, which is important when
generating a full textbook.
A big reason why we chose to use ReStructuredText for authoring is its
ability to pass raw HTML through, allowing us to embed dynamic content
(i.e., JavaScript) into our HTML pages while still having the
advantage of a markup language for authoring.
However, we don’t ever want to actually use the raw
directive in
our modules if we can avoid it.
At this point use of raw
should never be needed, as we have a
number of directives to use instead:
avembed
, inlineav
, odsalink
, and odsascript
.
Most exercises and visualizations are embedded into the module from
elsewhere using the avembed
directive, but small slideshows and
dynamically generated diagrams can be included directly using the
inlineav
directive.
Any CSS or JS code that is unique to a specific module page should be
maintained in separate files and included using odsalink
and
odsascript
directives, respectively.
Defining which modules will be used in a given book, which exercises are included for credit, and various other aspects of module use are defined with the Configuration system.
4.2. Math and Symbol Escapes¶
All equations within a module are created using LaTeX syntax embedded
in a :math:
inline directive.
This will be converted to appropriate math layout in the resulting
HTML file.
Note that due to various interactions between reStructuredText and
MathJax (which does the LaTeX conversion within an HTML page),
you have to use a double backslash for escaping the dollar sign
symbol, such as:
This costs \\$5.00.
4.3. Math and Code¶
One of the hardest things when writing modules is making sure
that all of the variables and expressions are marked up correctly.
In nearly all cases, any variable is either “mathy” or “codey”. Mathy
variables and expressions should use LaTeX markup embedded in a
:math:
directive.
“Codey” variables and expressions should be marked up as:
``my codey text``
All variables (and expressions) should always get their appropriate
typeface.
Avoid using physical markup such as italics or bold for such things,
we prefer to use logical markup (that is, math markup or code markup).
Sometimes it can be difficult to decide which is appropriate.
For example, you might have a function with a variable n
for the
array size.
When it comes time to discuss the analysis of the function, it is
probably going to be done in terms of \(n\), a quantity that
expresses the array size (as opposed to the function variable n
).
It can be a subtle point whether the variable or the quantity is
intended.
Having to typeset it (and so make a conscious decision) helps you to
think through what you are trying to convey.
4.4. Code Snippet Support¶
OpenDSA and JSAV provide an extensive framework for integrating code
snippets into your modules and visualizations.
JSAV provides support through the Pseudocode API for displaying and
manipulating your code snippets within an AV.
See the JSAV manual for details.
Within a module, code snippets are meant to be embedded from a
sourcecode file using the codeinclude
directive.
The default coding language(s) used by a textbook instance is
controlled by the code_lang
setting in the corresponding OpenDSA
configuration file.
The OpenDSA framework and configuration support makes it as easy as possible to be able to compile book instances with code snippets from your desired programming language(s), assuming that the code snippets have been provided by a content developer. The most important principle for managing code snippets is that they should be taken from working programs that can properly support testing of the code that you include into your modules.
All such sourcecode should appear in the SourceCode
directory
within OpenDSA, with each coding language having its own
subdirectory.
A given AV can have an associated .json
file that defines the
configuration for alternate coding languages, including such things as
the filename.
Note that in the .json
file, a given section of the code
block
should match the subdirectory name within the SourceCode
directory
for that language.
4.5. Creating Classroom Presentation Slides¶
OpenDSA uses hieroglyph, a Sphinx extension to build HTML slideshows to view in your browser.
The course notes infrastructures is similar to eTextBook creation, and uses
OpenDSA/Makefile
. The only difference is the -s
option for slides
when calling the configuration, for example python tools/configure.py -s config/OpenDSA.json
.
The Makefile will use the -s
option automatically if your JSON config’s
filename ends with the word ‘slides’ or ‘Slides’ (e.g. make TestSlides
will use config/TestSlides.json
and create class presentation slides).
4.6. Internationalization Support¶
OpenDSA supports a sophisticated internationalization framework that attempts to make it as easy as possible to support compiling textbook instances in various (natural) languages. The configuration system allows a book compiler to specify the language of choice, and the system will take module versions in the target language whenever available (the fallback language is English).
As a module author, your .rst
files will always appear in a
subdirectory of the RST
directory coded to the language that you
are writing for.
Like every other aspect of internationalization, we define these
subdirectories using the two-letter
ISO 639-1
language codes.
Thus, all English-language RST files appear in the RST/en
directory.