ascii_binder 0.0.7 → 0.0.8

data/bin/asciibinder

@@ -4,10 +4,20 @@ require 'ascii_binder/helpers'
 require 'pathname'
 require 'trollop'
 
-
 include AsciiBinder::Helpers
 
-SUB_COMMANDS = %w{help build watch package clean}
+def call_generate(distro,page=nil)
+  if page == ''
+    page = nil
+  end
+  begin
+    generate_docs(distro,page)
+  rescue Exception => e
+    Trollop::die "Could not generate docs: #{e.message}"
+  end
+end
+
+SUB_COMMANDS = %w{help build watch package clean create}
 Trollop::options do
   banner <<-EOF
 Usage:
@@ -16,6 +26,8 @@ Usage:
 Commands:
   build (default action)
     Builds the HTML docs in the indicated repo dir
+  create
+    Generates a new AsciiBinder repo at the indicated dir
   watch
     Starts Guard, which automatically regenerates changed HTML
     files on the working branch in the repo dir
@@ -24,7 +36,7 @@ Commands:
     defined in the _distro_config.yml file
   clean
     Remove _preview, _publish and _package dirs created by
-    other asciibinder operations.
+    other AsciiBinder operations.
 
 Options:
 EOF
@@ -38,7 +50,7 @@ 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('\', \'')}'."
+    Trollop::die "'#{cmd}' is not a valid asciibinder subcommand. Legal values are '#{SUB_COMMANDS.join('\', \'')}'."
   else
     repo_dir = Pathname.new(cmd)
     cmd = "build"
@@ -54,22 +66,44 @@ Usage:
 
 Description:
   This is the default behavior for the asciibinder utility. When run,
-  asciibinder reads the _distro_config.yml file out of the working
+  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
+  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.
 
+  The available options enable you to limit the scope of the build work,
+  as described by the options themselves. Note that the format for the
+  "--page" option is:
+
+  <topic_group>:<topic_file>
+
+  or for subtopics:
+
+  <topic_group>/<subtopic_group>:<topic_file>
+
+  However, if you want to use the --page option extensively, then be
+  aware of the `asciibinder watch` function, which does this for you
+  automatically as you change .adoc files in your working branch.
+
 Options:
 EOF
       opt :distro, "Instead of building all distros, build branches only for the specified distro.", :default => ''
+      opt :page, "Build only the specified page for all distros and only the current working branch.", :default => ''
+      conflicts :distro, :page
+    end
+  when "create"
+    Trollop::options do
+      banner <<-EOF
+Usage:
+  #$0 create <new_repo_dir>
+
+Description:
+  Creates a new, bare AsciiBinder repo in the specified directory.
+EOF
     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
@@ -77,16 +111,23 @@ Usage:
   #$0 watch <repo_dir>
 
 Description:
-  In watch mode, asciibinder starts a Guard process in the foreground.
+  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
+  files. When a change occurs, AsciiBinder regenerates the specific
   HTML output of the file that was changed, for the working branch only.
 
+  This is the equivalent of running:
+
+  $ asciibinder build --page='<topic_group>:<affected_file>'
+
+  ...except that the Guardfile automatically detects and runs this as
+  you work.
+
   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.
+  regenerated and your page view is automatically refreshed.
 EOF
     end
   when "package"
@@ -116,40 +157,70 @@ elsif repo_dir.nil?
   if ARGV.length == 1
     repo_dir = Pathname.new(ARGV.shift)
   else
-    repo_dir = Pathname.pwd
+    if not cmd == 'create'
+      repo_dir = Pathname.pwd
+    else
+      Trollop::die "Specify a name for the new repo directory."
+    end
   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."
+if cmd == 'create'
+  if repo_dir.exist?
+    Trollop::die "The specified new repo directory '#{repo_dir}' already exists."
+  end
+else
+  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."
+  else
+    ['.git','_build_cfg.yml','_distro_map.yml','_templates'].each do |file|
+      if not File.exist?(File.join(repo_dir, file))
+        Trollop::die "The specified repo directory '#{repo_dir}' does not appear to be an AsciiBinder repo."
+      end
+    end
+  end
 end
 
 # Set the repo root
 set_source_dir(File.expand_path(repo_dir))
 
+# Change to the repo dir. This is necessary in order for
+# AsciiDoctor to work properly.
+if not cmd == 'create'
+  Dir.chdir source_dir
+end
+
 # Do the things with the stuff
 case cmd
 when "build"
   build_distro = cmd_opts[:build] || ''
-  generate_docs(build_distro)
+  refresh_page = cmd_opts[:page] || ''
+  call_generate(build_distro,refresh_page)
 when "package"
   clean_up
-  generate_docs('')
+  call_generate('')
   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}")
+  if not dir_empty?(preview_dir)
+    guardfile_path = File.join(Gem::Specification.find_by_name("ascii_binder").full_gem_path, 'Guardfile')
+    exec("guard -G #{guardfile_path}")
+  else
+    Trollop::die "Run 'asciibinder build' at least once before running 'asciibinder watch'."
+  end
 when "clean"
   clean_up
   puts "Cleaned up #{repo_dir}."
+when "create"
+  create_new_repo
+  puts "Created new repo in #{repo_dir}."
 end
 
 exit

data/lib/ascii_binder/helpers.rb

@@ -2,6 +2,7 @@ require 'ascii_binder/template_renderer'
 require 'asciidoctor'
 require 'asciidoctor/cli'
 require 'asciidoctor-diagram'
+require 'fileutils'
 require 'find'
 require 'git'
 require 'logger'
@@ -19,10 +20,18 @@ module AsciiBinder
       @source_dir ||= `git rev-parse --show-toplevel`.chomp
     end
 
+    def self.gem_root_dir
+      @gem_root_dir ||= File.expand_path("../../../", __FILE__)
+    end
+
     def self.set_source_dir(source_dir)
       @source_dir = source_dir
     end
 
+    def template_renderer
+      @template_renderer ||= TemplateRenderer.new(source_dir, template_dir)
+    end
+
     def self.template_dir
       @template_dir ||= File.join(source_dir,'_templates')
     end
@@ -47,13 +56,28 @@ module AsciiBinder
       end
     end
 
-    def_delegators self, :source_dir, :set_source_dir, :template_dir, :preview_dir, :package_dir
+    def self.stylesheet_dir
+      @stylesheet_dir ||= File.join(source_dir,STYLESHEET_DIRNAME)
+    end
+
+    def self.javascript_dir
+      @javascript_dir ||= File.join(source_dir,JAVASCRIPT_DIRNAME)
+    end
+
+    def self.image_dir
+      @image_dir ||= File.join(source_dir,IMAGE_DIRNAME)
+    end
+
+    def_delegators self, :source_dir, :set_source_dir, :template_dir, :preview_dir, :package_dir, :gem_root_dir, :stylesheet_dir, :javascript_dir, :image_dir
 
     BUILD_FILENAME      = '_build_cfg.yml'
     DISTRO_MAP_FILENAME = '_distro_map.yml'
     BUILDER_DIRNAME     = '_build_system'
     PREVIEW_DIRNAME     = '_preview'
     PACKAGE_DIRNAME     = '_package'
+    STYLESHEET_DIRNAME  = '_stylesheets'
+    JAVASCRIPT_DIRNAME  = '_javascripts'
+    IMAGE_DIRNAME       = '_images'
     BLANK_STRING_RE     = Regexp.new('^\s*$')
 
     def build_date
@@ -95,8 +119,10 @@ module AsciiBinder
     def local_branches
       @local_branches ||= begin
         branches = []
-        branches << git.branches.local.select{ |b| b.current }[0].name
-        branches << git.branches.local.select{ |b| not b.current }.map{ |b| b.name }
+        if not git.branches.local.empty?
+          branches << git.branches.local.select{ |b| b.current }[0].name
+          branches << git.branches.local.select{ |b| not b.current }.map{ |b| b.name }
+        end
         branches.flatten
       end
     end
@@ -113,13 +139,54 @@ module AsciiBinder
       @distro_map_file ||= File.join(source_dir, DISTRO_MAP_FILENAME)
     end
 
+    def dir_empty?(dir)
+      Dir.entries(dir).select{ |f| not f.start_with?('.') }.empty?
+    end
+
     # Protip: Don't cache this! It needs to be reread every time we change branches.
     def build_config
       validate_config(YAML.load_stream(open(build_config_file)))
     end
 
+    def create_new_repo
+      gem_template_dir = File.join(gem_root_dir,"templates")
+
+      # Create the new repo dir
+      begin
+        Dir.mkdir(source_dir)
+      rescue Exception => e
+        raise "Could not create directory '#{source_dir}': #{e.message}"
+      end
+
+      # Copy the basic repo content into the new repo dir
+      Find.find(gem_template_dir).each do |path|
+        next if path == gem_template_dir
+        src_path = Pathname.new(path)
+        tgt_path = src_path.sub(gem_template_dir,source_dir)
+        if src_path.directory?
+          FileUtils.mkdir_p(tgt_path.to_s)
+        else
+          FileUtils.cp src_path.to_s, tgt_path.to_s
+        end
+      end
+
+      # Initialize the git repo and check everything in
+      g = nil
+      begin
+        g = Git.init(source_dir)
+      rescue Exception => e
+        raise "Could not initialize git repo in '#{source_dir}': #{e.message}"
+      end
+    end
+
     def find_topic_files
-      file_list = Find.find('.').select{ |path| not path.nil? and path =~ /.*\.adoc$/ and not path =~ /README/ and not path =~ /\/old\// and not path.split('/').length < 3 }
+      file_list = []
+      Find.find(source_dir).each do |path|
+        next if path.nil? or not path =~ /.*\.adoc/ or path =~ /README/ or path =~ /\/old\//
+        src_path = Pathname.new(path).sub(source_dir,'').to_s
+        next if src_path.split('/').length < 3
+        file_list << src_path
+      end
       file_list.map{ |path|
         parts = path.split('/').slice(1..-1);
         parts.slice(0..-2).join('/') + '/' + parts[-1].split('.')[0]
@@ -187,7 +254,8 @@ module AsciiBinder
         args[:subtopic_shim]             = '../'
       end
 
-      TemplateRenderer.new.render(File.expand_path("#{source_dir}/_templates/page.html.erb"), args)
+      template_path = File.expand_path("#{source_dir}/_templates/page.html.erb")
+      template_renderer.render(template_path, args)
     end
 
     def extract_breadcrumbs(args)
@@ -390,6 +458,12 @@ module AsciiBinder
     end
 
     def generate_docs(build_distro,single_page=nil)
+      # First, test to see if the docs repo has any commits. If the user has just
+      # run `asciibinder create`, there will be no commits to work from, yet.
+      if local_branches.empty?
+        raise "Before you can build the docs, you need at least one commit in your docs repo."
+      end
+
       single_page_dir  = []
       single_page_file = nil
       if not single_page.nil?
@@ -408,9 +482,6 @@ module AsciiBinder
         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|
@@ -480,19 +551,23 @@ module AsciiBinder
           end
 
           # Create the target dir
-          branch_path = File.join(preview_dir,distro,branch_config["dir"])
-          system("mkdir -p #{branch_path}/stylesheets")
-          system("mkdir -p #{branch_path}/javascripts")
-          system("mkdir -p #{branch_path}/images")
-
-          # Copy stylesheets into preview area
-          system("cp -r #{source_dir}/_stylesheets/*css #{branch_path}/stylesheets")
-
-          # Copy javascripts into preview area
-          system("cp -r #{source_dir}/_javascripts/*js #{branch_path}/javascripts")
-
-          # Copy images into preview area
-          system("cp -r #{source_dir}/_images/* #{branch_path}/images")
+          branch_path           = File.join(preview_dir,distro,branch_config["dir"])
+          branch_stylesheet_dir = File.join(branch_path,STYLESHEET_DIRNAME)
+          branch_javascript_dir = File.join(branch_path,JAVASCRIPT_DIRNAME)
+          branch_image_dir      = File.join(branch_path,IMAGE_DIRNAME)
+
+          # Copy files into the preview area.
+          [[stylesheet_dir, '*css', branch_stylesheet_dir],
+           [javascript_dir, '*js',  branch_javascript_dir],
+           [image_dir,      '*',    branch_image_dir]].each do |dgroup|
+            src_dir = dgroup[0]
+            glob    = dgroup[1]
+            tgt_dir = dgroup[2]
+            if Dir.exist?(src_dir) and not dir_empty?(src_dir)
+              FileUtils.mkdir_p tgt_dir
+              FileUtils.cp_r Dir.glob(File.join(src_dir,glob)), tgt_dir
+            end
+          end
 
           # Build the landing page
           navigation = nav_tree(distro,branch_build_config)
@@ -665,12 +740,11 @@ module AsciiBinder
       :group_id         => topic_group['ID'],
       :subgroup_id      => topic_subgroup && topic_subgroup['ID'],
       :topic_id         => topic['ID'],
-      :css_path         => "../../#{dir_depth}#{branch_config["dir"]}/stylesheets/",
-      :javascripts_path => "../../#{dir_depth}#{branch_config["dir"]}/javascripts/",
-      :images_path      => "../../#{dir_depth}#{branch_config["dir"]}/images/",
+      :css_path         => "../../#{dir_depth}#{branch_config["dir"]}/#{STYLESHEET_DIRNAME}/",
+      :javascripts_path => "../../#{dir_depth}#{branch_config["dir"]}/#{JAVASCRIPT_DIRNAME}/",
+      :images_path      => "../../#{dir_depth}#{branch_config["dir"]}/#{IMAGE_DIRNAME}/",
       :site_home_path   => "../../#{dir_depth}index.html",
-      :css              => ['docs.css'],
-      :template_dir     => template_dir,
+      :template_path    => template_dir,
     }
     full_file_text = page(page_args)
     File.write(tgt_file_path,full_file_text)

data/lib/ascii_binder/tasks/guards.rb

@@ -4,7 +4,7 @@ guard 'shell' do
       full_path      = m[0].split('/')
       src_group_path = full_path.length == 1 ? '' : full_path[0..-2].join('/')
       filename       = full_path[-1][0..-6]
-      system("bundle exec rake refresh_page['#{src_group_path}:#{filename}']")
+      system("asciibinder build --page='#{src_group_path}:#{filename}'")
     end
   }
 end

data/lib/ascii_binder/template_renderer.rb

@@ -2,24 +2,28 @@ require 'tilt'
 
 module AsciiBinder
   class TemplateRenderer
-    def self.template_cache
-      @template_cache ||= {}
-    end
+    attr_reader :source_dir, :template_cache
 
-    def self.initialize_cache(directory)
-      Dir.glob(File.join(directory, "**/*")).each do |file|
-        template_cache[file] = Tilt.new(file, :trim => "-")
+    def initialize(source_dir,template_directory)
+      @source_dir = source_dir
+      @template_cache = {}
+      Dir.glob(File.join(template_directory, "**/*")).each do |file|
+        @template_cache[file] = Tilt.new(file, :trim => "-")
       end
     end
 
     def render(template, args = {})
+      # Inside erb files, template path is local to repo
+      if not template.start_with?(source_dir)
+        template = File.join(source_dir, template)
+      end
       renderer_for(template).render(self, args).chomp
     end
 
     private
 
     def renderer_for(template)
-      self.class.template_cache.fetch(File.expand_path(template))
+      template_cache.fetch(File.expand_path(template))
     end
   end
 end