ascii_binder 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 01e8b7c8975f779411765ecd4db541dbbda03745
-  data.tar.gz: 9daf86717b278c2b10c6e59c0b554641fc1f9127
+  metadata.gz: 6fff45d8fcc35d2040f7f230045cabeeac556192
+  data.tar.gz: 61fa8923622f4aa924de6fab5c2cd47bcacc384b
 SHA512:
-  metadata.gz: 0e955da364eb1b81d49415c5b000b0cf06a83ad699e5085e5a72918b45a51f4f263cdcaf3871f6290198b2fd3d57603dc6558a5c577782d2d9c08d8e5c206ade
-  data.tar.gz: 6238794ecb04f36e2d65d30b06a3ec7c6b5e6a036d55051b2cc7726a389fa628ee14547a7942d88be007e44654329f7febda8f6493b13c171f99594cb80530c1
+  metadata.gz: f54679707ec775f4863468e85458960c1a5786b5d297be87bc704812f06dae8ec1744bc94217719293d97703cf99bd1d6d34760166def138effda3c0a0c9088d
+  data.tar.gz: 9afc02f88169c7e8790c8e9b6819c55d0283197f96e2801b54662d4f77aa8bd68d036bf2ef4c34778d57bf74eced650c340486ce726107bc2ca3d3be1c46ec9c

data/Dockerfile

@@ -0,0 +1,18 @@
+FROM centos/ruby-22-centos7
+
+RUN scl enable rh-ruby22 -- gem install ascii_binder
+USER root
+RUN yum install -y java-1.7.0-openjdk && \
+    yum clean all
+
+LABEL url="http://www.asciibinder.org" \
+      summary="a documentation system built on Asciidoctor" \
+      description="AsciiBinder is for documenting versioned, interrelated projects. Run this container image from the documentation repository, which is mounted into the container. Note: Generated files will be owned by root." \
+      RUN="docker run -it --rm \
+          -v `pwd`:/docs:z \
+          IMAGE"
+
+ENV JAVA_HOME=/usr/lib/jvm/java-1.7.0-openjdk-1.7.0.95-2.6.4.0.el7_2.x86_64/jre/
+ENV LANG=en_US.UTF-8
+WORKDIR /docs
+CMD asciibinder package

data/bin/ascii_binder

@@ -7,23 +7,33 @@ require 'trollop'
 
 include AsciiBinder::Helpers
 
-def call_generate(distro,page=nil)
+def call_generate(branch_group, distro, page)
   if page == ''
     page = nil
   end
   begin
-    generate_docs(distro,page)
-  rescue Exception => e
-    Trollop::die "Could not generate docs: #{e.message}"
+    generate_docs(branch_group, distro, page)
+  rescue => e
+    message = "#{e.class.name}: #{e.message} at\n    #{e.backtrace.join("\n    ")}"
+    Trollop::die "Could not generate docs:\n#{message}"
   end
 end
 
 def repo_check(repo_dir)
-  ['.git','_build_cfg.yml','_distro_map.yml','_templates'].each do |file|
+  missing_files = false
+  # These must all be present
+  ['.git','_distro_map.yml','_templates'].each do |file|
     unless File.exist?(File.join(repo_dir, file))
-      Trollop::die "The specified repo directory '#{repo_dir}' does not appear to be an AsciiBinder repo."
+      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'))
+    missing_files = true
+  end
+  if missing_files
+    Trollop::die "The specified repo directory '#{repo_dir}' does not appear to be an AsciiBinder repo."
+  end
 end
 
 SUB_COMMANDS = %w{help version build watch package clean create clone}
@@ -82,13 +92,20 @@ Description:
   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.
+  If you use the --all_branches flag, AsciiBinder behaves as described
+  above, and then 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.
+
+  If you want to limit the scope of the build work for faster builds,
+  you have two targeted options:
+
+  --distro=<distro_key> - Only builds the specified distro and branches
+  associated with this distro.
+
+  --page=<page_path> - Only builds the specified page for all distros.
 
-  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:
+  Note that the format for the "--page" option is:
 
   <topic_group>:<topic_file>
 
@@ -98,10 +115,11 @@ Description:
 
   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.
+  automatically as you change any .adoc files in your working branch.
 
 Options:
 EOF
+      opt :all_branches, "Instead of building only the current working branch, build all branches", :default => false
       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
@@ -267,12 +285,13 @@ end
 # Do the things with the stuff
 case cmd
 when "build"
-  build_distro = cmd_opts[:build] || ''
-  refresh_page = cmd_opts[:page] || ''
-  call_generate(build_distro,refresh_page)
+  branch_group = cmd_opts[:all_branches] ? :all : :working_only
+  build_distro = cmd_opts[:distro] || ''
+  refresh_page = cmd_opts[:page] || nil
+  call_generate(branch_group,build_distro,refresh_page)
 when "package"
   clean_up
-  call_generate('')
+  call_generate(:publish,'',nil)
   package_site = cmd_opts[:site] || ''
   package_docs(package_site)
 when "watch"

data/bin/asciibinder

@@ -7,23 +7,33 @@ require 'trollop'
 
 include AsciiBinder::Helpers
 
-def call_generate(distro,page=nil)
+def call_generate(branch_group, distro, page)
   if page == ''
     page = nil
   end
   begin
-    generate_docs(distro,page)
-  rescue Exception => e
-    Trollop::die "Could not generate docs: #{e.message}"
+    generate_docs(branch_group, distro, page)
+  rescue => e
+    message = "#{e.class.name}: #{e.message} at\n    #{e.backtrace.join("\n    ")}"
+    Trollop::die "Could not generate docs:\n#{message}"
   end
 end
 
 def repo_check(repo_dir)
-  ['.git','_build_cfg.yml','_distro_map.yml','_templates'].each do |file|
+  missing_files = false
+  # These must all be present
+  ['.git','_distro_map.yml','_templates'].each do |file|
     unless File.exist?(File.join(repo_dir, file))
-      Trollop::die "The specified repo directory '#{repo_dir}' does not appear to be an AsciiBinder repo."
+      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'))
+    missing_files = true
+  end
+  if missing_files
+    Trollop::die "The specified repo directory '#{repo_dir}' does not appear to be an AsciiBinder repo."
+  end
 end
 
 SUB_COMMANDS = %w{help version build watch package clean create clone}
@@ -82,13 +92,20 @@ Description:
   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.
+  If you use the --all_branches flag, AsciiBinder behaves as described
+  above, and then 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.
+
+  If you want to limit the scope of the build work for faster builds,
+  you have two targeted options:
+
+  --distro=<distro_key> - Only builds the specified distro and branches
+  associated with this distro.
+
+  --page=<page_path> - Only builds the specified page for all distros.
 
-  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:
+  Note that the format for the "--page" option is:
 
   <topic_group>:<topic_file>
 
@@ -98,10 +115,11 @@ Description:
 
   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.
+  automatically as you change any .adoc files in your working branch.
 
 Options:
 EOF
+      opt :all_branches, "Instead of building only the current working branch, build all branches", :default => false
       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
@@ -267,12 +285,13 @@ end
 # Do the things with the stuff
 case cmd
 when "build"
-  build_distro = cmd_opts[:build] || ''
-  refresh_page = cmd_opts[:page] || ''
-  call_generate(build_distro,refresh_page)
+  branch_group = cmd_opts[:all_branches] ? :all : :working_only
+  build_distro = cmd_opts[:distro] || ''
+  refresh_page = cmd_opts[:page] || nil
+  call_generate(branch_group,build_distro,refresh_page)
 when "package"
   clean_up
-  call_generate('')
+  call_generate(:publish,'',nil)
   package_site = cmd_opts[:site] || ''
   package_docs(package_site)
 when "watch"

data/lib/ascii_binder/helpers.rb

@@ -71,8 +71,8 @@ module AsciiBinder
     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'
+    TOPIC_MAP_FILENAME  = '_topic_map.yml'
     DISTRO_MAP_FILENAME = '_distro_map.yml'
-    BUILDER_DIRNAME     = '_build_system'
     PREVIEW_DIRNAME     = '_preview'
     PACKAGE_DIRNAME     = '_package'
     STYLESHEET_DIRNAME  = '_stylesheets'
@@ -133,7 +133,14 @@ module AsciiBinder
     end
 
     def build_config_file
-      @build_config_file ||= File.join(source_dir,BUILD_FILENAME)
+      use_file = TOPIC_MAP_FILENAME
+      unless File.exist?(File.join(source_dir,TOPIC_MAP_FILENAME))
+        # The new filename '_topic_map.yml' couldn't be found;
+        # switch to the old one and warn the user.
+        use_file = BUILD_FILENAME
+        puts "WARNING: '#{BUILD_FILENAME}' is a deprecated filename. Rename this to '#{TOPIC_MAP_FILENAME}'."
+      end
+      use_file
     end
 
     def distro_map_file
@@ -146,18 +153,14 @@ module AsciiBinder
 
     # 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)))
+      validate_config(YAML.load_stream(open(File.join(source_dir,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
+      FileUtils.mkdir_p(source_dir)
 
       # Copy the basic repo content into the new repo dir
       Find.find(gem_template_dir).each do |path|
@@ -171,13 +174,8 @@ module AsciiBinder
         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
+      # Initialize the git repo
+      Git.init(source_dir)
     end
 
     def find_topic_files
@@ -217,7 +215,7 @@ module AsciiBinder
         end
       end
       if nonexistent_topics.length > 0
-        puts "\nWARNING: The _build_cfg.yml file on branch '#{branch}' references nonexistant topics:\n" + nonexistent_topics.map{ |topic| "- #{topic}" }.join("\n")
+        puts "\nWARNING: The #{build_config_file} file on branch '#{branch}' references nonexistant topics:\n" + nonexistent_topics.map{ |topic| "- #{topic}" }.join("\n")
       end
     end
 
@@ -237,9 +235,17 @@ module AsciiBinder
     end
 
     def distro_branches(use_distro='')
-      @distro_branches ||= begin
-        use_distro_list = use_distro == '' ? distro_map.keys : [use_distro]
-        distro_map.select{ |dkey,dval| use_distro_list.include?(dkey) }.map{ |distro,dconfig| dconfig["branches"].keys }.flatten
+      use_distro_list = use_distro == '' ? distro_map.keys : [use_distro]
+      distro_map.select{ |dkey,dval| use_distro_list.include?(dkey) }.map{ |distro,dconfig| dconfig["branches"].keys }.flatten
+    end
+
+    def branch_group_branches
+      @branch_group_branches ||= begin
+        group_branches = Hash.new
+        group_branches[:working_only] = [local_branches[0]]
+        group_branches[:publish] = distro_branches
+        group_branches[:all] = local_branches
+        group_branches
       end
     end
 
@@ -468,7 +474,7 @@ module AsciiBinder
       ].concat(more_attrs)
     end
 
-    def generate_docs(build_distro,single_page=nil)
+    def generate_docs(branch_group,build_distro,single_page)
       # 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?
@@ -507,8 +513,11 @@ module AsciiBinder
         puts "The build will proceed but these branches will not be generated."
       end
 
-      # Generate all distros for every local branch
-      local_branches.each do |local_branch|
+      # Generate all distros for all branches in the indicated branch group
+      branch_group_branches[branch_group].each do |local_branch|
+        # Skip known missing branches; this will only come up for the :publish branch group
+        next if missing_branches.include?(local_branch)
+
         # Single-page regen only occurs for the working branch
         if not local_branch == working_branch
           if single_page.nil?
@@ -537,14 +546,28 @@ module AsciiBinder
         remove_found_config_files(local_branch,branch_build_config,branch_orphan_files)
 
         if branch_orphan_files.length > 0 and single_page.nil?
-          puts "\nWARNING: Branch '#{local_branch}' includes the following .adoc files that are not referenced in the _build_cfg.yml file:\n" + branch_orphan_files.map{ |file| "- #{file}" }.join("\n")
+          puts "\nWARNING: Branch '#{local_branch}' includes the following .adoc files that are not referenced in the #{build_config_file} file:\n" + branch_orphan_files.map{ |file| "- #{file}" }.join("\n")
         end
 
         # Run all distros.
         distro_map.each do |distro,distro_config|
-          # Only building a single distro; skip the others.
-          if not build_distro == '' and not build_distro == distro
-            next
+          if not build_distro == ''
+            # Only building a single distro; build for all indicated branches, skip the others.
+            if not build_distro == distro
+              next
+            end
+          else
+            current_distro_branches = distro_branches(distro)
+
+            # In publish mode we only build "valid" distro-branch combos from the distro map
+            if branch_group == :publish and not current_distro_branches.include?(local_branch)
+              next
+            end
+
+            # In "build all" mode we build every distro on the working branch plus the publish distro-branch combos
+            if branch_group == :all and not local_branch == working_branch and not current_distro_branches.include?(local_branch)
+              next
+            end
           end
 
           site_name = distro_config["site_name"]
@@ -720,46 +743,48 @@ module AsciiBinder
         "product-author=#{distro_config["author"]}"
       ])
 
-    # Because we render only the body of the article with AsciiDoctor, the full article title
-    # would be lost in conversion. So, use the _build_cfg.yml 'Name' as a fallback but try
-    # to read the full article title out of the file itself.
-    file_lines    = topic_adoc.split("\n")
-    article_title = topic['Name']
-    if file_lines.length > 0
-      article_title  = file_lines[0].gsub(/^\=\s+/, '').gsub(/\s+$/, '').gsub(/\{product-title\}/, distro_config["name"]).gsub(/\{product-version\}/, branch_config["name"])
-    end
-    topic_adoc = file_lines.join("\n")
-
-    topic_html = Asciidoctor.render topic_adoc, :header_footer => false, :safe => :unsafe, :attributes => page_attrs
-    dir_depth  = ''
-    if branch_config['dir'].split('/').length > 1
-      dir_depth = '../' * (branch_config['dir'].split('/').length - 1)
-    end
-    if not topic_subgroup.nil?
-      dir_depth = '../' + dir_depth
-    end
-    page_args = {
-      :distro_key       => distro,
-      :distro           => distro_config["name"],
-      :site_name        => site_name,
-      :version          => branch_config["name"],
-      :group_title      => topic_group['Name'],
-      :subgroup_title   => topic_subgroup && topic_subgroup['Name'],
-      :topic_title      => topic['Name'],
-      :article_title    => article_title,
-      :content          => topic_html,
-      :navigation       => navigation,
-      :group_id         => topic_group['ID'],
-      :subgroup_id      => topic_subgroup && topic_subgroup['ID'],
-      :topic_id         => topic['ID'],
-      :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",
-      :template_path    => template_dir,
-    }
-    full_file_text = page(page_args)
-    File.write(tgt_file_path,full_file_text)
+      # Because we render only the body of the article with AsciiDoctor, the full article title
+      # would be lost in conversion. So, use the _build_cfg.yml 'Name' as a fallback but try
+      # to read the full article title out of the file itself.
+      file_lines    = topic_adoc.split("\n")
+      article_title = topic['Name']
+      if file_lines.length > 0
+        article_title  = file_lines[0].gsub(/^\=\s+/, '').gsub(/\s+$/, '').gsub(/\{product-title\}/, distro_config["name"]).gsub(/\{product-version\}/, branch_config["name"])
+      end
+      topic_adoc = file_lines.join("\n")
+
+      topic_html = Asciidoctor.render topic_adoc, :header_footer => false, :safe => :unsafe, :attributes => page_attrs
+      dir_depth  = ''
+      if branch_config['dir'].split('/').length > 1
+        dir_depth = '../' * (branch_config['dir'].split('/').length - 1)
+      end
+      if not topic_subgroup.nil?
+        dir_depth = '../' + dir_depth
+      end
+      page_args = {
+        :distro_key       => distro,
+        :distro           => distro_config["name"],
+        :site_name        => site_name,
+        :site_url         => distro_config["site_url"],
+        :topic_url        => "#{branch_config['dir']}/#{topic_path}.html",
+        :version          => branch_config["name"],
+        :group_title      => topic_group['Name'],
+        :subgroup_title   => topic_subgroup && topic_subgroup['Name'],
+        :topic_title      => topic['Name'],
+        :article_title    => article_title,
+        :content          => topic_html,
+        :navigation       => navigation,
+        :group_id         => topic_group['ID'],
+        :subgroup_id      => topic_subgroup && topic_subgroup['ID'],
+        :topic_id         => topic['ID'],
+        :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",
+        :template_path    => template_dir,
+      }
+      full_file_text = page(page_args)
+      File.write(tgt_file_path,full_file_text)
     end
 
     # package_docs

data/lib/ascii_binder/tasks/tasks.rb

@@ -8,7 +8,7 @@ task :build, :build_distro do |task,args|
   # Figure out which distros we are building.
   # A blank value here == all distros
   build_distro = args[:build_distro] || ''
-  generate_docs(build_distro)
+  generate_docs(:all,build_distro,nil)
 end
 
 desc "Package the documentation"
@@ -21,7 +21,7 @@ end
 
 desc "Build the documentation and refresh the page"
 task :refresh_page, :single_page do |task,args|
-  generate_docs('',args[:single_page])
+  generate_docs(:working_only,'',args[:single_page])
 end
 
 desc "Clean all build artifacts"

data/lib/ascii_binder/version.rb

@@ -1,3 +1,3 @@
 module AsciiBinder
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ascii_binder
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - N. Harrison Ripps
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-15 00:00:00.000000000 Z
+date: 2016-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -233,6 +233,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- Dockerfile
 - Gemfile
 - Guardfile
 - LICENSE.txt