OpenDSA System Documentation

4. Compiling Book Instances: OpenDSA Configuration

«  3. Instructor’s Tools   ::   Contents   ::   5. Module Authoring  »

4. Compiling Book Instances: OpenDSA Configuration

4.1. Overview

A given OpenDSA eTextbook is called a “book instance”. The contents of a book instance is defined by a configuration file, the detailed syntax for which is defined in this section. In practice, it is easiest to start by copying an existing configuration file, and then changing it to fit your needs. Configuration files are JSON files, normally stored in OpenDSA/config. From the top level of an OpenDSA repository, you can compile a book instance (given the existance of a configuration file named config/foo.json) by issuing this command:

python tools/configure.py config/foo.json

Separate from book instances is the concept of a “course instance”. Depending on the course software (typically an LMS such as Canvas or Moodle) that you are using, you will likely need to compile a special instance of a given OpenDSA book instance for each course that intends to use it. OpenDSA course instances are managed by a separate configuration file. The convention is that if the book configuration file is foo.json, then the corresponding course configuration file(s) will be in in fooXX_LMSconf.json where XX allows you to distinguish between the various courses that use the book.

Details about how to set up a course is in Configuring Courses below.

4.2. Motivation for the Configuration System

  • Allows content to be environment-independent
    • Configuration file contains all environment-dependent settings such as paths and target URLs
    • Example: If developers want to point their front-end code at different backend systems, they simply make the change in their own config file. They can share all OpenDSA content, but when they build the book, it will be built using their personalized settings
  • Allows easy replication
    • Collects all settings and preferences required to configure an instance of OpenDSA in a single, portable file that can be easily shared among instructors.
    • Once a configuration has been created, instructors can make identical copies without going through the configuration process
  • Allows fine grain control
    • Existing configuration files provide sensible defaults, but allow instructors to control aspects such as how many points a specific exercise is worth or whether it is required for module proficiency
  • Configuration files will eventually be generated by a GUI front-end, but for now we create them by hand (tedious, and the motivation for a GUI tool is rapidly moving to the front burner).

4.3. Branches

We are temporarily supporting two versions of OpenDSA, as represented by the branches “master” and “NewKA”. The “master” branch currently is intended for generating books as used in Canvas, while “NewKA” supports “old style” book instances directly accessible via HTML files. Only the master branch uses the server configuration files described at the end of this section. There are a few fields of the configuration process that appear in NewKA book configuration files, that are moved to the server configuration file in the master branch.

4.4. Configuration Process

A comment at the beginning of configure.py gives some information information about how the script works. Generally, those who want to compile a book instance do not need to worry about those details.

Note: The OpenDSA root directory must be web-accessible as there are many supplemental directories and files (AV/, Exercises/, lib/, SourceCode/, etc) which must be referenced. These files are identical for all books and not copying them reduces the footprint of each book.

4.4.1. Module and Exercise Removal

  • Only the modules listed in the configuration file will be included. To remove a module from the book, simply remove the module object from the configuration file.
  • To remove a section from a module, set the “showsection” attribute to false. Exercises are normally the sole contents of some section. Note that Exercises that do not appear in the configuration file will still be included in the book using the default configuration options. During compilation, a list will be printed of any exercises which were encountered in the modules but not present in the configuration file.

4.4.2. Book Name

The name of the configuration file will often be used in some way by the LMS that manages the course. For example, the name of the configuration file might be the Course ID in the LMS.

4.5. Future Features

  • GUI editor/interface for editing configuration files.
  • Merge the “master” and “NewKA” branches, with support for both Canvas-style and “HTML page” book instances, controlled by command-line parameters on the configuration script.

4.6. Format

OpenDSA configuration files are stored using JSON. Here are the field definitions. All are required unless otherwise specified. Note: The fields “title”, “exercise_server”, “logging_server”, and “score_server” appear in the book configuration file only for the NewKA branch. These fields are moved to the server configuration file in the master branch.

  • title - The title of the OpenDSA textbook.

  • build_dir - (optional) The directory where the configured book directory will be created, defaults to ‘Books’ if omitted

    • A new directory, named after the configuration file, will be created at this location and serve as the output directory for the configuration process. Files required to compile the book will be copied / written to the output directory, including modified version of the source RST files
      • Example: Assume “build_dir”: “Books” and the name of the configuration file used is “CS3114.json”, the output directory would be “~OpenDSA/Books/CS3114/”
    • The compiled textbook will appear in [build_dir]/[book name]/html
    • This directory must be web accessible
  • code_dir (optional) - Specifies a directory that contains another directory as specified by code_lang (see below). Defaults to SourceCode if omitted.

    • Ex: Using "code_dir": "SourceCode/", and assuming that the defined language directory is Python then the configuration process would look for example Python source code in ~OpenDSA/SourceCode/Python.
  • code_lang - A dictionary where each key is the name of a programming language (supported by Pygments and matching a directory name in code_dir), and each value is a dictionary of language options. Language options are:

    • ext for a list of file extensions.
    • label for the text that will be displayed at the header of the code snippet tab.
    • lang for the name of the programming language (supported by Pygments).

    The order in which the languages and extensions are provided determines their order of precedence in cases where only one display code is to be selected.

    • Example:

      "code_lang": {
         "C++": {"ext": ["cpp","h"],"label":"C++","lang":"C++"}
         "Java": {"ext":["java"], "label":"Java", "lang":"java"},
         "Processing": {"ext":["pde"], "label":"Processing","lang":"java"}
      }
    • In this example, assuming that code_dir is SourceCode/, the system would search for .cpp files, followed by .h files in ~OpenDSA/SourceCode/C++/, then .java files in ~OpenDSA/SourceCode/Java/, and finally .pde files in ~OpenDSA/SourceCode/Processing/.

    • There is not actually a need for the “code” language files to be a real programming language. For example, it is plausible to use a “programming language” called Pseudo with file suffix .txt. However, Pygments might not do well with colorizing the result.

  • tabbed_codeinc (optional) - A boolean that controls whether or not code is displayed in a tabbed interface. If true, it will display the specified code in each of the languages specified in code_lang (if the code exists) in a tabbed container. If false, it will display the code in a single language (the first language for which the code exists with the order of precedence determined by the order specified in code_lang). Defaults to true if omitted.

  • lang (optional) - Specifies the native language of the book using the official ISO 639-1 or 639-2 standard abbreviation, defaults to en if omitted. This is used to control where RST source files are located, within ~OpenDSA/RST/[lang]. Any RST files not found in the indicated subdirectory will then be located in ~OpenDSA/RST/en.

  • module_origin - The protocol and domain where the module files are hosted

    • Used by embedded exercises as the target of HTML5 post messages which send information to the parent (module) page
    • Ex: “module_origin”: “http://algoviz.org”,
  • av_root_dir - (optional) Allows the user to change the default location where the AV/ directory can be found. Defaults to ~OpenDSA/ if omitted

    • This can point to another location on the same machine that hosts the module files (as long as it is web-accessible), or it can point to a remote location (this feature not supported yet).
    • Note: This should not point to the AV/ directory itself, but instead should be the directory containing the AV/ directory (to avoid breaking the relative paths in the RST files).
    • If this attribute references a remote location, ‘av_origin’ must be present and the value must be a prefix of the remote location.
    • Ex: “av_root_dir”: “/home/algoviz/OpenDSA/test/”,
    • Ex: “av_root_dir”: “http://algoviz.org/OpenDSA/”, // This directory contains an AV/ directory
  • av_origin - (normally optional, but required if av_root_dir is defined) The protocol and domain where the AV files are hosted, defaults to match module_origin if omitted.

    • Used on module pages to allow HTML5 post messages from this origin, allows embedded AVs to communicate with the parent module page.
    • Ex: “av_origin”: “http://algoviz.org”,
  • glob_mod_options - (optional) An object containing options to be applied to every module in the book. Can be overridden by module-specific options.

  • glob_exer_options - (optional) An object containing options to be applied to every exercise in the book. Can be used to control the behavior of the exercise. Can be overridden by exercise-specific options.

  • exercises_root_dir - (optional) Allows the user to change the default location where the Exercises/ directory will be found. Defaults to ~OpenDSA/ if omitted.

    • This can point to another location on the same machine that hosts the module files (as long as it is web-accessible) or it can point to a remote location (not fully supported yet).
    • Note: This should not point to the Exercises/ directory itself, but rather the directory containing the Exercises/ directory (to avoid breaking the relative paths in the RST files)
    • If this attribute references a remote location, exercise_origin must be present and the value must be a prefix of the remote location
    • If this attribute is not present, ~OpenDSA/ will be used as the default.
    • Ex: “exercises_root_dir”: “/home/algoviz/OpenDSA/test/”,
    • Ex: “exercises_root_dir”: “http://algoviz.org/OpenDSA/”, // This directory contains an Exercises/ directory
  • exercise_origin - (optional, unless exercises_root_dir is defined) The protocol and domain where the Exercises files are hosted, defaults to match module_origin if omitted.

    • Used on module pages to allow HTML5 post messages from this origin, allows embedded exercises to communicate with the parent module page.
    • Ex: “exercise_origin”: “http://algoviz.org”,
  • exercise_server - (optional) The protocol and domain (and port number, if different than the protocol default) of the exercise server that provides verification for the programming exercises. Defaults to an empty string (exercise server disabled) if omitted.

  • logging_server - (optional) The protocol and domain (and port number, if different than the protocol default) of the logging server that supports interaction data collection. Defaults to an empty string (logging server disabled) if omitted.

  • score_server - (optional) The protocol and domain (and port number, if different than the protocol default) of the score server that supports centralized user score collection. Defaults to an empty string (score server disabled) if omitted.

  • build_JSAV - (optional) A boolean controlling whether or not the JSAV library should be rebuilt whenever the book is compiled. Defaults to false if omitted.

    • This value should normally set to false for development.
    • Instructors may wish to set this to true for production environments when configuration is run infrequently and JSAV is likely to have changed since the last time configuration occurred.
  • build_cmap - (optional) A boolean controlling wether or not the glossary terms concept map should be diplayed. Defaults to false.

  • allow_anonymous_credit - (optional) A boolean controlling whether credit for exercises completed anonymously (without logging in) will be transferred to the next user to log in. Defaults to true if omitted. Note: Obsolete in the context of LMS support for scoring, since the LMS will require login for access to the OpenDSA content.

  • req_full_ss - (optional) A boolean controlling whether students must view every step of a slideshow in order to obtain credit. Defaults to true if omitted.

  • start_chap_num - (optional) Specifies at which number to start numbering chapters. Defaults to 0 if omitted.

  • suppress_todo - (optional) A boolean controlling whether or not TODO directives are removed from the RST source files. Defaults to false if omitted.

    • Note: When changing from false to true, you must run make clean or otherwise remove previously compiled book files so as to completely remove any references to ToDo.
  • tag - (optional) A string containing a semi-colon delimited list of tags. This directs Sphinx to include material from RST only directives with the matching tag(s). This is useful for relatively fine-grain control over whether material will be included in a book instance. For example, if you want to have multiple paragraphs each with a programming language-dependent discussion, with only the appropriate paragraph for the language being used for this book instance actually appearing to the reader. Any material within an only block that does not have a matching tag in the config file will be left out.

  • assumes - (optional) A string containing a semi-colon delimited list of topics that the book assumes students are familiar with. This allows for control over warnings about missing prerequisite modules during the build process.

  • chapters - A hierarchy of chapters, modules, and sections. This makes up the vast majority of most configuration files.

    • Each key in “chapters” represents a chapter name. A module object is one whose key matches the name of an RST file in the ~OpenDSA/RST/[lang]/ directory, and which contains the key “sections”.
    • hidden - This is an optional field to signal the preprocessor to not display the content of the chapter in the TOC. The configuration script will add the new directive odsatoctree. The flagged chapter entries in the TOC will be of class hide-from-toc, and will be removed by a CSS rule in odsaMOD.css file.
    • Modules
      • The key relating to each module object must correspond to a path to an RST file found in ~OpenDSA/RST/[lang]/.
      • long_name - A long form, human-readable name used to identify the module.
      • dispModComp - (optional) A flag that, if set to “true”, will force the “Module Complete” message to appear even if the module contains no required exercises. If set to “false”, the “Module Complete” message will not appear, even if the module DOES contain required exercises.
      • mod_options - (optional) overrides glob_mod_options, which allows modules to be configured independently from one another. Options that should be stored in JSAV_OPTIONS should be prepended with JOP- and options that should be stored in JSAV_EXERCISE_OPTIONS should be prepended with JXOP-. (This can be used to override the defaults set in odsaUtils.js). All other options will be made directly available to modules in the form of a parameters object created automatically by the client-side framework (specifically, when parseURLParams() is called in odsaUtils.js).
      • sections - A collection of section objects that define the sections that make up a module. The sections object should contain keys that match the titles of the corresponding sections in the RST file. Some modules contain no sections, in which case this field should be included with an empty list.
        • To remove the section completely, provide the field showsection and set it to false.
        • All options provided within a section object (with the exception of remove) are appended to the directive, please see the Extensions section for a list of supported arguments.
        • A section may contain a single exercise descriptor, as follows.
          • exer_options - (optional) An object containing exercise-specific configuration options for JSAV. Can be used to override the options set using glob_exer_options. Options that should be stored in JSAV_OPTIONS should be prepended with JOP- and options that should be stored in JSAV_EXERCISE_OPTIONS should be prepended with JXOP-. (This allows overriding the defaults set in odsaUtils.js.) All other options will be made directly available to exercises in the form of a parameters object created automatically by the client-side framework (specifically when parseURLParams() is called in odsaUtils.js).
          • long_name - (optional) A long form, human-readable name used to identify the exercise. Defaults to short exercise name if omitted.
          • points - (optional) The number of points the exercise is worth. Defaults to 0 if omitted.
          • required - (optional) Whether the exercise is required for module proficiency. Defaults to false if omitted.
          • threshold - (optional) The percentage that a user needs to score on the exercise to obtain proficiency. Defaults to 100% (1 on a 0-1 scale) if omitted.
        • JSAV-based diagrams do not need to be listed
      • codeinclude (optional) - An object that maps the path from a codeinclude to a specific language that should be used for that code. This allows control of individual code snippets, overriding the code_lang field.
        • Ex: "codeinclude": {"Sorting/Mergesort": "C++"} would set C++ as the language for the codeinclude “Sorting/Mergesort” within the current module.

4.7. Configuring Exercises

The most important concern when configuring proficiency exercises is the scoring option to be used. JSAV-based proficiency exercises have a number of possible grading methods:

  • atend: Scores are only shown at the end of the exercise.
  • continuous:undo: Mistakes are undone, the student will lose that point but have to repeat the step.
  • continuous:fix: On a mistake, the step is corrected, the student loses that point, and then is ready to attempt the next step. This mode requires that the exercise have the capability to fix the step. If it does not, this grading mode will default to continuous:undo.

All proficiency exercises can be controlled through URL parameters. What the configuration file actualy does by setting exer_options is specify what should be in the URL parameters that are sent to the exercise by the OpenDSA module page. Here is an example for configuring an exercise:

"shellsortPRO": {
  "long_name": "Shellsort Proficiency Exercise",
  "required": true,
  "points": 2.0,
  "threshold": 0.9,
  "exer_options": {
    "JXOP-feedback": "continuous",
    "JXOP-fixmode": "fix"
  }
},

This configuration will affect the configuration of an entity called shellsortPRO (presumeably defined by an ..avembed directive in the corresponding OpenDSA module). It is scored (as indicated by setting the required field to true), and is worth 2.0 points of credit once the user reaches “proficiency”. To reach “proficiency” requires correctly achieving 90% of the possible steps on some attempt at the exercise (as defined by threshold). The exercise is instructed to use the continuous:fix mode of scoring.

In addition to the standard JXOP-feedback and JXOP-fixmode parameters, a given AV or exercise might have ad hoc parameter settings that it can accept via URL parameter. Examples might be algorithm variations or initial data input values. Those would have to be defined by the exercise itself. These (along with the standard grading options) can also have defaults defined in the .json file associated with the AV or exercise, which might help to document the available options. Any such ad hoc parameter defaults can be over-ridden in the exer_options setting in the configuration file.

4.8. Configuring Courses

4.8.1. Rationale

Separate from book configuration files (which define the contents of a book, scoring information, and configurations for various exercise), a given book instance will typically be accessed in the context of a particular LMS, which will require various permissions in order to operate correctly. The compilation process separates the compilation of book files from the interactions needed to set up the book’s use at a specific instance of the LMS. Book instances are in fact compiled to the specification necessary for that specific LMS to access it, meaning that book instances cannot be shared across LMS’s, or by different instances of the same LMS (say, two instances of Canvas), or even by two course instances on the same installation of a given LMS. The reason is that the internal cross links between the various parts of the book instance are often defined in the context of a specific course instance within the LMS.

A specific course instance on a specific LMS installation is defined by a course configuration file. By convention, the file name will end with _LMSconf.json. A template for course configuration can be found here.

Since course configuration files routinely store sensitive information such as account passwords and access keys, they are not stored in the OpenDSA repository. This documentation along with the template file should provide enough information for you to successfully define the contents of a configuration file.

A set of make targets are available in the OpenDSA Makefile. From the top level of an OpenDSA repository, you can compile the HTML files for a book instance by typing

make <courseinstance>

So, if there existed a book with a configuration file named config/foo.json, you would type

make foo

This much (locally creating the HTML files) uses just the book configuration file.

If you want to bind a book instance to a particular course instance on a given LMS, that requires both compiling the book and pushing information about it to the LMS. Pushing information to the LMS is where the course configuration file comes into play. After you set up the proper course configuration file in config/foo_LMSconf.json, you can type:

make foo opts="-c True"

to push the necessary book data to your LMS. Alternatively, there may already be a Makefile target named fooLMS that has this same effect by typing

make fooLMS

4.8.2. Format

To understand the following description of configuration file data fields, it helps to understand that running a “course” using OpenDSA requires communication between several entities, including:

  • An LTI tool provider. This is the site that hosts the book, which is probably where the book is being compiled.
  • An LMS. The LMS has to grant access to the LTI provider in order for it to send scores and define the modules.
  • The OpenDSA scoring, logging, and programming exercise server(s). Communications with these are required in order to handle crucial aspects of exercise scoring.

Here are the fields in the configuration file.

  • title - The title for the course intance.
  • odsa_username - A viable user account on the course instance (OpenDSA) scoring server.
  • odsa_password - The corresponding password on the course instance (OpenDSA) scoring server.
  • target_LMS - LMS name. We currently support ‘canvas’. Other LMSs like moodle and Desire2Learn will be supported in the future.
  • LMS_url - The URL for the LMS.
  • course_code - The name used at the LMS to identify the course. In Canvas, this is the identfier given when creating the course.
  • access_token - This is normally issued by the LMS to allow an LTI tool provider to communicate with it. In Canvas, go to your account-level settings. Near the bottom of the page you should see a big blue button that reads “New Access Token”. Click this, then copy the string that is generated, and paste it into this field in the configuration file. If you (the creator of the config file and the one who compiles the book) are not the course instructor (with access to the LMS), then the course instructor will need to provide this access token.
  • LTI_consumer_key - The key required by the LTI tool provider.
  • LTI_secret - Effectively the password for the LTI tool provider.
  • module_origin - The protocol and domain where the module files are hosted
    • Used by embedded exercises as the target of HTML5 post messages which send information to the parent (module) page
    • Ex: “module_origin”: “http://algoviz.org”,
  • exercise_server - The protocol and domain (and port number, if different than the protocol default) of the exercise server that provides verification for the programming exercises. Defaults to an empty string (exercise server disabled) if omitted.
  • logging_server - The protocol and domain (and port number, if different than the protocol default) of the logging server that supports interaction data collection. Defaults to an empty string (logging server disabled) if omitted.
  • score_server - The protocol and domain (and port number, if different than the protocol default) of the score server that supports centralized user score collection. Defaults to an empty string (score server disabled) if omitted.

«  3. Instructor’s Tools   ::   Contents   ::   5. Module Authoring  »