ascii_binder 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81f89642e2ac1db79b24ef73783da62f0addea2b
-  data.tar.gz: 4a0cd477ba230e682f67b80fc24170787ba360ba
+  metadata.gz: 6157f325397b76b4332f318aba16ada7f930093c
+  data.tar.gz: c0b13db6c9254db35c9d2b64a56755a88f929499
 SHA512:
-  metadata.gz: ef945848b9d34f7f3617380978be87d880e0e0d26089826433e4926aabd24dacd2a90fb0349bdb81d3f24739f47cb365741337bccd69cc5e13b0df1b171b25ec
-  data.tar.gz: 58716e1317b74cf487a423400af981715f82662970d6df8194dfb3ffe81679f7713998237d2d1e44dc0688c49803424c46406ea7a948fe5a4d25d8e3669e0d52
+  metadata.gz: 5709a933e576d0d1f7e4beb5a26ae35d54a70798b2bce6630382925387352fbd81b2fdb2ba084f54255e81f6a31bf2ce7bbf0a22f3da7f294489f73fa21c6c76
+  data.tar.gz: 7660ad1cf7c7d8df27a7a1c9da6dae59a87f6d130b09d9085c9a3e334d5f89a2ddf26b5831d1c297c361f03beda0c624f27db908a1630849b14ae5af82846c00

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+sudo: false
+cache: bundler
+rvm:
+  - 2.3.3
+after_install: gem list
+script:
+- git config --global user.name "Travis Test"
+- git config --global user.email "travis@mailinator.com"
+- bundle exec cucumber
+notifications:
+  irc:
+    channels:
+      - "irc.freenode.org#asciibinder"
+    on_success: change
+    on_failure: always

data/ascii_binder.gemspec

@@ -19,10 +19,12 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "cucumber", "~> 2.3.3"
+  spec.add_development_dependency "diff_dirs", "~> 0.1.2"
   spec.add_dependency "rake", "~> 10.0"
 
-  spec.add_dependency 'asciidoctor', '~> 1.5.4'
-  spec.add_dependency 'asciidoctor-diagram'
+  spec.add_dependency 'asciidoctor', '~> 1.5.6'
+  spec.add_dependency 'asciidoctor-diagram', '~> 1.5.5'
   spec.add_dependency 'git'
   spec.add_dependency 'guard'
   spec.add_dependency 'guard-shell'
@@ -32,6 +34,6 @@ Gem::Specification.new do |spec|
   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 'yajl-ruby', '~> 1.3.0'
   spec.add_dependency 'tilt'
 end

data/bin/asciibinder

@@ -1,10 +1,12 @@
 #!/usr/bin/env ruby
 
+require 'ascii_binder/engine'
 require 'ascii_binder/helpers'
 require 'ascii_binder/version'
 require 'pathname'
 require 'trollop'
 
+include AsciiBinder::Engine
 include AsciiBinder::Helpers
 
 def call_generate(branch_group, distro, page)
@@ -19,40 +21,47 @@ def call_generate(branch_group, distro, page)
   end
 end
 
-def repo_check(repo_dir)
+def repo_check(docs_basedir)
   missing_files = false
   # These must all be present
-  ['.git','_distro_map.yml','_templates'].each do |file|
-    unless File.exist?(File.join(repo_dir, file))
+  ['_distro_map.yml','_templates'].each do |file|
+    unless File.exist?(File.join(docs_basedir, file))
       missing_files = true
     end
   end
   # Either of these must be present
-  unless File.exist?(File.join(repo_dir, '_build_cfg.yml')) or File.exist?(File.join(repo_dir, '_topic_map.yml'))
+  unless File.exist?(File.join(docs_basedir, '_build_cfg.yml')) or File.exist?(File.join(docs_basedir, '_topic_map.yml'))
     missing_files = true
   end
-  if missing_files
-    Trollop::die "The specified repo directory '#{repo_dir}' does not appear to be an AsciiBinder repo."
+  if missing_files or not in_git_repo(docs_basedir)
+    Trollop::die "The specified docs base directory '#{docs_basedir}' does not appear to be part of an AsciiBinder-compatible repo."
   end
 end
 
+def in_git_repo(dir)
+  git_path = File.join(dir,'.git')
+  return true if File.exist?(git_path) and File.directory?(git_path)
+  return false if dir == '/'
+  in_git_repo(File.expand_path('..',dir))
+end
+
 SUB_COMMANDS = %w{help version build watch package clean create clone}
 Trollop::options do
   version AsciiBinder::VERSION
   banner <<-EOF
 Usage:
-  #$0 <command> <repo_dir>
+  #$0 <command> <docs_basedir>
 
 Commands:
   build (default action)
-    Builds the HTML docs in the indicated repo dir
+    Builds the HTML docs within the indicated docs base directory
   create
     Generates a new AsciiBinder repo at the indicated dir
   clone
     Clones an existing AsciiBinder repo to the local filesystem
   watch
     Starts Guard, which automatically regenerates changed HTML
-    files on the working branch in the repo dir
+    files on the working branch in the docs base directory dir
   package
     Builds and packages the static HTML for all of the sites
     defined in the _distro_config.yml file
@@ -66,13 +75,13 @@ EOF
 end
 
 cmd = ARGV.shift
-repo_dir = nil
+docs_basedir = nil
 
 if cmd.nil?
   cmd = "build"
 elsif !SUB_COMMANDS.include?(cmd)
   if ARGV.empty?
-    repo_dir = Pathname.new(cmd)
+    docs_basedir = Pathname.new(cmd)
     cmd = "build"
   else
     Trollop::die "'#{cmd}' is not a valid asciibinder subcommand. Legal values are '#{SUB_COMMANDS.join('\', \'')}'."
@@ -84,13 +93,13 @@ cmd_opts = case cmd
     Trollop::options do
       banner <<-EOF
 Usage:
-  #$0 build <options> <repo_dir>
+  #$0 build <options> <docs_basedir>
 
 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.
+  branch of the indicated docs base directory and based on that, proceeds
+  to build the working branch version of the documentation for each distro.
 
   If you use the --all_branches flag, AsciiBinder behaves as described
   above, and then once the working branch version is built, AsciiBinder
@@ -128,7 +137,7 @@ EOF
     Trollop::options do
       banner <<-EOF
 Usage:
-  #$0 create <new_repo_dir>
+  #$0 create <new_docs_basedir>
 
 Description:
   Creates a new, bare AsciiBinder repo in the specified directory.
@@ -155,11 +164,11 @@ EOF
     Trollop::options do
       banner <<-EOF
 Usage:
-  #$0 watch <repo_dir>
+  #$0 watch <docs_basedir>
 
 Description:
   In watch mode, AsciiBinder starts a Guard process in the foreground.
-  This process watches the repo_dir for changes to the AsciiDoc (.adoc)
+  This process watches the docs_basedir 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.
 
@@ -181,7 +190,7 @@ EOF
     Trollop::options do
       banner <<-EOF
 Usage:
-  #$0 package <options> <repo_dir>
+  #$0 package <options> <docs_basedir>
 
 Description:
   Publish mode is similar to 'build' mode, but once all of the branches' of
@@ -201,26 +210,26 @@ EOF
     exit 0
   end
 
-if (not repo_dir.nil? and not ARGV.empty?) or (repo_dir.nil? and ARGV.length > 1)
+if (not docs_basedir.nil? and not ARGV.empty?) or (docs_basedir.nil? and ARGV.length > 1)
   Trollop::die "Too many arguments provided to ascii_binder: '#{ARGV.join(' ')}'. Exiting."
-elsif repo_dir.nil?
+elsif docs_basedir.nil?
   if ARGV.length == 1
     if cmd == 'clone'
       cmd_opts[:giturl] = ARGV.shift
       if cmd_opts[:dir] != ''
-        repo_dir = Pathname.new(cmd_opts[:dir])
+        docs_basedir = Pathname.new(cmd_opts[:dir])
       else
-        repo_dir = Pathname.new(File.join(Pathname.pwd, cmd_opts[:giturl].split('/')[-1].split('.')[0]))
+        docs_basedir = Pathname.new(File.join(Pathname.pwd, cmd_opts[:giturl].split('/')[-1].split('.')[0]))
       end
     else
-      repo_dir = Pathname.new(ARGV.shift)
+      docs_basedir = Pathname.new(ARGV.shift)
     end
   else
     if cmd != 'create'
       if cmd == 'clone'
         Trollop::die "Provide a git URL to clone from."
       else
-        repo_dir = Pathname.pwd
+        docs_basedir = Pathname.pwd
       end
     else
       Trollop::die "Specify a name for the new repo directory."
@@ -228,39 +237,39 @@ elsif repo_dir.nil?
   end
 end
 
-# Validate the repo_dir path
+# Validate the docs_basedir path
 if cmd == 'create' or cmd == 'clone'
-  if repo_dir.exist?
-    Trollop::die "The specified new repo directory '#{repo_dir}' already exists."
+  if docs_basedir.exist?
+    Trollop::die "The specified new repo directory '#{docs_basedir}' already exists."
   end
 else
-  if !repo_dir.exist?
-    Trollop::die "The specified repo directory '#{repo_dir}' does not exist."
-  elsif !repo_dir.directory?
-    Trollop::die "The specified repo directory path '#{repo_dir}' is not a directory."
-  elsif !repo_dir.readable?
-    Trollop::die "The specified repo directory '#{repo_dir}' is not readable."
-  elsif !repo_dir.writable?
-    Trollop::die "The specified repo directory '#{repo_dir}' cannot be written to."
+  if !docs_basedir.exist?
+    Trollop::die "The specified docs directory '#{docs_basedir}' does not exist."
+  elsif !docs_basedir.directory?
+    Trollop::die "The specified docs directory path '#{docs_basedir}' is not a directory."
+  elsif !docs_basedir.readable?
+    Trollop::die "The specified docs directory '#{docs_basedir}' is not readable."
+  elsif !docs_basedir.writable?
+    Trollop::die "The specified docs directory '#{docs_basedir}' cannot be written to."
   else
-    repo_check(repo_dir)
+    repo_check(docs_basedir)
   end
 end
 
 # Set the repo root
-set_source_dir(File.expand_path(repo_dir))
+set_docs_root_dir(File.expand_path(docs_basedir))
 
 # Cloning? Time to try it.
 if cmd == 'clone'
-  puts "Cloning #{cmd_opts[:giturl]} to #{repo_dir}"
-  system("git clone #{cmd_opts[:giturl]} #{repo_dir}")
+  puts "Cloning #{cmd_opts[:giturl]} to #{docs_basedir}"
+  system("git clone #{cmd_opts[:giturl]} #{docs_basedir}")
   Trollop::die "The git URL could not be cloned: #{err}" if $?.exitstatus != 0
 
   # Make sure this cloned repo is legit.
-  repo_check(repo_dir)
+  repo_check(docs_basedir)
 
   if cmd_opts[:branches]
-    Dir.chdir(repo_dir)
+    Dir.chdir(docs_basedir)
     puts "Tracking branch setup:"
     distro_branches.each do |doc_branch|
       next if doc_branch == 'master'
@@ -279,7 +288,7 @@ end
 # Change to the repo dir. This is necessary in order for
 # AsciiDoctor to work properly.
 if cmd != 'create'
-  Dir.chdir source_dir
+  Dir.chdir docs_basedir
 end
 
 # Do the things with the stuff
@@ -304,10 +313,10 @@ when "watch"
   end
 when "clean"
   clean_up
-  puts "Cleaned up #{repo_dir}."
+  puts "Cleaned up #{docs_basedir}."
 when "create"
   create_new_repo
-  puts "Created new repo in #{repo_dir}."
+  puts "Created new repo in #{docs_basedir}."
 end
 
 exit

data/features/command_help.feature

@@ -0,0 +1,8 @@
+Feature: asciibinder help
+
+  Displays help information for the asciibinder utility
+
+  Scenario: A user wants to see help information for the utility
+    Given a nonexistant repo directory
+    When the user runs `asciibinder help` on that repo directory
+    Then the program displays help information

data/features/command_version.feature

@@ -0,0 +1,8 @@
+Feature: asciibinder version
+
+  This command returns the version of the installed utility
+
+  Scenario: A user wants to display the version of the asciibinder utility
+    Given a nonexistant repo directory
+    When the user runs `asciibinder version` on that repo directory
+    Then the program prints the current version of the utility

data/features/repo_build.feature

@@ -0,0 +1,34 @@
+Feature: asciibinder build
+
+  Causes the utility to process one or more distro/branch combinations,
+  transforming AsciiDoc files to a unified docs set in HTML
+
+  Scenario: A user wants to do any build in a repo with an invalid distro map
+    Given an invalid AsciiBinder docs repo due to a malformed distro map
+    When the user runs `asciibinder build` on that repo directory
+    Then the program exits with a warning
+
+  Scenario: A user wants to build all distros against the current repo branch
+    Given a valid AsciiBinder docs repo with multiple distros
+    When the user runs `asciibinder build` on that repo directory
+    Then the program generates preview content for all distros in the current branch
+
+  Scenario: A user wants to build a single distro against the current repo branch
+    Given a valid AsciiBinder docs repo with multiple distros
+    When the user runs `asciibinder build --distro=distro_test` on that repo directory
+    Then the program generates preview content for only the `distro_test` distro
+
+  Scenario: A user wants to build all distros against all relevant branches
+    Given a valid AsciiBinder docs repo with multiple distros
+    When the user runs `asciibinder build --all-branches` on that repo directory
+    Then the program generates preview content for all relevant distro/branch combos
+
+  Scenario: A user wants to build a specific page in the current branch
+    Given a valid AsciiBinder docs repo with multiple distros
+    When the user runs `asciibinder build --page=welcome:index` on that repo directory
+    Then the program generates preview content for the specified page in all distros
+
+  Scenario: A user wants to build from a repo where the docs root is not the repo root
+    Given a valid AsciiBinder docs repo where the docs root is not at the repo root
+    When the user runs `asciibinder build` on that docs root directory
+    Then the program generates preview content for all distros in the current branch

data/features/repo_clean.feature

@@ -0,0 +1,20 @@
+Feature: asciibinder clean
+
+  This command cleans up any files generated by AsciiBinder
+
+  Scenario: A user wants to clean a docs repo of generated content
+    Given a valid AsciiBinder docs repo
+    And the docs repo contains generated content
+    When the user runs `asciibinder clean` on that repo directory
+    Then the generated content is removed
+
+  Scenario: A user cleans a docs repo with no generated content
+    Given a valid AsciiBinder docs repo
+    And the docs repo contains no generated content
+    When the user runs `asciibinder clean` on that repo directory
+    Then the program exits without errors
+
+  Scenario: A user cleans a directory that is not a docs repo
+    Given an invalid AsciiBinder docs repo
+    When the user runs `asciibinder clean` on that repo directory
+    Then the program exits with a warning

data/features/repo_clone.feature

@@ -0,0 +1,22 @@
+Feature: asciibinder clone
+
+  This command clones a remote docs repo to a local directory and
+  sets up tracking branches for each branch listed in the distro map
+
+  Scenario: A user tries to clone a nonexistant remote repo
+    Given a nonexistant remote repo
+    And a nonexistant repo directory
+    When the user runs `asciibinder clone` on that repo directory
+    Then the program exits with a warning
+
+  Scenario: A user tries to clone a remote repo into an existing directory
+    Given an existing remote repo
+    And an existing repo directory
+    When the user runs `asciibinder clone` on that repo directory
+    Then the program exits with a warning
+
+  Scenario: A user tries to clone a remote repo into a nonexistant directory
+    Given an existing remote repo
+    And a nonexistant repo directory
+    When the user runs `asciibinder clone` on that repo directory
+    Then the program clones the remote repo into the local directory

data/features/repo_create.feature

@@ -0,0 +1,13 @@
+Feature: asciibinder create
+
+  This command creates a new base docs repo to be managed by AsciiBinder
+
+  Scenario: A user tries to create a repo in an existing directory
+    Given an existing repo directory
+    When the user runs `asciibinder create` on that repo directory
+    Then the program exits with a warning
+
+  Scenario: A user tries to create a repo in a nonexistant directory
+    Given a nonexistant repo directory
+    When the user runs `asciibinder create` on that repo directory
+    Then the program generates a new base docs repo

data/features/repo_package.feature

@@ -0,0 +1,15 @@
+Feature: asciibinder package
+
+  Causes the utility to run a `build` operation and then marshall
+  together all of the distro / branch combinations that will be
+  published into "sites". Each site has a distinct home page.
+
+  Scenario: A user wants to package all of the sites contained in their docs repo
+    Given a valid AsciiBinder docs repo with multiple distros
+    When the user runs `asciibinder package` on that repo directory
+    Then the program generates a site directory for each site in the distro map
+
+  Scenario: A user wants to package one of the sites contained in their docs repo
+    Given a valid AsciiBinder docs repo with multiple distros
+    When the user runs `asciibinder package --site=test` on that repo directory
+    Then the program generates a site directory for only the `test` site in the distro map

data/features/step_definitions/steps.rb

@@ -0,0 +1,182 @@
+require 'ascii_binder/version'
+require 'cucumber'
+require 'fileutils'
+require 'open3'
+require 'diff_dirs'
+
+Given(/^an existing repo directory$/) do
+  Dir.mkdir(working_dir)
+end
+
+Given(/^a nonexistant repo directory$/) do
+  working_dir
+end
+
+Given(/^a valid AsciiBinder docs repo(.*)$/) do |repo_condition|
+  multiple_distros = false
+  offset_docs_root = false
+  if repo_condition == ' with multiple distros'
+    multiple_distros = true
+  elsif repo_condition == ' where the docs root is not at the repo root'
+    multiple_distros = true
+    offset_docs_root = true
+  end
+  initialize_test_repo(true,multiple_distros,offset_docs_root)
+end
+
+Given(/^an invalid AsciiBinder docs repo(.*)$/) do |invalid_condition|
+  if invalid_condition == ' due to a malformed distro map'
+    initialize_test_repo(true,true)
+    invalidate_distro_map
+  else
+    initialize_test_repo(false)
+  end
+end
+
+Given(/^the docs repo contains generated content$/) do
+  output    = run_command('package')
+  has_error = false
+  [preview_dir,package_dir].each do |subdir|
+    unless Dir.exist?(subdir)
+      puts "ERROR: expected directory '#{subdir}' was not created."
+      has_error = true
+    end
+    unless Dir.entries(subdir).select{ |item| not ['.','..'].include?(item) }.length > 0
+      puts "ERROR: directory '#{subdir}' is empty."
+      has_error = true
+    end
+  end
+  if has_error
+    print_output(output)
+    exit 1
+  end
+end
+
+Given(/^the docs repo contains no generated content$/) do
+  [preview_dir,package_dir].each do |subdir|
+    next unless Dir.exist?(subdir)
+    FileUtils.rm_rf(subdir)
+  end
+end
+
+Given(/^a nonexistant remote repo$/) do
+  @remote_repo_url = 'http://example.com/repo.git'
+end
+
+Given(/^an existing remote repo$/) do
+  # We're going to set up a local repo as a remote.
+  @remote_repo_dir = initialize_remote_repo
+  @remote_repo_url = "file://#{@remote_repo_dir}"
+end
+
+When(/^the user runs `asciibinder (.+)` on that (.+) directory$/) do |command_string,target_dir|
+  @command_args = command_string.split(' ')
+  run_dir = target_dir == 'docs root' ? File.join(working_dir,'docs') : working_dir
+  command = @command_args.shift
+  if command == 'clone'
+    @step_output = run_command(command,["-d #{working_dir}"],@remote_repo_url)
+  else
+    @step_output = run_command(command,@command_args,run_dir)
+  end
+end
+
+Then(/^the generated content is removed$/) do
+  has_error = false
+  [preview_dir,package_dir].each do |subdir|
+    unless Dir.exist?(subdir)
+      puts "ERROR: expected to find directory '#{subdir}' but didn't"
+      has_error = true
+    end
+    unless Dir.entries(subdir).select{ |item| not ['.','..'].include?(item) }.length == 0
+      puts "ERROR: expected directory '#{subdir}' to be empty"
+      has_error
+    end
+  end
+  if has_error
+    print_output(@step_output)
+    exit 1
+  end
+end
+
+Then(/^the program exits without errors$/) do
+  status_check(@step_output,'running `asciibinder clean`.')
+end
+
+Then(/^the program exits with a warning$/) do
+  if @step_output[:status].exitstatus == 0
+    puts "ERROR: testing `asciibinder clean`; expected an exit code other than 0."
+    print_output(@step_output)
+    exit 1
+  end
+end
+
+Then(/^the program clones the remote repo into the local directory$/) do
+  diffs           = diff_dirs(@remote_repo_dir, working_dir)
+  non_git_diffs   = diffs.select{ |entry| not entry[1].start_with?('.git') }
+  remote_branches = Git.open(@remote_repo_dir).branches.local.map{ |branch| branch.name }.sort
+  local_branches  = Git.open(working_dir).branches.local.map{ |branch| branch.name }.sort
+  branch_matches  = remote_branches & local_branches
+  unless branch_matches.length == local_branches.length and non_git_diffs.length == 0
+    puts "ERROR: cloned repo doesn't match remote repo."
+    exit 1
+  end
+end
+
+Then(/^the program generates a new base docs repo$/) do
+  diffs = diff_dirs(repo_template_dir, working_dir)
+  unless diffs.length == 1 and diffs[0][0] == :new and diffs[0][1] == '.git'
+    puts "ERROR: template repo copy produced differences - #{diffs.inspect}"
+    exit 1
+  end
+end
+
+Then(/^the program displays help information$/) do
+  status_check(@step_output,'`asciibinder help` command failed.')
+  unless @step_output[:stderr] == '' and @step_output[:stdout].start_with?('Usage:')
+    puts "ERROR: unexpected help output"
+    print_output(@step_output)
+    exit 1
+  end
+end
+
+Then(/^the program prints the current version of the utility$/) do
+  status_check(@step_output,'`asciibinder version` command failed.')
+  unless @step_output[:stderr] == '' and @step_output[:stdout].chomp == AsciiBinder::VERSION
+    puts "ERROR: unexpected help output"
+    print_output(@step_output)
+    exit 1
+  end
+end
+
+Then(/^the program generates preview content for (.+)$/) do |build_target|
+  status_check(@step_output,'`asciibinder build` command failed.')
+  case build_target
+  when 'all distros in the current branch'
+    build_check(:default)
+  when 'only the `distro_test` distro'
+    distro = @command_args.select{ |arg| arg.starts_with?('--distro=') }.map{ |arg| arg.split('=')[1] }[0]
+    build_check(:distro,distro)
+  when 'all relevant distro/branch combos'
+    build_check(:all_branches)
+  when 'the specified page in all distros'
+    page = @command_args.select{ |arg| arg.starts_with?('--page=') }.map{ |arg| arg.split('=')[1] }[0]
+    build_check(:page,page)
+  else
+    puts "ERROR: unrecognized test case '#{build_target}'"
+    exit 1
+  end
+end
+
+Then(/^the program generates a site directory for (.+) in the distro map$/) do |package_target|
+  status_check(@step_output,'`asciibinder package` command failed.')
+  case package_target
+  when 'each site'
+    package_check()
+  when 'only the `test` site'
+    site = @command_args.select{ |arg| arg.starts_with?('--site=') }.map{ |arg| arg.split('=')[1] }[0]
+    package_check(site)
+  else
+    puts "ERROR: unrecognized test case '#{build_target}'"
+    exit 1
+  end
+end