doc.go

// trainctl is an opinionated tool for managing training materials.
//
// trainctl allows you to mix multiple training modules in various combinations,
// creating courses from the modules.
//
// Modules are self-contained topics.  A module might represent a single presentation
// at a conference, or a single topic of a multi-topic course.
//
// Courses are a collection of modules assembled in a specific order to create a logical
// progression of learning material.
//
// Modules are stored in a base folder.  We'll refer to the base folder as $MODULEDIR
// Each module consists of a present slide file, a json manifest and a subdirectory
// bearing the same name as the module, containing
// the slide's assets, in `images` and `includes` directories.
//
// Source code intended for student consumption is stored in `$MODULEDIR/src/modulename`.
// The expectation is that each course will be a self-contained $GOPATH, so the import
// names of each module are simply the modulename.
//
// trainctl is a tool that allows you to manage modules individually, with the end goal of
// assembling them into a course which will be presented/taught.
//
// trainctl uses a configuration file stored at $HOME/.trainctl.yaml which can be created using
// `trainctl createconfig`.  It is not required, but will pre-fill many of the fields needed for
// every command, so it is strongly recommended.
//
// Usage:
//  trainctl [command]
//
// Available Commands:
//  assemble     Assemble modules into a course
//  create       Create a new module skeleton
//  createconfig Create a config file in your home directory
//  info         Get info about a module
//  package      package a course into a downloadable zip file
//  related      Add related material to a module
//  remove       Remove a new module skeleton
//  search       Search modules by metadata
//
// Start with `trainctl createconfig` to create a configuration file in your home directory.
// Edit this file with real values representing your configuration.
// The $MODULEDIR should be a source controlled directory.
// The $COURSEDIR can be any directory, source control not required (or recommended).
//
// To create a module run:
//  trainctl create --name mymodule
//
// This creates the following files and directories:
//  $MODULEDIR/mymodule.slide
//  $MODULEDIR/mymodule.json
//  $MODULEDIR/mymodule/images
//  $MODULEDIR/mymodule/includes
// These files represent the module's slide and assets required to present the slide.
//
// Additionally, the following directories are created:
//  $MODULEDIR/src/mymodule/demos
//  $MODULEDIR/src/mymodule/exercises
//  $MODULEDIR/src/mymodule/solutions
// These directories are intended to be a self-contained $GOPATH for the module, and eventually
// the courses that contain this module.
//
// Create one or more modules this way, then assemble them into a course with the
// `trainctl assemble` command like this:
//  trainctl assemble --course "My Class" --modules module1,module2,module4 --shortname myclass
// The assemble command will create a course in the $COURSEDIR folder with the name `myclass` in the
// above example.  The following files are created
//  $COURSEDIR/mymodule.json
//  $COURSEDIR/mymodule.slide
// The .json file is a manifest of the course's contents.
// The .slide file is a symlink to your module's .slide file, with the addition of a numbered
// prefix, establishing the order the modules you specified in the `assemble` command.
// The module directory is symlinked to:
//  $COURSEDIR/mymodule
// with the subdirectories intact so the slide's assets will still appear on the slide.
//
// The `package` sub-command takes a course from your $COURSEDIR and creates a zipfile from
// it, which has the effect of de-referencing the symlinks.  The benefit if this approach is that
// your courses will always contain the latest up-to-date changes from the modules included in them,
// up to the point where you memorialize them immediately before presenting your class.
// Repackaging the course in the future will update the zipfile with files in the symlinked
// modules that may have changed since last giving the course.
//
//  trainctl package --shortname mycourse
// This creates a zipfile called mycourse.zip with the contents of the `mycourse` included.
// This is the course material you will use to present, or give to your students.
// It also includes a Vagrantfile and a supporting bootstrap bash script which provides
// a fully operational Go development with the course's /src shared into the Vagrant container.
//
// The `search` and `info` sub-commands give you information about modules in your
// $MODULEDIR so that you can choose which modules to assemble into a course.
package main