ascii_binder_gabriel_rh 0.0.1

data/lib/ascii_binder_gabriel_rh/helpers.rb

@@ -0,0 +1,172 @@
+require 'logger'
+require 'stringio'
+
+module AsciiBinderGabrielRH
+  module Helpers
+    BUILD_FILENAME      = '_build_cfg.yml'
+    TOPIC_MAP_FOLDER    = '_topic_maps'
+    TOPIC_MAP_FILENAME  = '_topic_map.yml'
+    DISTRO_MAP_FILENAME = '_distro_map.yml'
+    PREVIEW_DIRNAME     = '_preview'
+    PACKAGE_DIRNAME     = '_package'
+    STYLESHEET_DIRNAME  = '_stylesheets'
+    JAVASCRIPT_DIRNAME  = '_javascripts'
+    IMAGE_DIRNAME       = '_images'
+    BLANK_STRING_RE     = Regexp.new('^\s*$')
+    ID_STRING_RE        = Regexp.new('^[A-Za-z0-9\-\_]+$')
+    URL_STRING_RE       = Regexp.new('^https?:\/\/[\S]+$')
+
+    def valid_id?(check_id)
+      return false unless check_id.is_a?(String)
+      return false unless check_id.match ID_STRING_RE
+      return true
+    end
+
+    def valid_string?(check_string)
+      return false unless check_string.is_a?(String)
+      return false unless check_string.length > 0
+      return false if check_string.match BLANK_STRING_RE
+      return true
+    end
+
+    def valid_url?(check_string)
+      return false unless valid_string?(check_string)
+      return false unless check_string.match URL_STRING_RE
+      return true
+    end
+
+    def camelize(text)
+      text.gsub(/[^0-9a-zA-Z ]/i, '').split(' ').map{ |t| t.capitalize }.join
+    end
+
+    def git_root_dir
+      @git_root_dir ||= `git rev-parse --show-toplevel`.chomp
+    end
+
+    def gem_root_dir
+      @gem_root_dir ||= File.expand_path("../../../", __FILE__)
+    end
+
+    def set_docs_root_dir(docs_root_dir)
+      AsciiBinderGabrielRH.const_set("DOCS_ROOT_DIR", docs_root_dir)
+    end
+
+    def docs_root_dir
+      AsciiBinderGabrielRH::DOCS_ROOT_DIR
+    end
+
+    def set_depth(user_depth)
+      AsciiBinderGabrielRH.const_set("DEPTH", user_depth)
+    end
+
+    def set_log_level(user_log_level)
+      AsciiBinderGabrielRH.const_set("LOG_LEVEL", log_levels[user_log_level])
+    end
+
+    def log_levels
+      @log_levels ||= {
+        :debug => Logger::DEBUG.to_i,
+        :error => Logger::ERROR.to_i,
+        :fatal => Logger::FATAL.to_i,
+        :info  => Logger::INFO.to_i,
+        :warn  => Logger::WARN.to_i,
+      }
+    end
+
+    def logerr
+      @logerr ||= begin
+        logger = Logger.new(STDERR, level: AsciiBinderGabrielRH::LOG_LEVEL)
+        logger.formatter = proc do |severity, datetime, progname, msg|
+          "#{severity}: #{msg}\n"
+        end
+        logger
+      end
+    end
+
+    def logstd
+      @logstd ||= begin
+        logger = Logger.new(STDOUT, level: AsciiBinderGabrielRH::LOG_LEVEL)
+        logger.formatter = proc do |severity, datetime, progname, msg|
+          severity == 'ANY' ? "#{msg}\n" : "#{severity}: #{msg}\n"
+        end
+        logger
+      end
+    end
+
+    def log_info(text)
+      logstd.info(text)
+    end
+
+    def log_warn(text)
+      logstd.warn(text)
+    end
+
+    def log_error(text)
+      logerr.error(text)
+    end
+
+    def log_fatal(text)
+      logerr.fatal(text)
+    end
+
+    def log_debug(text)
+      logstd.debug(text)
+    end
+
+    def log_unknown(text)
+      logstd.unknown(text)
+    end
+
+    def without_warnings
+      verboseness_level = $VERBOSE
+      $VERBOSE = nil
+      yield
+    ensure
+      $VERBOSE = verboseness_level
+    end
+
+    def template_renderer
+      @template_renderer ||= TemplateRenderer.new(docs_root_dir, template_dir)
+    end
+
+    def template_dir
+      @template_dir ||= File.join(docs_root_dir,'_templates')
+    end
+
+    def preview_dir
+      @preview_dir ||= begin
+        lpreview_dir = File.join(docs_root_dir,PREVIEW_DIRNAME)
+        if not File.exists?(lpreview_dir)
+          Dir.mkdir(lpreview_dir)
+        end
+        lpreview_dir
+      end
+    end
+
+    def package_dir
+      @package_dir ||= begin
+        lpackage_dir = File.join(docs_root_dir,PACKAGE_DIRNAME)
+        if not File.exists?(lpackage_dir)
+          Dir.mkdir(lpackage_dir)
+        end
+        lpackage_dir
+      end
+    end
+
+    def stylesheet_dir
+      @stylesheet_dir ||= File.join(docs_root_dir,STYLESHEET_DIRNAME)
+    end
+
+    def javascript_dir
+      @javascript_dir ||= File.join(docs_root_dir,JAVASCRIPT_DIRNAME)
+    end
+
+    def image_dir
+      @image_dir ||= File.join(docs_root_dir,IMAGE_DIRNAME)
+    end
+
+    def alias_text(target)
+      "<!DOCTYPE html><html><head><title>#{target}</title><link rel=\"canonical\" href=\"#{target}\"/><meta name=\"robots\" content=\"noindex\"><meta http-equiv=\"content-type\" content=\"text/html; charset=utf-8\" /><meta http-equiv=\"refresh\" content=\"0; url=#{target}\" /></head></html>"
+    end
+  end
+end

data/lib/ascii_binder_gabriel_rh/site.rb

@@ -0,0 +1,52 @@
+require 'ascii_binder_gabriel_rh/helpers'
+
+include AsciiBinderGabrielRH::Helpers
+
+module AsciiBinderGabrielRH
+  class Site
+    attr_reader :id, :name, :url
+
+    def initialize(distro_config)
+      @id   = distro_config['site']
+      @name = distro_config['site_name']
+      @url  = distro_config['site_url']
+    end
+
+    def is_valid?
+      validate
+    end
+
+    def errors
+      validate(true)
+    end
+
+    private
+
+    def validate(verbose=false)
+      errors = []
+      unless valid_id?(@id)
+        if verbose
+          errors << "Site ID '#{@id}' is not a valid ID."
+        else
+          return false
+        end
+      end
+      unless valid_string?(@name)
+        if verbose
+          errors << "Site name '#{@name}' for site ID '#{@id}' is not a valid string."
+        else
+          return false
+        end
+      end
+      unless valid_string?(@url)
+        if verbose
+          errors << "Site URL '#{@url}' for site ID '#{@id}' is not a valid string."
+        else
+          return false
+        end
+      end
+      return errors if verbose
+      return true
+    end
+  end
+end

data/lib/ascii_binder_gabriel_rh/site_info.rb

@@ -0,0 +1,22 @@
+module AsciiBinderGabrielRH
+  class SiteInfo
+    attr_reader :id, :name, :url, :distros, :branches
+
+    def initialize(distro)
+      @id       = distro.site.id
+      @name     = distro.site.name
+      @url      = distro.site.url
+      @distros  = {}
+      @branches = ['main']
+      add_distro(distro)
+    end
+
+    def add_distro(distro)
+      @distros[distro.id] = distro.branches
+      distro.branches.each do |branch|
+        next if @branches.include?(branch.id)
+        @branches << branch.id
+      end
+    end
+  end
+end

data/lib/ascii_binder_gabriel_rh/site_map.rb

@@ -0,0 +1,24 @@
+require 'ascii_binder_gabriel_rh/site_info'
+
+module AsciiBinderGabrielRH
+  class SiteMap
+    def initialize(distro_map)
+      @site_map = {}
+      distro_map.distros.each do |distro|
+        unless @site_map.has_key?(distro.site.id)
+          @site_map[distro.site.id] = AsciiBinderGabrielRH::SiteInfo.new(distro)
+        else
+          @site_map[distro.site.id].add_distro(distro)
+        end
+      end
+    end
+
+    def sites
+      return @site_map.values
+    end
+
+    def ids
+      return @site_map.keys
+    end
+  end
+end

data/lib/ascii_binder_gabriel_rh/tasks/guards.rb

@@ -0,0 +1,15 @@
+guard 'shell' do
+  watch(/^.*\.adoc$/) { |m|
+    if not m[0].start_with?('_preview') and not m[0].start_with?('_package')
+      full_path      = m[0].split('/')
+      src_group_path = full_path.length == 1 ? '' : full_path[0..-2].join('/')
+      filename       = full_path[-1][0..-6]
+      system("asciibinder build --page='#{src_group_path}:#{filename}'")
+    end
+  }
+end
+
+guard 'livereload' do
+  watch(%r{^_preview/.+\.(css|js|html)$})
+  watch(%r{^_preview/.+\/.+\/.+\.(css|js|html)$})
+end

data/lib/ascii_binder_gabriel_rh/tasks/tasks.rb

@@ -0,0 +1,41 @@
+require 'rake'
+require 'ascii_binder_gabriel_rh'
+
+include AsciiBinderGabrielRH::Engine
+include AsciiBinderGabrielRH::Helpers
+
+desc "Build the documentation"
+task :build, :build_distro do |task,args|
+  # Figure out which distros we are building.
+  # A blank value here == all distros
+  set_docs_root_dir(git_root_dir)
+  set_log_level(:warn)
+  build_distro = args[:build_distro] || ''
+  generate_docs(:all,build_distro,nil)
+end
+
+desc "Package the documentation"
+task :package, :package_site do |task,args|
+  set_docs_root_dir(git_root_dir)
+  set_log_level(:warn)
+  package_site = args[:package_site] || ''
+  Rake::Task["clean"].invoke
+  Rake::Task["build"].invoke
+  package_docs(package_site)
+end
+
+desc "Build the documentation and refresh the page"
+task :refresh_page, :single_page do |task,args|
+  set_docs_root_dir(git_root_dir)
+  set_log_level(:warn)
+  generate_docs(:working_only,'',args[:single_page])
+end
+
+desc "Clean all build artifacts"
+task :clean do
+  sh "rm -rf _preview/* _package/*" do |ok,res|
+    if ! ok
+      puts "Nothing to clean."
+    end
+  end
+end

data/lib/ascii_binder_gabriel_rh/template_renderer.rb

@@ -0,0 +1,29 @@
+require 'tilt'
+
+module AsciiBinderGabrielRH
+  class TemplateRenderer
+    attr_reader :source_dir, :template_cache
+
+    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)
+      template_cache.fetch(File.expand_path(template))
+    end
+  end
+end

data/lib/ascii_binder_gabriel_rh/topic_entity.rb

@@ -0,0 +1,324 @@
+require 'ascii_binder_gabriel_rh/helpers'
+require 'trollop'
+
+include AsciiBinderGabrielRH::Helpers
+
+module AsciiBinderGabrielRH
+  class TopicEntity
+    attr_reader :name, :dir, :file, :topic_alias, :distro_keys, :subitems, :raw, :parent, :depth
+
+    def initialize(topic_entity,actual_distro_keys,dir_path='',parent_group=nil,depth=0)
+      @raw                = topic_entity
+      @parent             = parent_group
+      @dir_path           = dir_path
+      @name               = topic_entity['Name']
+      @dir                = topic_entity['Dir']
+      @file               = topic_entity['File']
+      @topic_alias        = topic_entity['Alias']
+      @depth              = depth
+      @actual_distro_keys = actual_distro_keys
+      @distro_keys        = topic_entity.has_key?('Distros') ? parse_distros(topic_entity['Distros']) : actual_distro_keys
+      @nav_trees          = {}
+      @alias_lists        = {}
+      @path_lists         = {}
+      @subitems           = []
+      if topic_entity.has_key?('Topics')
+        entity_dir  = @dir.nil? ? '<nil_dir>' : @dir
+        subdir_path = dir_path == '' ? entity_dir : File.join(dir_path,entity_dir)
+        topic_entity['Topics'].each do |sub_entity|
+          @subitems << AsciiBinderGabrielRH::TopicEntity.new(sub_entity,actual_distro_keys,subdir_path,self,depth+1)
+        end
+      end
+    end
+
+    def repo_path
+      @repo_path ||= begin
+        this_step = '<nil_item>'
+        if is_group?
+          this_step = dir
+        elsif is_topic?
+          this_step = file.end_with?('.adoc') ? file : "#{file}.adoc"
+        end
+        @dir_path == '' ? this_step : File.join(@dir_path,this_step)
+      end
+    end
+
+    def basename_path
+      @basename_path ||= File.join(File.dirname(repo_path),File.basename(repo_path,'.adoc'))
+    end
+
+    def repo_path_html
+      @repo_path_html ||= is_topic? ? File.join(File.dirname(repo_path),File.basename(repo_path,'.adoc')) + ".html" : repo_path
+    end
+
+    def source_path
+      @source_path ||= File.join(docs_root_dir,repo_path)
+    end
+
+    def preview_path(distro_key,branch_dir)
+      File.join(preview_dir,distro_key,branch_dir,repo_path_html)
+    end
+
+    def topic_publish_url(distro_url,branch_dir)
+      File.join(distro_url,branch_dir,repo_path_html)
+    end
+
+    def package_path(site_id,branch_dir)
+      File.join(package_dir,site_id,branch_dir,repo_path_html)
+    end
+
+    def group_filepaths
+      @group_filepaths ||= begin
+        group_filepaths = []
+        if is_topic? and not is_alias?
+          group_filepaths << File.join(File.dirname(repo_path),File.basename(repo_path,'.adoc'))
+        elsif is_group?
+          subitems.each do |subitem|
+            group_filepaths.concat(subitem.group_filepaths)
+          end
+          group_filepaths.uniq!
+        end
+        group_filepaths
+      end
+    end
+
+    def nav_tree(distro_key)
+      @nav_trees[distro_key] ||= begin
+        nav_tree = {}
+        if distro_keys.include?(distro_key) and not is_alias?
+          nav_tree[:id]   = id
+          nav_tree[:name] = name
+          if is_topic?
+            nav_tree[:path] = "../" + repo_path_html
+          elsif is_group?
+            sub_nav_items = []
+            subitems.each do |subitem|
+              sub_nav = subitem.nav_tree(distro_key)
+              next if sub_nav.empty?
+              sub_nav_items << sub_nav
+            end
+            if sub_nav_items.empty?
+              nav_tree = {}
+            else
+              nav_tree[:topics] = sub_nav_items
+            end
+          end
+        end
+        nav_tree
+      end
+    end
+
+    def alias_list(distro_key)
+      @alias_lists[distro_key] ||= begin
+        sub_aliases = []
+        if distro_keys.include?(distro_key)
+          if is_group?
+            subitems.each do |subitem|
+              sub_list = subitem.alias_list(distro_key)
+              sub_list.each do |sub_list_alias|
+                sub_aliases << sub_list_alias
+              end
+            end
+          elsif is_alias?
+            sub_aliases << { :alias_path => basename_path, :redirect_path => topic_alias }
+          end
+        end
+        sub_aliases
+      end
+    end
+
+    def path_list(distro_key)
+      @path_lists[distro_key] ||= begin
+        sub_paths = []
+        if distro_keys.include?(distro_key)
+          if is_group?
+            subitems.each do |subitem|
+              sub_list = subitem.path_list(distro_key)
+              sub_list.each do |sub_list_path|
+                sub_paths << sub_list_path
+              end
+            end
+          elsif is_topic? and not is_alias?
+            sub_paths << basename_path
+          end
+        end
+        sub_paths
+      end
+    end
+
+    # Is this topic entity or any of its children used in
+    # the specified distro / single page chain
+    def include?(distro_key,single_page_path)
+      # If this entity isn't for this distro, bail out
+      return false unless distro_keys.include?(distro_key)
+
+      # If we're building a single page, check if we're on the right track.
+      if single_page_path.length > 0  and not single_page_path[depth].nil?
+        if is_group?
+          return false unless single_page_path[depth] == dir
+        elsif is_topic?
+          return false unless single_page_path[depth] == file
+        else
+          return false
+        end
+      elsif is_group?
+        # If this is a topic group that -is- okay for this distro, but
+        # none of its subitems are okay for this distro, then bail out.
+        subitems_for_distro = false
+        subitems.each do |subitem|
+          if subitem.include?(distro_key,[])
+            subitems_for_distro = true
+            break
+          end
+        end
+        return false unless subitems_for_distro
+      end
+
+      return true
+    end
+
+    def breadcrumb
+      @breadcrumb ||= hierarchy.map{ |entity| { :id => entity.id, :name => entity.name, :url => entity.repo_path_html } }
+    end
+
+    def id
+      @id ||= hierarchy.map{ |entity| camelize(entity.name) }.join('::')
+    end
+
+    def is_group?
+      @is_group ||= file.nil? and not name.nil? and not dir.nil? and subitems.length > 0
+    end
+
+    def is_topic?
+      @is_topic ||= dir.nil? and not name.nil? and not file.nil? and subitems.length == 0
+    end
+
+    def is_alias?
+      @is_alias ||= is_topic? and not topic_alias.nil?
+    end
+
+    def is_valid?
+      validate
+    end
+
+    def errors
+      validate(true)
+    end
+
+    private
+
+    def parse_distros(entity_distros)
+      values = entity_distros.split(',').map(&:strip)
+      # Don't bother with glob expansion if 'all' is in the list.
+      return @actual_distro_keys if values.include?('all')
+
+      # Expand globs and return the list
+      values.flat_map do |value|
+        value_regex = Regexp.new("\\A#{value.gsub("*", ".*")}\\z")
+        @actual_distro_keys.select { |k| value_regex.match(k) }
+      end.uniq
+    end
+
+    def validate(verbose=false)
+      errors = []
+
+      # Check common fields - Name and Distros
+      if not valid_string?(name)
+        if verbose
+          errors << "Topic entity with missing or invalid 'Name' value: '#{raw.inspect}'"
+        else
+          return false
+        end
+      end
+      distro_keys.each do |distro_key|
+        next if @actual_distro_keys.include?(distro_key)
+        if verbose
+          errors << "#{entity_id} 'Distros' filter includes nonexistent distro key '#{distro_key}'"
+        else
+          return false
+        end
+      end
+
+      # Check the depth.
+      if (depth > AsciiBinderGabrielRH::DEPTH) and (AsciiBinderGabrielRH::DEPTH != 0)
+        if verbose
+          errors << "#{entity_id} exceeds the maximum nested depth."
+        else
+          return false
+        end
+      end
+
+      # For groups, test the 'Dir' value and the sub-items.
+      if is_group?
+        if not valid_string?(dir)
+          if verbose
+            errors << "#{entity_id} has invalid 'Dir' value."
+          else
+            return false
+          end
+        end
+        if not topic_alias.nil?
+          if verbose
+            errors << "#{entity_id} is a topic group with an Alias entry. Aliases are only supported for topic items."
+          else
+            return false
+          end
+        end
+        subitems.each do |subitem|
+          next if subitem.is_valid?
+          if verbose
+            errors = errors.concat(subitem.errors)
+          else
+            return false
+          end
+        end
+      elsif is_topic?
+        if not valid_string?(file)
+          if verbose
+            errors << "#{entity_id} has invalid 'File' value."
+          else
+            return false
+          end
+        end
+        # We can do basic validation of the 'Alias' string here, but real validation has
+        # to be done after the whole topic map is loaded.
+        if not topic_alias.nil? and not valid_string?(topic_alias)
+          if verbose
+            errors << "#{entity_id} has invalid 'Alias' value."
+          else
+            return false
+          end
+        end
+      else
+        if verbose
+          errors << "#{entity_id} is not parseable as a group or a topic: '#{raw.inspect}'"
+        else
+          return false
+        end
+      end
+      return errors if verbose
+      return true
+    end
+
+    def hierarchy
+      @hierarchy ||= begin
+        entity   = self
+        ancestry = []
+        loop do
+          ancestry << entity
+          break if entity.parent.nil?
+          entity = entity.parent
+        end
+        ancestry.reverse
+      end
+    end
+
+    def entity_id
+      if hierarchy.length == 1
+        return "Top level topic entity '#{name}'"
+      else
+        return "Topic entity at '#{breadcrumb.map{ |node| node[:name] }.join(' -> ')}'"
+      end
+    end
+  end
+end