liquidoc 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6066fed122738d3eb82ad92365208357bba0fc97
-  data.tar.gz: 55acbe02d698fea8c72ebaae61daa8f3a23584cc
+  metadata.gz: 680eeb03f5bdca5f09d010b37c2ba8a4fa2f7060
+  data.tar.gz: c5b06675ef4d7e2fcdcf5e0e1838295864edf094
 SHA512:
-  metadata.gz: 460472382d8369294a1857b16e1444610d540d5805ba95c7ceb72faa46962305720f45fdf7a9d5d65c724cfe541154a0cbf46853ca0a17d914dca62c9314ffac
-  data.tar.gz: d234c41558f62429e2d23f06bafc01bc9db7302933d9ca5e09f58b0d8679a0a5caf90c80a98564ddc053b47b3aae7ced2d1dd062887d7426747a508906759284
+  metadata.gz: 9658b656c88006e9fae3d16e35c00f12132f19a57fc963241650bc5a6b2849ce7efa4198f101c51f319f0b674936d624c29cd67ae5d292082cda773bebe5e77b
+  data.tar.gz: d63050fcd42fce26362c7cf9300a75f2a51213da2606e3cfb2fed84792b249c7b9a317da21120dc91194657124e11fdb1e9dc0a2378f0aa41f2046b2382d0f8c

data/lib/liquidoc/version.rb

@@ -1,3 +1,3 @@
 module Liquidoc
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/liquidoc.rb

@@ -9,6 +9,7 @@ require 'logger'
 require 'csv'
 require 'crack/xml'
 require 'fileutils'
+require 'jekyll'
 
 # ===
 # Table of Contents
@@ -32,6 +33,8 @@ require 'fileutils'
 
 @base_dir_def = Dir.pwd + '/'
 @base_dir = @base_dir_def
+@build_dir_def = @base_dir + '_build'
+@build_dir = @build_dir_def
 @configs_dir = @base_dir + '_configs'
 @templates_dir = @base_dir + '_templates/'
 @data_dir = @base_dir + '_data/'
@@ -43,12 +46,20 @@ require 'fileutils'
 @attributes = {}
 @passed_attrs = {}
 @verbose = false
+@quiet = false
+@explicit = false
 
+# Instantiate the main Logger object, which is always running
 @logger = Logger.new(STDOUT)
-@logger.level = Logger::INFO
 @logger.formatter = proc do |severity, datetime, progname, msg|
   "#{severity}: #{msg}\n"
 end
+@logger.level = Logger::INFO # suppresses DEBUG-level messages
+
+
+FileUtils::mkdir_p("#{@build_dir}") unless File.exists?("#{@build_dir}")
+FileUtils::mkdir_p("#{@build_dir}/pre") unless File.exists?("#{@build_dir}/pre")
+
 
 # ===
 # Executive procs
@@ -77,6 +88,7 @@ def iterate_build cfg
   for step in cfg.steps # iterate through each node in the 'config' object, which should start with an 'action' parameter
     stepcount = stepcount + 1
     step = BuildConfigStep.new(step) # create an instance of the Action class, validating the top-level step hash (now called 'step') in the process
+    @explainer.info step.message
     type = step.type
     case type # a switch to evaluate the 'action' parameter for each step in the iteration...
     when "parse"
@@ -85,7 +97,8 @@ def iterate_build cfg
       for bld in builds
         build = Build.new(bld, type) # create an instance of the Build class; Build.new accepts a 'bld' hash & action 'type'
         if build.template
-          liquify(data, build.template, build.output) # perform the liquify operation
+          @explainer.info build.message
+          liquify(data, build.template, build.output, build.variables) # perform the liquify operation
         else
           regurgidata(data, build.output)
         end
@@ -96,12 +109,14 @@ def iterate_build cfg
       copy_assets(step.source, step.target, inclusive)
     when "render"
       validate_file_input(step.source, "source") if step.source
-      doc = AsciiDocument.new(step.source)
-      attrs = ingest_attributes(step.data) if step.data # Set attributes in from YAML files
-      doc.add_attrs!(attrs) # Set attributes from the action-level data file
       builds = step.builds
       for bld in builds
+        doc = AsciiDocument.new(step.source)
+        attrs = ingest_attributes(step.data) if step.data # Set attributes from from YAML files
+        doc.add_attrs!(attrs) # Set attributes from the action-level data file
         build = Build.new(bld, type) # create an instance of the Build class; Build.new accepts a 'bld' hash & action 'type' string
+        build.set("backend", derive_backend(doc.type, build.output) ) unless build.backend
+        @explainer.info build.message
         render_doc(doc, build) # perform the render operation
       end
     when "deploy"
@@ -145,6 +160,27 @@ def validate_config_structure config
 # TODO More validation needed
 end
 
+def explainer_init out=nil
+  unless @explainer
+    if out == "STDOUT"
+      @explainer = Logger.new(STDOUT)
+    else
+      out = "#{@build_dir}/pre/config-explainer.adoc" if out.nil?
+      File.open(out, 'w') unless File.exists?(out)
+      file = File.open(out, File::WRONLY)
+      begin
+        @explainer = Logger.new(file)
+      rescue Exception => ex
+        @logger.error ex
+        raise "ExplainerCreateError"
+      end
+    end
+    @explainer.formatter = proc do |severity, datetime, progname, msg|
+      "#{msg}\n"
+    end
+  end
+end
+
 # ===
 # Core classes
 # ===
@@ -211,10 +247,59 @@ class BuildConfigStep
     return @step['options']
   end
 
+  def stage
+    return @step['stage']
+  end
+
   def builds
     return @step['builds']
   end
 
+  def message
+    # dynamically build a human-friendly log message, possibly appending a reason
+    unless @step['message']
+      reason = ", #{@step['reason']}" if @step['reason']
+      noninclusively = ", without carrying the parent directory" if self.options.is_a?(Hash) && self.options['inclusive'] == false && File.directory?(self.source)
+      stage = "" ; stage = "[#{self.stage}] " if self.stage
+      case self.type
+      when "migrate"
+        text = ". #{stage}Copies `#{self.source}` to `#{self.target}`#{noninclusively}#{reason}."
+      when "parse"
+        if self.data.is_a? Array
+          if self.data.count > 1
+            text = ". Draws data from the following files:"
+            self.data.each do |file|
+              text.concat("\n  * `#{file}`.")
+            end
+            text.concat("\n")
+          else
+            text = ". #{stage}Draws data from `#{self.data[0]}`"
+          end
+        else
+          text = ". #{stage}Draws data from `#{self.data['file']}`"
+        end
+        text.concat("#{reason},") if reason
+        text.concat(" and parses it as follows:")
+        return text
+      when "render"
+        if self.source
+          text = ". #{stage}Using the index file `#{self.source}` as a map#{reason}, and ingesting AsciiDoc attributes from "
+          if self.data.is_a? Array
+            text.concat("the following data files:")
+            self.data.each do |file|
+              text.concat("\n  * `#{file}`.")
+            end
+          else
+            text.concat("`#{self.data}`")
+          end
+          return text
+        end
+      end
+    else
+      return @step['message']
+    end
+  end
+
   def validate
     case self.type
     when "parse"
@@ -267,6 +352,58 @@ class Build
     @build['props']
   end
 
+  def variables
+    @build['variables']
+  end
+
+  def message
+    # dynamically build a message, possibly appending a reason
+    unless @build['message']
+      reason = ", #{@build['reason']}" if @build['reason']
+      case @type
+      when "parse"
+        text = ".. Builds `#{self.output}` pressed with the template `#{self.template}`#{reason}."
+      when "render"
+        case self.backend
+        when "pdf"
+          text = ".. Uses Asciidoctor/Prawn to generate a PDF file `#{self.output}`"
+          text.concat("#{reason}") if reason
+          text.concat(".")
+        when "html5"
+          text = ".. Compiles a standard Asciidoctor HTML5 file, `#{self.output}`"
+          text.concat("#{reason}") if reason
+          text.concat(".")
+        when "jekyll"
+          text = ".. Uses Jekyll config files:\n+\n--"
+          files = self.props['files']
+          if files.is_a? String
+            if files.include? ","
+              files = files.split(",")
+            else
+              files = files.split
+            end
+          else
+            unless files.is_a? Array
+              @logger.error "The Jekyll configuration file must be a single filename, a comma-separated list of filenames, or an array of filenames."
+            end
+          end
+          files.each do |file|
+            text.concat("\n  * `#{file}`")
+          end
+          text.concat("\n\nto generate a static site")
+          if self.props && self.props['arguments']
+            text.concat(" at `#{self.props['arguments']['destination']}`")
+          end
+          text.concat("#{reason}") if reason
+          text.concat(".\n--\n")
+        end
+        return text
+      end
+    else
+      @build['message']
+    end
+  end
+
   def prop_files_array
     if props
       if props['files']
@@ -333,7 +470,7 @@ class Build
     end
   end
 
-end #class Build
+end # class Build
 
 class DataSrc
   # initialization means establishing a proper hash for the 'data' param
@@ -355,8 +492,12 @@ class DataSrc
     else
       if datasrc.is_a? String
         @datasrc['ext'] = File.extname(datasrc)
-      else # datasrc is neither string nor hash
-        raise "InvalidDataSource"
+      else
+        if datasrc.is_a? Array
+
+        else
+          raise "InvalidDataSource"
+        end
       end
     end
   end
@@ -522,9 +663,13 @@ def parse_regex data_file, pattern
 end
 
 # Parse given data using given template, generating given output
-def liquify datasrc, template_file, output
+def liquify datasrc, template_file, output, variables=nil
   data = get_data(datasrc)
   validate_file_input(template_file, "template")
+  if variables
+    vars = { "vars" => variables }
+    data.merge!vars
+  end
   begin
     template = File.read(template_file) # reads the template file
     template = Liquid::Template.parse(template) # compiles template
@@ -546,7 +691,7 @@ def liquify datasrc, template_file, output
       raise "FileNotBuilt"
     end
     if File.exists?(output_file)
-      @logger.info "File built: #{File.basename(output_file)}"
+      @logger.info "File built: #{output_file}"
     else
       @logger.error "Hrmp! File not built."
       raise "FileNotBuilt"
@@ -638,7 +783,11 @@ def ingest_attributes attr_file
       raise "AttributeBlockError"
     end
     begin
-      attrs.merge!new_attrs
+      if new_attrs.is_a? Hash
+        attrs.merge!new_attrs
+      else
+        @logger.warn "The AsciiDoc attributes file #{filename} is not formatted as a hash, so its data was not ingested."
+      end
     rescue Exception => ex
       raise "AttributesMergeError #{ex.message}"
     end
@@ -657,7 +806,6 @@ def derive_backend type, out_file
 end
 
 def render_doc doc, build
-  build.set("backend", derive_backend(doc.type, build.output) ) unless build.backend
   case build.backend
   when "html5", "pdf"
     asciidocify(doc, build)
@@ -734,15 +882,15 @@ def generate_site doc, build
     attrs.merge!(build.attributes) if build.attributes
     attrs = {"asciidoctor" => {"attributes" => attrs} }
     attrs_yaml = attrs.to_yaml # Convert it all back to Yaml, as we're going to write a file to feed back to Jekyll
-    FileUtils::mkdir_p("build/pre") unless File.exists?("build/pre")
-    File.open("build/pre/_attributes.yml", 'w') { |file| file.write(attrs_yaml) }
-    build.add_config_file("build/pre/_attributes.yml")
+    File.open("#{@build_dir}/pre/_attributes.yml", 'w') { |file| file.write(attrs_yaml) }
+    build.add_config_file("#{@build_dir}/pre/_attributes.yml")
     config_list = build.prop_files_array.join(',') # flatten the Array back down for the CLI
     opts_args = ""
+    quiet = "--quiet" if @quiet || @explicit
     if build.props['arguments']
       opts_args = build.props['arguments'].to_opts_args
     end
-    command = "bundle exec jekyll build --config #{config_list} #{opts_args}"
+    command = "bundle exec jekyll build --config #{config_list} #{opts_args} #{quiet}"
   end
   @logger.info "Running #{command}"
   @logger.debug "AsciiDoc attributes: #{doc.attributes.to_yaml} "
@@ -839,6 +987,8 @@ end
 
 # Extending Liquid filters/text manipulation
 module CustomFilters
+  include Jekyll::Filters
+
   def plainwrap input
     input.wrap
   end
@@ -875,7 +1025,7 @@ Liquid::Template.register_filter(CustomFilters)
 command_parser = OptionParser.new do|opts|
   opts.banner = "Usage: liquidoc [options]"
 
-  opts.on("-a KEY=VALUE", "For passing an AsciiDoc attribute parameter to Asciidoctor. Ex: -a basedir=some/path -a custom_var='my value'") do |n|
+  opts.on("-a KEY=VALUE", "For passing an AsciiDoc attribute parameter to Asciidoctor. Ex: -a imagesdir=some/path -a custom_var='my value'") do |n|
     pair = {}
     k,v = n.split('=')
       pair[k] = v
@@ -884,7 +1034,11 @@ command_parser = OptionParser.new do|opts|
 
   # Global Options
   opts.on("-b PATH", "--base=PATH", "The base directory, relative to this script. Defaults to `.`, or pwd." ) do |n|
-    @data_file = @base_dir + n
+    @base_dir = n
+  end
+
+  opts.on("-B PATH", "--build=PATH", "The directory under which LiquiDoc should save automatically preprocessed files. Defaults to #{@base_dir}_build. Can be absolute or relative to the base path (-b/--base=). Do NOT append '/' to the build path." ) do |n|
+    @build_dir = n
   end
 
   opts.on("-c", "--config=PATH", "Configuration file, enables preset source, template, and output.") do |n|
@@ -911,17 +1065,25 @@ command_parser = OptionParser.new do|opts|
     @template_file = @base_dir + n
   end
 
-  opts.on("--verbose", "Run verbose") do |n|
+  opts.on("--verbose", "Run verbose debug logging.") do |n|
     @logger.level = Logger::DEBUG
     @verbose = true
   end
 
-  opts.on("--stdout", "Puts the output in STDOUT instead of writing to a file.") do
-    @output_type = "stdout"
+  opts.on("--quiet", "Run with only WARN- and error-level logs written to console.") do |n|
+    @logger.level = Logger::WARN
+    @quiet = true
+  end
+
+  opts.on("--explicit", "Log explicit step descriptions to console as build progresses. (Otherwise writes to file at #{@build_dir}/pre/config-explainer.adoc .)") do |n|
+    explainer_init("STDOUT")
+    @explainer.level = Logger::INFO
+    @logger.level = Logger::WARN # Suppress all those INFO-level messages
+    @explicit = true
   end
 
-  opts.on("--clean PATH", "Force deletes the designated directory and all its contents WITHOUT WARNING.") do |n|
-    @clean_dir = n
+  opts.on("--stdout", "Puts the output in STDOUT instead of writing to a file.") do
+    @output_type = "stdout"
   end
 
   opts.on("--deploy", "EXPERIMENTAL: Trigger a jekyll serve operation against the destination dir of a Jekyll render step.") do
@@ -938,21 +1100,21 @@ end
 command_parser.parse!
 
 # Upfront debug output
-@logger.debug "Base dir: #{@base_dir}"
-@logger.debug "Config file: #{@config_file}"
+@logger.debug "Base dir: #{@base_dir} (The path from which LiquiDoc CLI commands are relative.)"
+
+explainer_init
 
 # ===
 # Execute
 # ===
-if @clean_dir
-  FileUtils.remove_dir(@clean_dir)
-end
+
 unless @config_file
+  @logger.debug "Executing config-free build based on API/CLI arguments alone."
   if @data_file
     liquify(@data_file, @template_file, @output_file)
   end
   if @index_file
-    @logger.warn "Publishing via command line arguments not yet implemented. Use a config file."
+    @logger.warn "Rendering via command line arguments is not yet implemented. Use a config file."
   end
 else
   @logger.debug "Executing... config_build"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: liquidoc
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Brian Dominick
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-05 00:00:00.000000000 Z
+date: 2018-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -51,7 +51,6 @@ files:
 - bin/liquidoc
 - lib/liquidoc.rb
 - lib/liquidoc/version.rb
-- lib/yaml_plus.rb
 homepage: https://github.com/scalingdata/liquidoc
 licenses:
 - MIT

data/lib/yaml_plus.rb

@@ -1,60 +0,0 @@
-require 'safe_yaml/load'
-module YamlPlus
-
-  def self.parse data
-    puts data
-    return
-    # self.new.load((::SafeYAML.load raw_data), theme_data)
-    # input_data ||= ::OpenStruct.new
-    # return input_data unless ::Hash === data
-    # data.inject(input_data) {|data, (key, val)| process_entry key, val, data }
-    # input_data.base_align ||= 'left'
-    # input_data
-  end
-
-  def process_entry key, val, data
-    if ::Hash === val
-      val.each do |key2, val2|
-        process_entry %(#{key}_#{key2.tr '-', '_'}), val2, data
-      end
-    else
-      data[key] = evaluate val, data
-    end
-    data
-  end
-
-  def evaluate expr, vars
-    case expr
-    when ::String
-      evaluate_math(expand_vars expr, vars)
-    when ::Array
-      expr.map {|e| evaluate e, vars }
-    else
-      expr
-    end
-  end
-
-  def expand_vars expr, vars
-    if (idx = (expr.index '$'))
-      if idx == 0 && expr =~ LoneVariableRx
-        if vars.respond_to? $1
-          vars[$1]
-        else
-          warn %(asciidoctor: WARNING: unknown variable reference: $#{$1})
-          expr
-        end
-      else
-        expr.gsub(VariableRx) {
-          if vars.respond_to? $1
-            vars[$1]
-          else
-            warn %(asciidoctor: WARNING: unknown variable reference: $#{$1})
-            $&
-          end
-        }
-      end
-    else
-      expr
-    end
-  end
-end