Create 'asciibinder' utility

Author: nhr

.gitignore

@@ -12,3 +12,5 @@
 *.o
 *.a
 mkmf.log
+*.gem
+*.swp

Guardfile

@@ -0,0 +1,3 @@
+require 'ascii_binder'
+gem_dir = Gem::Specification.find_by_name("ascii_binder").lib_dirs_glob
+instance_eval(File.read(File.join(gem_dir, 'ascii_binder/tasks/guards.rb')))

ascii_binder.gemspec

@@ -31,6 +31,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'json'
   spec.add_dependency 'pandoc-ruby'
   spec.add_dependency 'sitemap_generator', '~> 5.1.0'
+  spec.add_dependency 'trollop', '~> 2.1.2'
   spec.add_dependency 'yajl-ruby'
   spec.add_dependency 'tilt'
 end

bin/asciibinder

@@ -0,0 +1,155 @@
+#!/usr/bin/env ruby
+
+require 'ascii_binder/helpers'
+require 'pathname'
+require 'trollop'
+
+
+include AsciiBinder::Helpers
+
+SUB_COMMANDS = %w{help build watch package clean}
+Trollop::options do
+  banner <<-EOF
+Usage:
+  #$0 <command> <repo_dir>
+
+Commands:
+  build (default action)
+    Builds the HTML docs in the indicated repo dir
+  watch
+    Starts Guard, which automatically regenerates changed HTML
+    files on the working branch in the repo dir
+  package
+    Builds and packages the static HTML for all of the sites
+    defined in the _distro_config.yml file
+  clean
+    Remove _preview, _publish and _package dirs created by
+    other asciibinder operations.
+
+Options:
+EOF
+  stop_on SUB_COMMANDS
+end
+
+cmd = ARGV.shift
+repo_dir = nil
+
+if cmd.nil?
+  cmd = "build"
+elsif not SUB_COMMANDS.include?(cmd)
+  if not ARGV.empty?
+    Trollop::die "'#{cmd}' is not a valid asciibinder command. Legal values are '#{SUB_COMMANDS.join('\', \'')}'."
+  else
+    repo_dir = Pathname.new(cmd)
+    cmd = "build"
+  end
+end
+
+cmd_opts = case cmd
+  when "build"
+    Trollop::options do
+      banner <<-EOF
+Usage:
+  #$0 build <options> <repo_dir>
+
+Description:
+  This is the default behavior for the asciibinder utility. When run,
+  asciibinder reads the _distro_config.yml file out of the working
+  branch of the indicated repo directory and based on that, proceeds to
+  build the working branch version of the documentation for each distro.
+
+  Once the working branch version is built, asciibinder cycles through
+  the other branches named in the _distro_config.yml file until all of
+  the permutations have been built.
+
+Options:
+EOF
+      opt :distro, "Instead of building all distros, build branches only for the specified distro.", :default => ''
+    end
+  #when "new"
+  #  Trollop::options do
+  #    opt :initialize, "Create a new AsciiBinder-ready git repo in the target directory.", :default => true
+  #  end
+  when "watch"
+    Trollop::options do
+      banner <<-EOF
+Usage:
+  #$0 watch <repo_dir>
+
+Description:
+  In watch mode, asciibinder starts a Guard process in the foreground.
+  This process watches the repo_dir for changes to the AsciiDoc (.adoc)
+  files. When a change occurs, asciibinder regenerates the specific
+  HTML output of the file that was changed, for the working branch only.
+
+  This is meant to be used in conjunction with a web browser that is
+  running a LiveReload plugin. If you are viewing the output HTML page
+  in a browser where LiveReload is active, then every time you save a
+  new version of the .adoc file, the new HTML is automatically
+  regenrated and your page view is automatically refreshed.
+EOF
+    end
+  when "package"
+    Trollop::options do
+      banner <<-EOF
+Usage:
+  #$0 package <options> <repo_dir>
+
+Description:
+  Publish mode is similar to 'build' mode, but once all of the branches' of
+  HTML are generated, 'publish' goes on to organize the branch / distro
+  combinations that are described in _distro_config.yml into their "site"
+  layouts. As a final step, the site layouts are tarred and gzipped for
+  easy placement onto a production web server.
+
+Options:
+EOF
+      opt :site, "Instead of packaging every docs site, package the specified site only.", :default => ''
+    end
+  when "help"
+    Trollop::educate
+  end
+
+if (not repo_dir.nil? and not ARGV.empty?) or (repo_dir.nil? and ARGV.length > 1)
+  Trollop::die "Too many arguments provided to ascii_binder: '#{ARGV.join(' ')}'. Exiting."
+elsif repo_dir.nil?
+  if ARGV.length == 1
+    repo_dir = Pathname.new(ARGV.shift)
+  else
+    repo_dir = Pathname.pwd
+  end
+end
+
+# Validate the repo_dir path
+if not repo_dir.exist?
+  Trollop::die "The specified repo directory '#{repo_dir}' does not exist."
+elsif not repo_dir.directory?
+  Trollop::die "The specified repo directory path '#{repo_dir}' is not a directory."
+elsif not repo_dir.readable?
+  Trollop::die "The specified repo directory '#{repo_dir}' is not readable."
+elsif not repo_dir.writable?
+  Trollop::die "The specified repo directory '#{repo_dir}' cannot be written to."
+end
+
+# Set the repo root
+set_source_dir(File.expand_path(repo_dir))
+
+# Do the things with the stuff
+case cmd
+when "build"
+  build_distro = cmd_opts[:build] || ''
+  generate_docs(build_distro)
+when "package"
+  clean_up
+  generate_docs('')
+  package_site = cmd_opts[:site] || ''
+  package_docs(package_site)
+when "watch"
+  guardfile_path = File.join(Gem::Specification.find_by_name("ascii_binder").full_gem_path, 'Guardfile')
+  exec("guard -G #{guardfile_path}")
+when "clean"
+  clean_up
+  puts "Cleaned up #{repo_dir}."
+end
+
+exit

lib/ascii_binder/helpers.rb

@@ -1,3 +1,4 @@
+require 'ascii_binder/template_renderer'
 require 'asciidoctor'
 require 'asciidoctor/cli'
 require 'asciidoctor-diagram'
@@ -18,6 +19,10 @@ def self.source_dir
       @source_dir ||= `git rev-parse --show-toplevel`.chomp
     end
 
+    def self.set_source_dir(source_dir)
+      @source_dir = source_dir
+    end
+
     def self.template_dir
       @template_dir ||= File.join(source_dir,'_templates')
     end
@@ -42,9 +47,7 @@ def self.package_dir
       end
     end
 
-    def_delegators self, :source_dir, :template_dir, :preview_dir, :package_dir
-
-    TemplateRenderer.initialize_cache(template_dir)
+    def_delegators self, :source_dir, :set_source_dir, :template_dir, :preview_dir, :package_dir
 
     BUILD_FILENAME      = '_build_cfg.yml'
     DISTRO_MAP_FILENAME = '_distro_map.yml'
@@ -70,17 +73,17 @@ def git_checkout branch_name
 
     def git_stash_all
       # See if there are any changes in need of stashing
-      @stash_needed = `git status --porcelain` !~ /^\s*$/
+      @stash_needed = `cd #{source_dir} && git status --porcelain` !~ /^\s*$/
       if @stash_needed
         puts "\nNOTICE: Stashing uncommited changes and files in working branch."
-        `git stash -u`
+        `cd #{source_dir} && git stash -u`
       end
     end
 
     def git_apply_and_drop
       return unless @stash_needed
       puts "\nNOTE: Re-applying uncommitted changes and files to working branch."
-      if system("git stash pop")
+      if system("cd #{source_dir} && git stash pop")
         puts "NOTE: Stash application successful."
       else
         puts "ERROR: Could not apply stashed code. Run `git stash apply` manually."
@@ -184,7 +187,7 @@ def page(args)
         args[:subtopic_shim]             = '../'
       end
 
-      TemplateRenderer.new.render("_templates/page.html.erb", args)
+      TemplateRenderer.new.render(File.expand_path("#{source_dir}/_templates/page.html.erb"), args)
     end
 
     def extract_breadcrumbs(args)
@@ -405,6 +408,9 @@ def generate_docs(build_distro,single_page=nil)
         puts "Building all distributions."
       end
 
+      # Cache the page templates
+      TemplateRenderer.initialize_cache(template_dir)
+
       # First, notify the user of missing local branches
       missing_branches = []
       distro_branches(build_distro).sort.each do |dbranch|
@@ -432,6 +438,9 @@ def generate_docs(build_distro,single_page=nil)
           end
         end
 
+        # Note the image files checked in to this branch.
+        branch_image_files = Find.find(source_dir).select{ |path| not path.nil? and (path =~ /.*\.png$/ or path =~ /.*\.png\.cache$/) }
+
         first_branch = single_page.nil?
 
         if local_branch =~ /^\(detached from .*\)/
@@ -477,13 +486,13 @@ def generate_docs(build_distro,single_page=nil)
           system("mkdir -p #{branch_path}/images")
 
           # Copy stylesheets into preview area
-          system("cp -r _stylesheets/*css #{branch_path}/stylesheets")
+          system("cp -r #{source_dir}/_stylesheets/*css #{branch_path}/stylesheets")
 
           # Copy javascripts into preview area
-          system("cp -r _javascripts/*js #{branch_path}/javascripts")
+          system("cp -r #{source_dir}/_javascripts/*js #{branch_path}/javascripts")
 
           # Copy images into preview area
-          system("cp -r _images/* #{branch_path}/images")
+          system("cp -r #{source_dir}/_images/* #{branch_path}/images")
 
           # Build the landing page
           navigation = nav_tree(distro,branch_build_config)
@@ -573,6 +582,15 @@ def generate_docs(build_distro,single_page=nil)
           return
         end
 
+        # Remove DITAA-generated images
+        ditaa_image_files = Find.find(source_dir).select{ |path| not path.nil? and not (path =~ /_preview/ or path =~ /_package/) and (path =~ /.*\.png$/ or path =~ /.*\.png\.cache$/) and not branch_image_files.include?(path) }
+        if not ditaa_image_files.empty?
+          puts "\nRemoving ditaa-generated files from repo before changing branches."
+          ditaa_image_files.each do |dfile|
+            File.unlink(dfile)
+          end
+        end
+
         if local_branch == working_branch
           # We're moving away from the working branch, so save off changed files
           git_stash_all
@@ -652,6 +670,7 @@ def configure_and_generate_page options
       :images_path      => "../../#{dir_depth}#{branch_config["dir"]}/images/",
       :site_home_path   => "../../#{dir_depth}index.html",
       :css              => ['docs.css'],
+      :template_dir     => template_dir,
     }
     full_file_text = page(page_args)
     File.write(tgt_file_path,full_file_text)
@@ -706,5 +725,11 @@ def package_docs(package_site)
         end
       end
     end
+
+    def clean_up
+      if not system("rm -rf #{source_dir}/_preview/* #{source_dir}/_package/*")
+        puts "Nothing to clean."
+      end
+    end
   end
 end

lib/ascii_binder/version.rb

@@ -1,3 +1,3 @@
 module AsciiBinder
-  VERSION = "0.0.6"
+  VERSION = "0.0.7"
 end