swirlypy is a Python package, meaning that its directory must be located somewhere in your Python path. For individuals with sane directory structures, this likely means temporarily adding the path to the directory above swirlypy's to your $PYTHONPATH. Alternatively, you could add a symlink from an existing Python directory. Eventually, we should be able to install swirlypy as a package and avoid this issue, but for the moment this is the workaround.

Swirlypy courses are distributed as tar archives (compressed or not) with a particular directory structure. They are required to have a course.yaml file, which describes the course in general. In addition, they must contain a lessons directory, with lesson files (see below).

The course.yaml file must be present in the root of the course, and contain the following fields: course (course title), lessonnames (list of human-readable lesson names), and author (human readable author name or names). It may also contain: description (explanatory text), organization (name of the course's sponsoring organization), version (a string, usually of numbers), and published (a timestamp in YAML format). An example is available here.

Lessons are YAML files contained in the lessons/ subdirectory. Their filenames are "sluggified," meaning that all non-ascii characters are replaced by dashes, and all ascii characters are lowercased. For example, a lesson called "Basics in Statistics" will be in a file named basics-in-statistics.yaml.

Each lesson is, itself, simply a list (what YAML calls a sequence) of questions. Fields at the root of lessons are not case sensitive, and an example lesson can be seen here.

Questions are, under the hood, all descended from a particular Python class. As such, they share certain properties, including the way they are parsed from YAML. Fields at the root are not case sensitive, and they are used as keyword arguments to construct Questions matching the listed category. For example, a Question of the "text" category will construct a TextQuestion.

The exact fields required by each question are determined by the type of question, but they at least require Category and Output. All of the questions in the standard library can be found here.

Furthermore, new questions can be defined within courses by placing them within a questions subdirectory, the same as with the standard library.

The swirlytool application that comes with Swirlypy is capable of packaging a course by using the create subcommand. This produces a Swirlypy course file, which is just a gzipped tar file with a particular format.