puppet-courseware-manager 0.5.0

data/lib/courseware/manager.rb

@@ -0,0 +1,129 @@
+require 'courseware/printer'
+require 'courseware/repository'
+require 'io/console'
+require 'nokogiri'
+
+class Courseware::Manager
+  require 'courseware/manager/validators'
+
+  attr_reader :coursename, :prefix, :warnings, :errors
+
+  def initialize(config, repository=nil, generator=nil, printer=nil)
+    @config     = config
+    @repository = repository || Courseware::Repository.new(config)
+    @generator  = generator  || Courseware::Generator.new(config)
+    @warnings   = 0
+    @errors     = 0
+
+    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 releasenotes
+    courselevel!
+    master!
+    clean!
+
+    @repository.update
+    current = @repository.current(@coursename)
+    version = Courseware.increment(current)
+    tag     = "#{@coursename}-#{current}"
+
+    notes = @repository.releasenotes(tag, version)
+
+    # print to screen
+    puts notes
+
+    # and copy if on OS X
+    begin
+      IO.popen('pbcopy', 'w') { |f| f.puts notes }
+      puts
+      puts "{{ Copied to clipboard }}"
+    rescue
+    end
+  end
+
+  def release(type)
+    courselevel!
+    master!
+    clean!
+
+    @repository.update
+    version = Courseware.increment(@repository.current(@coursename), type)
+    Courseware.bailout?("Building a release for #{@coursename} version #{version}.")
+
+    raise "Release notes not updated for #{version}" unless Courseware.grep(version, 'Release-Notes.md')
+
+    Courseware.dialog('Last Repository Commit', @repository.last_commit)
+    Courseware.bailout?('Abort now if the commit message displayed is not what you expected.')
+    build_pdfs(version)
+    point_of_no_return
+    Courseware.bailout?('Please inspect the generated PDF files and abort if corrections must be made.') do
+      @repository.discard(@config[:stylesheet])
+    end
+
+    @repository.commit(@config[:stylesheet], "Updating for #{@coursename} release #{version}")
+    @repository.tag("#{@prefix}-#{version}", "Releasing #{@coursename} version #{version}")
+    puts "Release shipped. Please upload PDF files to printer and break out the bubbly."
+  end
+
+  def wordcount(subject)
+    $logger.debug "Counting words for #{subject}"
+    opts = print_opts(@repository.current(prefix))
+    puts "Words longer than a single character:"
+    Courseware::Printer.new(@config, opts) do |printer|
+      subject.each do |item|
+        printer.generate_html(item)
+        doc   = Nokogiri::HTML(File.read('static/index.html'))
+        count = doc.css('body').text.split.select {|w| w.size > 1 }.count
+
+        puts "  * #{item}: #{count}"
+
+        FileUtils.rm_rf('static')
+      end
+    end
+  end
+
+private
+  def toplevel!
+    raise 'This task must be run from the repository root.' unless @repository.toplevel?
+  end
+
+  def courselevel!
+    raise 'This task must be run from within a course directory' unless @repository.courselevel?
+  end
+
+  def master!
+    raise 'You should release from the master branch' unless @repository.on_branch? 'master'
+  end
+
+  def clean!
+    raise 'Your working directory has local modifications' unless @repository.clean?
+  end
+
+  def point_of_no_return
+    Courseware.dialog('Point of No Return', 'Proceeding past this point will result in permanent repository changes.')
+  end
+
+  def build_pdfs(version)
+    @generator.styles(@coursename, version)
+    Courseware::Printer.new(@config, print_opts(version)) do |printer|
+      printer.print
+    end
+    system("open #{@config[:output]} >/dev/null 2>&1")
+  end
+
+  def print_opts(version)
+    {
+      :course  => @coursename,
+      :prefix  => @prefix,
+      :version => version,
+      :variant => Courseware.choose_variant,
+    }
+  end
+
+end

data/lib/courseware/manager/validators.rb

@@ -0,0 +1,72 @@
+class Courseware::Manager
+
+  def obsolete
+    puts "Obsolete images:"
+    Dir.glob('**/_images/*') do |file|
+      next if File.symlink? file
+      next if File.directory? file
+      next if system("grep #{file} *.css */*.md >/dev/null 2>&1")
+
+      puts "  * #{file}"
+      @warnings += 1
+    end
+
+    puts "Obsolete slides:"
+    Dir.glob('**/*.md') do |file|
+      next if File.symlink? file
+      next if File.directory? file
+      next if file =~ /^_.*$|^[^\/]*$/
+      next if @sections.include? file
+
+      puts "  * #{file}"
+      @warnings += 1
+    end
+  end
+
+  def missing
+    sections = @sections.dup
+
+    # This seems backwards, but we do it this way to get a case sensitive match
+    Dir.glob('**/*.md') do |file|
+      sections.delete(file)
+    end
+    return if sections.empty?
+
+    puts "Missing slides:"
+    sections.each do |slide|
+      puts "  * #{slide}"
+      @errors += 1
+    end
+  end
+
+  def lint
+    puts "Checking Markdown style:"
+    style  = File.join(@config[:cachedir], 'templates', 'markdown_style.rb')
+    style  = File.exists?(style) ? style : 'all'
+    issues = 0
+
+    unless system('mdl', '--version')
+      puts '  * Markdown linter not found: gem install mdl'
+      puts
+      @warnings += 1
+      return
+    end
+
+    Dir.glob('**/*.md') do |file|
+      next if File.symlink? file
+      next if File.directory? file
+      next if file =~ /^_.*$|^[^\/]*$/
+
+      issues += 1 unless system('mdl', '-s', style, file)
+    end
+
+    if issues > 0
+      puts
+      puts 'Rule explanations can be found at:'
+      puts '  * https://github.com/mivok/markdownlint/blob/master/docs/RULES.md'
+      puts
+      @warnings += issues
+    end
+  end
+
+end

data/lib/courseware/printer.rb

@@ -0,0 +1,224 @@
+require 'fileutils'
+class Courseware::Printer
+
+  def initialize(config, opts)
+    @config  = config
+    @course  = opts[:course]  or raise 'Course is a required option'
+    @prefix  = opts[:prefix]  or raise 'Prefix is a required option'
+    @version = opts[:version] or raise 'Version is a required option'
+    @varfile = opts[:variant] or raise 'Variant is a required option'
+
+    @variant = File.basename(@varfile, '.json') unless @varfile == 'showoff.json'
+
+    raise unless can_print?
+
+    @pdfopts = "--pdf-title '#{@course}' --pdf-author '#{@config[:pdf][:author]}' --pdf-subject '#{@config[:pdf][:subject]}'"
+    @pdfopts << " --disallow-modify" if @config[:pdf][:protected]
+
+    if @config[:pdf][:watermark]
+      @event_id        = Courseware.question('Enter the Event ID:')
+      @password        = Courseware.question('Enter desired password:', (@event_id[/-?(\w*)$/, 1] rescue nil))
+      @watermark_style = File.join(@config[:cachedir], 'templates', 'watermark.css')
+      @watermark_pdf   = File.join(@config[:cachedir], 'templates', 'watermark.pdf')
+    end
+
+    FileUtils.mkdir(config[:output]) unless File.directory?(config[:output])
+
+    if block_given?
+      yield self
+      FileUtils.rm_rf('static')
+    end
+  end
+
+  def print
+    handouts
+    exercises
+    solutions
+  end
+
+  def handouts
+    $logger.info "Generating handouts pdf for #{@course} #{@version}..."
+
+    generate_pdf(:print)
+  end
+
+  def exercises
+    $logger.info "Generating exercise guide pdf for #{@course} #{@version}..."
+
+    generate_pdf(:exercises)
+  end
+
+  def solutions
+    $logger.info "Generating solutions guide pdf for #{@course} #{@version}..."
+
+    generate_pdf(:solutions)
+  end
+
+  def guide
+    $logger.info "Generating instructor guide pdf for #{@course} #{@version}..."
+
+    generate_pdf(:guide)
+  end
+
+  # Ensure that the printing toolchain is in place.
+  def can_print?
+    case @config[:renderer]
+    when :wkhtmltopdf
+      # Fonts must be installed locally for wkhtmltopdf to find them
+      if RUBY_PLATFORM =~ /darwin/
+        fontpath = File.expand_path('~/Library/Fonts')
+        Dir.glob('_fonts/*').each do |font|
+          destination = "#{fontpath}/#{File.basename(font)}"
+          FileUtils.cp(font, destination) unless File.exists?(destination)
+        end
+      end
+
+      unless system 'wkhtmltopdf --version >/dev/null 2>&1' and system 'pdftk --version >/dev/null 2>&1'
+        msg = "We use wkhtmltopdf and pdftk to generate courseware PDF files.\n" +
+              "\n"                                                               +
+              "You should install them using Homebrew or directly from:\n"       +
+              "  * http://wkhtmltopdf.org/downloads.htm\n"                       +
+              "  * https://www.pdflabs.com/tools/pdftk-server/#download"
+
+        unless RUBY_PLATFORM =~ /darwin/
+          msg << "\n\n"
+          msg << 'Please install all the fonts in the `_fonts` directory to your system.'
+        end
+
+        Courseware.dialog('Printing toolchain unavailable.', msg)
+        return false
+      end
+
+    when :prince
+      unless system 'prince --version >/dev/null 2>&1'
+        msg = "This course is configured to use PrinceXMLto generate PDF files.\n" +
+              "\n"                                                                 +
+              "You should install version 9 from:\n"                               +
+              "  * http://www.princexml.com/download/\n"                           +
+              "\n"                                                                 +
+              "And the license from:\n"                                            +
+              "  * https://confluence.puppet.com/display/EDU/Licenses"
+
+        Courseware.dialog('Printing toolchain unavailable.', msg)
+        return false
+      end
+    end
+
+    return true
+  end
+
+  # clean out the static dir and build the source html
+  def generate_html(subject)
+    case subject
+    when :handouts, :print
+      subject = 'print'
+    when :exercises, :solutions
+      subject = "supplemental #{subject}"
+    when :guide
+      subject = 'print guide'
+    else
+      raise "I don't know how to generate HTML of #{subject}."
+    end
+
+    begin
+      # Until showoff static knows about -f, we have to schlup around files
+      if @variant
+        FileUtils.mv 'showoff.json', 'showoff.json.tmp'
+        FileUtils.cp @varfile, 'showoff.json'
+      end
+
+      FileUtils.rm_rf('static')
+      system("showoff static #{subject}")
+      if File.exists? 'cobrand.png'
+        FileUtils.mkdir(File.join('static', 'image'))
+        FileUtils.cp('cobrand.png', File.join('static', 'image', 'cobrand.png'))
+      end
+    ensure
+      FileUtils.mv('showoff.json.tmp', 'showoff.json') if File.exist? 'showoff.json.tmp'
+    end
+  end
+
+  def generate_pdf(subject)
+    # TODO screen printing
+    # @pdfopts << " #{SCREENHACK}"
+    # @suffix = "-screen"
+
+    # Build the filename for the output PDF. This is ugly.
+    output = File.join(@config[:output], "#{@prefix}-")
+    output << "#{@variant}-" if @variant
+    output << 'w-' if @config[:pdf][:watermark]
+    case subject
+    when :print
+      output << "#{@version}.pdf"
+    when :exercises, :solutions, :guide
+      output << "#{@version}-#{subject}.pdf"
+    else
+      raise "I don't know how to generate a PDF of #{subject}."
+    end
+
+    generate_html(subject)
+    FileUtils.mkdir(@config[:output]) unless File.directory?(@config[:output])
+
+    case @config[:renderer]
+    when :wkhtmltopdf
+      infofile    = File.join(@config[:output], 'info.txt')
+      scratchfile = File.join(@config[:output], 'scratch.pdf')
+
+      command = ['wkhtmltopdf', '-s', 'Letter', '--print-media-type', '--quiet']
+      command << ['--footer-left', "#{@course} #{@version}", '--footer-center', '[page]']
+      command << ['--footer-right', "©#{Time.now.year} Puppet", '--header-center', '[section]']
+      command << ['--title', @course, File.join('static', 'index.html'), output]
+      system(*command.flatten)
+      raise 'Error generating PDF files' unless $?.success?
+
+      if `pdftk #{output} dump_data | grep NumberOfPages`.chomp == 'NumberOfPages: 1'
+        puts "#{output} is empty; aborting and cleaning up."
+        FileUtils.rm(output)
+        return
+      end
+
+      # We can't add metadata in the same run. It requires dumping, modifying, and updating
+      if @event_id
+        command = ['pdftk', output, 'dump_data', 'output', infofile]
+        system(*command.flatten)
+        raise 'Error retrieving PDF info' unless $?.success?
+        info = File.read(infofile)
+        File.open(infofile, 'w+') do |file|
+          file.write("InfoBegin\n")
+          file.write("InfoKey: Subject\n")
+          file.write("InfoValue: #{@event_id}\n")
+          file.write(info)
+        end
+        command = ['pdftk', output, 'update_info', infofile, 'output', scratchfile]
+        system(*command.flatten)
+        raise 'Error updating PDF info' unless $?.success?
+      else
+        FileUtils.mv(output, scratchfile)
+      end
+
+      command = ['pdftk', scratchfile, 'output', output]
+      command << ['owner_pw', @config[:pdf][:password], 'allow', 'printing', 'CopyContents']
+      command << ['background', @watermark_pdf] if @config[:pdf][:watermark]
+      command << ['user_pw', @password] if @password
+      system(*command.flatten)
+      raise 'Error watermarking PDF files' unless $?.success?
+
+      FileUtils.rm(infofile)    if File.exists? infofile
+      FileUtils.rm(scratchfile) if File.exists? scratchfile
+
+    when :prince
+      command = ['prince', File.join('static', 'index.html')]
+      command << ['--pdf-title', @course, '--pdf-author', @config[:pdf][:author], '--disallow-modify']
+      command << ['--pdf-subject', @event_id] if @event_id
+      command << ['--style', @watermark_style] if @config[:pdf][:watermark]
+      command << ['--encrypt', '--user-password', @password] if @password
+      command << ['--license-file', @config[:pdf][:license]] if (@config[:pdf][:license] and File.exists? @config[:pdf][:license])
+      command << ['-o', output]
+      system(*command.flatten)
+      raise 'Error generating PDF files' unless $?.success?
+    end
+
+    FileUtils.rm_rf('static')
+  end
+
+end

data/lib/courseware/repository.rb

@@ -0,0 +1,189 @@
+require 'fileutils'
+require 'rubygems'
+class Courseware::Repository
+
+  def initialize(config)
+    raise 'This is not a courseware repository' unless Courseware::Repository.repository?
+    @config = config
+
+    configure_courseware
+  end
+
+  def tag(tag, message=nil)
+    if tag
+      system("git tag -a #{tag} -m '#{message}'")
+    else
+      system("git tag #{tag}")
+    end
+
+    system("git push upstream master")
+    system("git push upstream #{tag}")
+    system("git push courseware master")
+    system("git push courseware #{tag}")
+  end
+
+  def update
+    system('git fetch upstream')
+    system('git fetch upstream --tags')
+  end
+
+  def create(branch)
+    system("git checkout -b #{branch}")
+    system("git push upstream #{branch}")
+  end
+
+  def checkout(branch, pull=false)
+    system("git checkout #{branch}")
+    pull(branch) if pull
+  end
+
+  def pull(branch)
+    system('git', 'pull', 'upstream', branch)
+  end
+
+  def merge(branch)
+    system('git checkout master')
+    system("git merge #{branch}")
+    system('git push upstream master')
+  end
+
+  def delete(branch)
+    system("git branch -d #{branch}")
+    system("git push upstream --delete #{branch}")
+  end
+
+  def commit(*args)
+    message = args.pop
+    args.each do |file|
+      system('git', 'add', file)
+    end
+    system('git', 'commit', '-m', message)
+  end
+
+  def discard(*args)
+    args.each do |file|
+      $logger.warn "Discarding changes to #{file}"
+      system('git', 'checkout', '--', file)
+    end
+  end
+
+  def last_commit
+    `git show --name-status --no-color`.chomp.gsub("\t", '    ')
+  end
+
+  def on_branch?(branch='master')
+    `git symbolic-ref -q --short HEAD`.chomp == branch
+  end
+
+  def clean?
+    system('git diff-index --quiet HEAD')
+  end
+
+  # clean working tree and no untracked files
+  def pristine?
+    clean? and `git ls-files --other --directory --exclude-standard`.empty?
+  end
+
+  def branch_exists?(branch)
+    `git branch --list '#{branch}'` != ''
+  end
+
+  def toplevel?
+    Dir.pwd == `git rev-parse --show-toplevel`.chomp
+  end
+
+  def courselevel?
+    File.expand_path("#{Dir.pwd}/..") == `git rev-parse --show-toplevel`.chomp
+  end
+
+  def outstanding_commits(prefix, verbose=false)
+    last = current(prefix)
+    commits = `git log --no-merges --oneline #{prefix}-#{last}..HEAD -- .`.each_line.map {|line| line.chomp }
+
+    verbose ? commits : commits.count
+  end
+
+  def releasenotes(last, version)
+    str = "### #{version}\n"
+    str << "{{{Please summarize the release here}}}\n"
+    str << "\n"
+    str << `git log --no-merges --pretty="format:* (%h) %s [%aN]" #{last}..HEAD -- .`
+    str
+  end
+
+  # This gets a list of all tags matching a prefix.
+  def tags(prefix, count=1)
+    prefix ||= 'v' # even if we pass in nil, we want to default to this
+    tags = `git tag -l '#{prefix}*'`.split("\n").sort_by { |tag| version(tag) }.last(count)
+    tags.empty? ? ['v0.0.0'] : tags
+  end
+
+  def current(prefix)
+    tags(prefix).first.gsub(/^#{prefix}-/, '')
+  end
+
+private
+
+  def configure_courseware
+    courseware = "#{@config[:github][:public]}/#{@config[:github][:repository]}"
+    upstream   = "#{@config[:github][:development]}/#{@config[:github][:repository]}"
+
+    # Check the origin to see which scheme we should use
+    origin = `git config --get remote.origin.url`.chomp
+    if origin =~ /^(git@|https:\/\/)github.com[:\/].*\/#{@config[:github][:repository]}(?:-.*)?(?:.git)?$/
+      case $1
+      when 'git@'
+        ensure_remote('courseware', "git@github.com:#{courseware}.git")
+        ensure_remote('upstream',   "git@github.com:#{upstream}.git")
+      when 'https://'
+        ensure_remote('courseware', "https://github.com/#{courseware}.git")
+        ensure_remote('upstream',   "https://github.com/#{upstream}.git")
+      end
+    elsif origin.empty?
+      $logger.warn 'Your origin remote is not set properly.'
+      $logger.warn 'Generating PDF files and other local operations will work properly, but many repository actions will fail.'
+    else
+      raise "Your origin (#{origin}) does not appear to be configured correctly."
+    end
+  end
+
+  def ensure_remote(remote, url)
+    # If we *have* the remote, but it's not correct, then  let's repair it.
+    if `git config --get remote.#{remote}.url`.chomp != url and $?.success?
+      if Courseware.confirm("Your '#{remote}' remote should be #{url}. May I correct this?")
+        raise "Error correcting remote." unless system("git remote remove #{remote}")
+      else
+        raise "Please configure your '#{remote}' remote before proceeding."
+      end
+    end
+
+    # add the remote, either for the first time or because we removed it
+    unless system("git config --get remote.#{remote}.url > /dev/null")
+      # Add the remote if it doesn't already exist
+      unless system("git remote add #{remote} #{url}")
+        raise "Could not add the '#{remote}' remote."
+      end
+    end
+
+    # for pedantry, validate the refspec too
+    unless `git config --get remote.#{remote}.fetch`.chomp == "+refs/heads/*:refs/remotes/#{remote}/*"
+      if Courseware.confirm("Your '#{remote}' remote has an invalid refspec. May I correct this?")
+        unless system("git config remote.#{remote}.fetch '+refs/heads/*:refs/remotes/#{remote}/*'")
+          raise "Could not repair the '#{remote}' refspec."
+        end
+      else
+        raise "Please configure your '#{remote}' remote before proceeding."
+      end
+
+    end
+  end
+
+  # Gem::Version is used simply for semantic version comparisons.
+  def version(tag)
+    Gem::Version.new(tag.gsub(/^.*-?v/, '')) rescue Gem::Version.new(0)
+  end
+
+  def self.repository?
+    system('git status >/dev/null 2>&1')
+  end
+end