puppet-courseware-manager 0.5.0

data/lib/courseware.rb

@@ -0,0 +1,165 @@
+class Courseware
+  require 'courseware/cache'
+  require 'courseware/composer'
+  require 'courseware/generator'
+  require 'courseware/manager'
+  require 'courseware/printer'
+  require 'courseware/repository'
+  require 'courseware/utils'
+
+  def initialize(config, configfile)
+    @config     = config
+    @configfile = configfile
+    @cache      = Courseware::Cache.new(config)
+    @generator  = Courseware::Generator.new(config)
+    @composer   = Courseware::Composer.new(config)
+
+    if Courseware::Repository.repository?
+      @repository = Courseware::Repository.new(config)
+      @manager    = Courseware::Manager.new(config, @repository)
+    else
+      require 'courseware/dummy'
+      @repository = Courseware::Dummy.new
+      @manager    = Courseware::Dummy.new
+      $logger.debug "Running outside a valid git repository."
+    end
+  end
+
+  def options(opts)
+    raise ArgumentError, "One or two arguments expected, not #{opts.inspect}" unless opts.size.between?(1,2)
+    if opts.include? :section
+      section = opts[:section]
+      setting, value = opts.reject {|key, value| key == :section }.first
+      @config[section][setting] = value
+    else
+      setting, value = opts.first
+      @config[setting] = value
+    end
+  end
+
+  def print(subject)
+    $logger.debug "Printing #{subject}"
+
+    #TODO: This should not be duplicated!
+    opts = {
+      :course  => @manager.coursename,
+      :prefix  => @manager.prefix,
+      :version => @repository.current(@manager.prefix),
+      :variant => Courseware.choose_variant,
+    }
+    Courseware::Printer.new(@config, opts) do |printer|
+      subject.each do |item|
+        case item
+        when :handouts
+          printer.handouts
+
+        when :exercises
+          printer.exercises
+
+        when :solutions
+          printer.solutions
+
+        when :guide
+          printer.guide
+
+        else
+          $logger.error "The #{item} document type does not exist."
+        end
+      end
+    end
+  end
+
+  def wordcount(subject)
+    @manager.wordcount(subject)
+  end
+
+  def generate(subject)
+    $logger.debug "Generating #{subject}"
+    if subject.first == :skeleton
+      subject.shift
+      subject.each do |course|
+        @generator.skeleton course.to_s
+      end
+    else
+      subject.each do |item|
+        case item
+        when :config
+          @generator.saveconfig @configfile
+
+        when :styles
+          course = @manager.coursename
+          prefix = @manager.prefix
+          @generator.styles(course, @repository.current(prefix))
+
+        when :links
+          @generator.links
+
+        when :metadata
+          @generator.metadata
+
+        when :rakefile
+          @generator.rakefile
+
+        when :shared
+          @generator.shared
+
+        else
+          $logger.error "I don't know how to generate #{item}!"
+        end
+      end
+    end
+
+  end
+
+  def validate(subject)
+    $logger.debug "Validating #{subject}"
+    subject.each do |item|
+      case item
+      when :obsolete
+        @manager.obsolete
+
+      when :missing
+        @manager.missing
+
+      when :lint
+        @manager.lint
+
+      else
+        $logger.error "I don't know how to do that yet!"
+      end
+    end
+
+    $logger.warn "Found #{@manager.errors} errors and #{@manager.warnings} warnings."
+    exit @manager.errors + @manager.warnings
+  end
+
+  def release(subject)
+    case subject
+
+    when :major, :minor, :point
+      $logger.debug "Creating a #{subject} release."
+      @manager.release subject
+
+    when :notes
+      $logger.debug "Generating release notes."
+      @manager.releasenotes
+
+    else
+      $logger.error "I don't know how to do that yet!"
+    end
+  end
+
+  def compose(subject)
+    @composer.build(subject)
+  end
+
+  def package(subject)
+    @composer.package(subject)
+  end
+
+  def debug
+    require 'pry'
+    binding.pry
+  end
+
+end

data/lib/courseware/cache.rb

@@ -0,0 +1,35 @@
+require 'fileutils'
+class Courseware::Cache
+
+  def initialize(config)
+    @config = config
+
+    clone
+    update
+  end
+
+  def clone
+    templates = File.join(@config[:cachedir], 'templates')
+
+    FileUtils.mkdir_p(@config[:cachedir]) unless File.exists? @config[:cachedir]
+    system('git', 'clone', @config[:templates], templates) unless File.exists? templates
+  end
+
+  def update
+    $logger.debug "Updating template cache..."
+    git('templates', 'pull', '--quiet', 'origin', 'master')
+    git('templates', 'reset', '--quiet', '--hard', 'HEAD')
+  end
+
+  def clear
+    FileUtils.rm_rf @config[:cachedir]
+  end
+
+private
+  def git(repo, *args)
+    worktree = File.join(@config[:cachedir], repo)
+    gitdir   = File.join(worktree, '.git')
+    system('git', '--git-dir', gitdir, '--work-tree', worktree, *args)
+  end
+
+end

data/lib/courseware/composer.rb

@@ -0,0 +1,135 @@
+class Courseware::Composer
+  def initialize(config, repository=nil)
+    @config     = config
+    @repository = repository || Courseware::Repository.new(config)
+
+    if File.exists?(@config[:presfile])
+      @showoff    = JSON.parse(File.read(@config[:presfile]))
+      @coursename = @showoff['name']
+      @prefix     = @showoff['name'].gsub(' ', '_')
+      @sections   = @showoff['sections']
+    end
+  end
+
+  def build(subject)
+    courselevel!
+
+    if subject.nil?
+      display_tags
+      raise "Please re-run this task with a list of tags to include."
+    end
+
+    subject.each do |tag|
+      key = "tag:#{tag}"
+      @showoff['sections'].each do |section|
+        raise 'All sections must be represented as Hashes to customize.' unless section.is_a? Hash
+
+        if section.include? key
+          raise "A section in showoff.json refers to #{section[key]}, which does not exist." unless File.exist? section[key]
+          section['include'] = section[key]
+        end
+      end
+    end
+
+    # normalize the output and trim unused tags
+    @showoff['sections'].each do |section|
+      section.select! { |k,v| k == 'include' }
+    end
+    @showoff['sections'].reject! { |section| section.empty? }
+
+    name = Courseware.question('What would you like to call this variant?', 'custom').gsub(/\W+/, '_')
+    desc = Courseware.question("Enter a customized description if you'd like:")
+
+    @showoff['description'] = desc if desc
+
+    File.write("#{name}.json", JSON.pretty_generate(@showoff))
+    puts "Run your presentation with `showoff serve -f #{name}.json` or `rake present`"
+  end
+
+  def package(subject)
+    courselevel!
+    on_release!
+    pristine!
+
+    subject ||= Courseware.choose_variant
+    subject   = subject.to_s
+    content   = JSON.parse(File.read(subject))
+    variant   = File.basename(subject, '.json')
+    current   = @repository.current(@coursename)
+
+    if variant == 'showoff'
+      variant = @prefix
+      output  = @prefix
+    else
+      output  = "#{@prefix}-#{variant}"
+    end
+
+    FileUtils.rm_rf "build/#{variant}"
+    FileUtils.mkdir_p "build/#{variant}"
+    FileUtils.cp subject, "build/#{variant}/showoff.json"
+
+    content['sections'].each do |section|
+      path  = section['include']
+      next if path.nil?
+
+      dir   = File.dirname path
+      FileUtils.mkdir_p "build/#{variant}/#{dir}"
+      FileUtils.cp path, "build/#{variant}/#{path}"
+
+      files = JSON.parse(File.read(path))
+      files.each do |file|
+        FileUtils.cp "#{dir}/#{file}", "build/#{variant}/#{dir}/#{file}"
+      end
+    end
+
+    # support is special
+    FileUtils.cp_r '../_support', "build/#{variant}/_support"
+    FileUtils.rm_f "build/#{variant}/_support/*.pem"
+    FileUtils.rm_f "build/#{variant}/_support/*.pub"
+    FileUtils.rm_f "build/#{variant}/_support/aws_credentials"
+
+    # duplicate from cwd to build/variant everything not already copied
+    Dir.glob('*').each do |thing|
+      next if thing == 'build'
+      next if File.extname(thing) == '.json'
+      next if File.exist? "build/#{variant}/#{thing}"
+      FileUtils.ln_s "../../#{thing}", "build/#{variant}/#{thing}"
+    end
+
+    system("tar -C build --dereference -czf build/#{output}-#{current}.tar.gz  #{variant}")
+    if Courseware.confirm("Would you like to clean up the output build directory?")
+      FileUtils.rm_rf "build/#{variant}"
+    end
+
+  end
+
+private
+  def display_tags
+    courselevel!
+
+    raise "This course has no tags to choose from." unless @showoff['tags']
+
+    puts
+    puts 'Available tags:'
+    @showoff['tags'].each do |tag, desc|
+      printf " * %-10s: %s\n", tag, desc
+    end
+    puts
+  end
+
+  def courselevel!
+    raise 'This task must be run from within a course directory' unless @repository.courselevel?
+  end
+
+  def pristine!
+    raise 'Your working directory has local modifications or untracked files' unless @repository.clean?
+  end
+
+  def on_release!
+    count = @repository.outstanding_commits(@prefix)
+    unless count == 0
+      raise "There have been #{count} commits since release. Either make a release or check out a tagged release."
+    end
+  end
+
+end

data/lib/courseware/dummy.rb

@@ -0,0 +1,5 @@
+class Courseware::Dummy
+  def method_missing(meth, *args, &block)
+    raise "Cannot call #{meth} without a working courseware repository"
+  end
+end

data/lib/courseware/generator.rb

@@ -0,0 +1,91 @@
+require 'erb'
+require 'json'
+require 'yaml'
+require 'fileutils'
+class Courseware::Generator
+
+  def initialize(config)
+    @config = config
+  end
+
+  def saveconfig(configfile)
+    $logger.info "Saving configuration to #{configfile}"
+    File.write(configfile, @config.to_yaml)
+  end
+
+  def skeleton(dest)
+    source = File.join(@config[:cachedir], 'templates', 'skeleton')
+    FileUtils.cp_r(source, dest)
+
+    Dir.chdir(dest) do
+      course = metadata()
+      styles(course, '0.0.1')
+
+      default = Courseware::Repository.repository? ? 'P' : 'S'
+      case Courseware.question('Should this be a (S)tandalone course or share assets with a (P)arent repository?', default)
+      when 's','S'
+        shared
+        $logger.warn "Don't forget to create the GitHub repository for your new course following the EDU standard."
+      else
+        links
+        $logger.warn "Don't forget to add, commit, & push this new course directory to the repository."
+      end
+    end
+  end
+
+  def shared
+    source = File.join(@config[:cachedir], 'templates', 'shared')
+    FileUtils.cp_r(source, '.')
+  end
+
+  def rakefile
+    raise 'Update the toplevel Rakefile instead.' if File.symlink? 'Rakefile'
+    source = File.join(@config[:cachedir], 'templates', 'Rakefile')
+    FileUtils.cp(source, 'Rakefile')
+  end
+
+  def styles(course=nil, version=nil)
+    File.open(@config[:stylesheet], 'w') do |f|
+      $logger.info "Updating stylesheet for #{course} version #{version}."
+      template = File.join(@config[:cachedir], 'templates', 'showoff.css.erb')
+      f.write ERB.new(File.read(template), nil, '-').result(binding)
+    end
+  end
+
+  def links
+    filename = File.join(@config[:cachedir], 'templates', 'links.json')
+    JSON.parse(File.read(filename)).each do |file, target|
+      $logger.info "Linking #{file} -> #{target}"
+      FileUtils.rm_rf(file) if File.exists?(file)
+      FileUtils.ln_sf(target, file)
+    end
+  end
+
+  def metadata
+    location = File.basename Dir.pwd
+    if File.exists?(@config[:presfile])
+      metadata    = JSON.parse(File.read(@config[:presfile]))
+      coursename  = metadata['name']
+      description = metadata['description']
+      component   = metadata['issues'].match(/components=(\d*)/)[1]
+    else
+      template    = File.join(@config[:cachedir], 'templates', 'showoff.json')
+      metadata    = JSON.parse(File.read(template))
+      coursename  = location.capitalize
+      description = nil
+      component   = nil
+    end
+    coursename  = Courseware.question('Choose a short name for this course:', coursename)
+    description = Courseware.question('Please enter a description of the course:', description)
+    component   = Courseware.get_component(component)
+
+    metadata['name']        = coursename
+    metadata['description'] = description
+    metadata['edit']        = "https://github.com/puppetlabs/#{@config[:github][:repository]}/edit/qa/review/#{coursename}/#{location}/"
+    metadata['issues']      = "http://tickets.puppetlabs.com/secure/CreateIssueDetails!init.jspa?pid=10302&issuetype=1&components=#{component}&priority=6&summary="
+
+    $logger.info "Updating presentation file #{@config[:presfile]}"
+    File.write(@config[:presfile], JSON.pretty_generate(metadata))
+    coursename
+  end
+end

data/lib/courseware/help.rb

@@ -0,0 +1,108 @@
+class Courseware
+  def self.help
+    IO.popen("less", "w") do |less|
+      less.puts <<-EOF.gsub(/^ {6}/, '')
+                             Courseware Manager
+
+        SYNOPSIS
+          courseware [-c CONFIG] [-d] <verb> [subject] [subject] ...
+
+        DESCRIPTION
+          Manage the development lifecycle of Puppet courseware. This tool is not
+          required for presenting the material or for contributing minor updates.
+
+          The following verbs are recognized:
+
+          * print
+              Render course material as PDF files. This verb accepts one or more of the
+              following arguments, where the default is all.
+
+              Arguments (optional):
+                 handouts: Generate handout notes
+                exercises: Generate the lab exercise manual
+                solutions: Generate the solution guide
+                    guide: Generate the instructor guide
+
+          * watermark
+              Render watermarked PDF files. Accepts same arguements as the `print` verb.
+
+          * generate or update
+              Build new or update certain kinds of configuration. By default, this will
+              update the stylesheet.
+
+              Arguments (optional):
+                skeleton <name>: Build a new course directory named <name> and generate
+                                 required metadata for a Showoff presentation.
+
+                         config: Write current configuration to a `courseware.yaml` file.
+
+                         styles: Generate or update the stylesheet for the current version.
+
+                          links: Ensure that all required symlinks are in place.
+
+                       metadata: Interactively generate or update the `showoff.json` file.
+
+          * validate
+              Runs validation checks on the presentation. Defaults to running all the checks.
+
+              Validators:
+                  obsolete: Lists all unreferenced images and slides. This reference checks
+                            all slides and all CSS stylesheets. Case sensitive.
+
+                   missing: Lists all slides that are missing. Note that this does not check
+                            for missing image files yet. Case sensitive.
+
+                      lint: Runs a markdown linter on each slide file, using our own style
+                            definition.
+
+          * release [type]
+              Orchestrate a courseware release. Defaults to `point`.
+
+              All instructors are expected to deliver the most current point release, except
+              in extraordinary cases. We follow Semver, as closely as it can be adapted to
+              classroom usage. Instructors can trust that updates with high potential to cause
+              classroom disruptions will never make it into a point release.
+
+                                       http://semver.org
+
+              Release types:
+                      major: This is a major release with "breaking" changes, such as a major
+                             product update, or significant classroom workflow changes. This
+                             is not necessarily tied to product releases. Instructors should
+                             expect to spend significant time studying the new material thoroughly.
+
+                      minor: This indicates a significant change in content. Instructors
+                             should take extra time to review updates in minor releases.
+                             The release cadence is roughly once a quarter, give or take.
+
+                      point: Release early and release often. Changes made in the regular
+                             maintenance cycle will typically fit into this category.
+
+                      notes: Display release notes since last release and copy to clipboard.
+
+          * wordcount [type]
+              Display a simple wordcount of one or more content types.
+
+              Arguments (optional):
+                 handouts: Counts words in the student handout guide
+                exercises: Counts words in the lab exercise manual
+                solutions: Counts words in the solution guide
+
+          * compose [comma,separated,list,of,tags]
+              Generates a variant of the complete course, using tags defined in `showoff.json`.
+              The practical effect of this action is to generate a new presentation `.json` file,
+              which can be displayed directly by passing the `-f` flag to Showoff, or by choosing
+              a variant in the classroom `rake present` task.
+
+          * package [variant.json]
+              Package up a standalone form of a given variant of the presentation. You can pass
+              in a `variant.json` file, or choose from a menu. Tarballs will be saved into the
+              `build` directory and you can optionally retain the full working directory.
+
+          * help
+              You're looking at it.
+      EOF
+    end
+  end
+end
+