Writing Trane Courses
Trane courses have the following directory structure:
course_root/
course_manifest.json
<LESSON_DIR>/
lesson_manifest.json
<EXERCISE_DIR>/
exercise_manifest.json
There can be multiple lessons in a course and multiple exercises in a lesson. In addition, there can be asset files (e.g. markdown files) anywhere in the course directory, but it's best to put each of them in the same directory as the manifest that refers to it.
So writing a course for Trane consists of generating the manifest files in this directory structure and placing any assets in the right paths. While this process is easy for small courses, it can quickly get out of hands if you are generating courses with a lot of exercises or if you are planning on creating a lot of courses.
For this reason, Trane provides utilities to help you write courses inside the course_builder
module in Trane. These utilities help you define the courses, lessons, and exercises as Rust code
and contain methods to generate all the files (including assets) while also performing several
sanity checks. While the decision of generating courses by writing Rust source files might seem
strange at first, it's actually a lot easier and less annoying than writing a course by hand.
Another advantage is that any breaking change to the manifest data structures in Trane will result
in a compile error, so you can be confident that your courses will work with a specific version of
Trane as long as the code compiles.
These utilities can be augmented to help you write more easily specific types of courses. For
example, inside the course_builder
module, there is a CirclesFifthCourse
struct that can be used
to generate courses that require a lesson for each key and which follow the order of the circles of
fifths, starting with the key of C and going clockwise and counterclockwise into each of the other
keys.
You can look at any of the official Trane courses for example of how courses are written.