giblish 0.2.12 → 0.3.0

data/lib/giblish/docconverter.rb

@@ -0,0 +1,231 @@
+require "pathname"
+require "asciidoctor"
+require "asciidoctor-pdf"
+
+require_relative "utils"
+
+module Giblish
+
+  # Base class for document converters. It contains a hash of
+  # conversion options used by derived classes
+  class DocConverter
+    # a common set of converter options used for all output formats
+    COMMON_CONVERTER_OPTS = {
+        safe: Asciidoctor::SafeMode::UNSAFE,
+        header_footer: true,
+        mkdirs: true
+    }.freeze
+
+    # the giblish attribute defaults used if nothing else
+    # is required by the user
+    DEFAULT_ATTRIBUTES = {
+        "source-highlighter" => "rouge",
+        "xrefstyle" => "short"
+    }.freeze
+
+    # setup common options that are used regardless of the
+    # specific output format used
+    attr_reader :converter_options
+
+    # the path manager used by this converter
+    attr_accessor :paths
+
+    def initialize(paths, options)
+      # access the source highlight module
+      require "asciidoctor-rouge"
+
+      @paths = paths
+      @user_style = options[:userStyle]
+      @converter_options = COMMON_CONVERTER_OPTS.dup
+      @converter_options[:attributes] = DEFAULT_ATTRIBUTES.dup
+      @converter_options[:backend] = options[:backend]
+    end
+
+    # Public: Convert one single adoc file using the specific conversion
+    # options.
+    #
+    # filepath - a pathname with the absolute path to the input file to convert
+    #
+    # Returns: The resulting Asciidoctor::Document object
+    def convert(filepath)
+      unless filepath.is_a?(Pathname)
+        raise ArgumentError, "Trying to invoke convert with non-pathname!"
+      end
+
+      Giblog.logger.info {"Processing: #{filepath}"}
+
+      # create an asciidoc doc object and convert to requested
+      # output using current conversion options
+      @converter_options[:to_dir] = @paths.adoc_output_dir(filepath).to_s
+      @converter_options[:base_dir] =
+          Giblish::PathManager.closest_dir(filepath).to_s
+      @converter_options[:to_file] =
+          Giblish::PathManager.get_new_basename(filepath,
+                                                @converter_options[:fileext])
+
+      Giblog.logger.debug {"converter_options: #{@converter_options}"}
+
+      # do the actual conversion
+      Asciidoctor.convert_file filepath, @converter_options
+    end
+
+    # converts the supplied string to the file
+    # dst_dir/basename.<backend-ext>
+    #
+    # the supplied string must pass asciidoctor without
+    # any error to stderr, otherwise, nothing will be written
+    # to disk.
+    # returns 'true' if a file was written, 'false' if not
+    def convert_str(src_str, dst_dir, basename)
+      index_opts = @converter_options.dup
+
+      # use the same options as when converting all docs
+      # in the tree but make sure we don't write to file
+      # by trial and error, the following dirs seem to be
+      # necessary to change
+      index_opts[:to_dir] = dst_dir.to_s
+      index_opts[:base_dir] = dst_dir.to_s
+      index_opts.delete_if {|k, _v| %i[to_file].include? k}
+
+      # load and convert the document using the converter options
+      doc = nil, output = nil
+      adoc_stderr = Giblish.with_captured_stderr do
+        doc = Asciidoctor.load src_str, index_opts
+        output = doc.convert index_opts
+      end
+
+      index_filepath = dst_dir + "#{basename}.#{index_opts[:fileext]}"
+
+      # if we get anything from asciidoctor to stderr,
+      # consider this a failure and do not emit a file.
+      if !adoc_stderr.length.zero?
+        Giblog.logger.error {"Errors when converting string to asciidoc!!"}
+        Giblog.logger.error {"Will _not_ generate file #{index_filepath.to_s}"}
+        Giblog.logger.error {"Got following warnings/errors from asciidoc conversion:"}
+        Giblog.logger.error {adoc_stderr}
+        return false
+      end
+
+      # write the converted document to an index file located at the
+      # destination root
+      doc.write output, index_filepath.to_s
+      true
+    end
+
+    protected
+
+    # Protected: Adds the supplied backend specific options and
+    #            attributes to the base ones.
+    #            The following options must be provided by the derived class:
+    #            :fileext - a string with the filename extention to use for the
+    #                       generated file
+    #
+    # backend_opts - the options specific to the asciidoctor backend
+    #                that the derived class supports
+    # backend_attribs - the attributes specific to the asciidoctor backend
+    #                   that the derived class supports
+    def add_backend_options(backend_opts, backend_attribs)
+      @converter_options = @converter_options.merge(backend_opts)
+      @converter_options[:attributes] =
+          @converter_options[:attributes].merge(backend_attribs)
+    end
+  end
+
+# Converts asciidoc files to html5 output.
+  class HtmlConverter < DocConverter
+    def initialize(paths, options)
+      super paths, options
+
+      # handle needed assets for the styling (css et al)
+      html_attrib = setup_web_assets options[:webRoot]
+
+      # Setting 'data-uri' makes asciidoctor embed images in the resulting
+      # html file
+      html_attrib["data-uri"] = 1
+
+      # tell asciidoctor to use the html5 backend
+      backend_options = {backend: "html5", fileext: "html"}
+      add_backend_options backend_options, html_attrib
+    end
+
+    private
+
+    def setup_stylesheet_attributes(css_dir)
+      return {} if @paths.resource_dir_abs.nil?
+
+      # use the supplied stylesheet if there is one
+      attrib = {"linkcss" => 1,
+                "stylesdir" => css_dir,
+                "stylesheet" => "giblish.css",
+                "copycss!" => 1}
+
+      # Make sure that a user supplied stylesheet ends with .css or .CSS
+      @user_style &&
+          attrib["stylesheet"] =
+              /\.(css|CSS)$/ =~ @user_style ? @user_style : "#{@user_style}.css"
+      Giblog.logger.debug {"stylesheet attributes: #{attrib}"}
+      attrib
+    end
+
+    # make sure that linked assets are available at dst_root
+    def setup_web_assets(html_dir_root = nil)
+      # only set this up if user has specified a resource dir
+      return {} unless @paths.resource_dir_abs
+
+      # create dir for web assets directly under dst_root
+      assets_dir = "#{@paths.dst_root_abs}/web_assets"
+      Dir.exist?(assets_dir) || FileUtils.mkdir_p(assets_dir)
+
+      # copy needed assets
+      %i[css fonts images].each do |dir|
+        src = "#{@paths.resource_dir_abs}/#{dir}"
+        Dir.exist?(src) && FileUtils.copy_entry(src, "#{assets_dir}/#{dir}")
+      end
+
+      # find the path to the assets dir that is correct when called from a url,
+      # taking the DirectoryRoot for the web site into consideration.
+      if html_dir_root
+        wr = Pathname.new(
+            assets_dir
+        ).relative_path_from Pathname.new(html_dir_root)
+        Giblog.logger.info {"Relative web root: #{wr}"}
+        assets_dir = "/" << wr.to_s
+      end
+
+      Giblog.logger.info {"stylesheet dir: #{assets_dir}"}
+      setup_stylesheet_attributes "#{assets_dir}/css"
+    end
+  end
+
+  class PdfConverter < DocConverter
+    def initialize(paths, options)
+      super paths, options
+
+      pdf_attrib = setup_pdf_attribs
+
+      backend_options = {backend: "pdf", fileext: "pdf"}
+      add_backend_options backend_options, pdf_attrib
+    end
+
+    private
+
+    def setup_pdf_attribs()
+      # only set this up if user has specified a resource dir
+      return {} unless @paths.resource_dir_abs
+
+      pdf_attrib = {
+          "pdf-stylesdir" => "#{@paths.resource_dir_abs}/themes",
+          "pdf-style" => "giblish.yml",
+          "pdf-fontsdir" => "#{@paths.resource_dir_abs}/fonts",
+          "icons" => "font"
+      }
+
+      # Make sure that the stylesheet ends with .yml or YML
+      @user_style &&
+          pdf_attrib["pdf-style"] =
+              /\.(yml|YML)$/ =~ @user_style ? @user_style : "#{@user_style}.yml"
+
+      pdf_attrib
+    end
+  end
+end

data/lib/giblish/docid.rb

@@ -1,23 +1,35 @@
 
 require_relative "./utils"
-
-require 'asciidoctor'
-require 'asciidoctor/extensions'
+require "asciidoctor"
+require "asciidoctor/extensions"
 
 module Giblish
   # Parse all adoc files for :docid: attributes
   class DocidCollector < Asciidoctor::Extensions::Preprocessor
     # Use a class-global docid_cache since asciidoctor creates a new instance
     # for each preprocessor hook
+    # a hash of {doc_id => Pathname(src_path)}
     @docid_cache = {}
+
+    # A class-global hash of {src_path => [target doc_ids] }
+    @docid_deps = {}
+
     class << self
       def docid_cache
         @docid_cache
       end
 
+      def docid_deps
+        @docid_deps
+      end
+
       def clear_cache
         @docid_cache = {}
       end
+
+      def clear_deps
+        @docid_deps = {}
+      end
     end
 
     # The minimum number of characters required for a valid doc id
@@ -32,30 +44,6 @@ module Giblish
     #   super(everything)
     # end
 
-    # Helper method that provides the user with a way of processing only the
-    # lines within the asciidoc header block.
-    # The user must return nil to get the next line.
-    #
-    # ex:
-    # process_header_lines(file_path) do |line|
-    #   if line == "Quack!"
-    #      puts "Donald!"
-    #      1
-    #   else
-    #      nil
-    #   end
-    # end
-    def process_header_lines(path)
-      state = "before_header"
-      File.foreach(path) do |line|
-        case state
-        when "before_header" then (state = "in_header" if line =~ /^=+.*$/)
-        when "in_header" then (state = "done" if line =~ /^\s*$/ || yield(line))
-        when "done" then break
-        end
-      end
-    end
-
     # Check if a :docid: <id> entry exists in the header.
     # According to http://www.methods.co.nz/asciidoc/userguide.html#X95
     # the header is optional, but if it exists it:
@@ -73,40 +61,95 @@ module Giblish
       end
     end
 
+    # add a new source document to the docid_deps
+    def add_source_dep(src_path)
+      return if docid_deps.key? src_path
+      docid_deps[src_path] = []
+    end
+
     # This hook is called by Asciidoctor once for each document _before_
     # Asciidoctor processes the adoc content.
     #
     # It replaces references of the format <<:docid: ID-1234,Hello >> with
     # references to a resolved relative path.
     def process(document, reader)
+      # Add doc as a source dependency for doc ids
+      src_path = document.attributes["docfile"]
+
+      # Note: the nil check is there to prevent us adding generated
+      # asciidoc docs that does not exist in the file system (e.g. the
+      # generated index pages). This is a bit hackish and should maybe be
+      # done differently
+      return if src_path.nil?
+
+      add_source_dep src_path
+
+      # Convert all docid refs to valid relative refs
       reader.lines.each do |line|
         line.gsub!(/<<\s*:docid:\s*(.*)>>/) do |_m|
-          replace_doc_id Regexp.last_match(1), document.attributes["docfile"]
+          # parse the ref
+          target_id, section, display_str =
+            parse_doc_id_ref Regexp.last_match(1)
+
+          # The result is a valid ref in the form
+          # <<target_doc.adoc#[section][,display_str]>>
+          Giblog.logger.debug { "Replace docid ref in doc #{src_path}..." }
+          if docid_cache.key? target_id
+            # add the referenced doc id as a target dependency of this document
+            docid_deps[src_path] << target_id
+            docid_deps[src_path] = docid_deps[src_path].uniq
+
+            # resolve the doc id ref to a valid relative path
+            "<<#{get_rel_path(src_path, target_id)}##{section}#{display_str}>>"
+          else
+            "<<UNKNOWN_DOC, Could not resolve doc id reference !!!>>"
+          end
         end
       end
       reader
     end
 
-    def substitute_ids_file(path)
-      substitute_ids(File.read(path), path)
-    end
+    private
 
-    def substitute_ids(src_str, src_path)
-      src_str.gsub!(/<<\s*:docid:\s*(.*)>>/) do |_m|
-        replace_doc_id Regexp.last_match(1), src_path
+    # Helper method that provides the user with a way of processing only the
+    # lines within the asciidoc header block.
+    # The user must return nil to get the next line.
+    #
+    # ex:
+    # process_header_lines(file_path) do |line|
+    #   if line == "Quack!"
+    #      puts "Donald!"
+    #      1
+    #   else
+    #      nil
+    #   end
+    # end
+    def process_header_lines(path)
+      state = "before_header"
+      File.foreach(path) do |line|
+        case state
+        when "before_header" then (state = "in_header" if line =~ /^=+.*$/)
+        when "in_header" then (state = "done" if line =~ /^\s*$/ || yield(line))
+        when "done" then break
+        end
       end
-      src_str
     end
 
-    private
-
     # Helper method to shorten calls to docid_cache from instance methods
     def docid_cache
       self.class.docid_cache
     end
 
+    def docid_deps
+      self.class.docid_deps
+    end
+
+    # Get the relative path from the src doc to the
+    # doc with the given doc id
     def get_rel_path(src_path, doc_id)
-      return "UNKNOWN_DOC" unless docid_cache.key? doc_id
+      unless docid_cache.key? doc_id
+        raise ArgumentError("unknown doc id: #{doc_id}")
+      end
 
       rel_path = docid_cache[doc_id]
                  .dirname
@@ -115,43 +158,49 @@ module Giblish
       rel_path.to_s
     end
 
-    # The input string shall contain the expression between
+    # input_str shall be the expression between
     # <<:docid:<input_str>>> where the <input_str> is in the form
     # <id>[#section][,display_str]
     #
-    # The result shall be a valid ref in the form
-    # <<target_doc.adoc#[section][,display_str]>>
-    def replace_doc_id(input_str, src_path)
+    # returns an array with [id, section, display_str]
+    def parse_doc_id_ref(input_str)
       ref, display_str = input_str.split(",").each(&:strip)
-      display_str = "" if display_str.nil?
-      display_str.prepend "," if display_str.length.positive?
-
       id, section = ref.split "#"
+
+      display_str = id.dup if display_str.nil?
+      display_str.prepend ","
+
       section = "" if section.nil?
 
-      Giblog.logger.debug { "Replace docid ref in doc #{src_path}..." }
-      "<<#{get_rel_path(src_path, id)}##{section}#{display_str}>>"
+      [id, section, display_str]
+    end
+
+    # make sure the id is within the designated length and
+    # does not contain a '#' symbol
+    def doc_id_ok?(doc_id)
+      (doc_id.length.between?(ID_MIN_LENGTH, ID_MAX_LENGTH) &&
+         !doc_id.include?("#"))
     end
 
     def validate_and_add(doc_id, path)
       id = doc_id.strip
       Giblog.logger.debug { "found possible docid: #{id}" }
 
-      # make sure the id is within the designated length and
-      # does not contain a '#' symbol
-      if id.length.between?(ID_MIN_LENGTH, ID_MAX_LENGTH) &&
-         !id.include?("#")
-        # the id is ok
-        if docid_cache.key? id
-          Giblog.logger.warn { "Found same doc id twice (#{id}). Using last found id."}
-        end
-        docid_cache[id] = Pathname(path)
-      else
-        Giblog.logger.error { "Invalid docid: #{id}, this will be ignored!" }
+      unless doc_id_ok? doc_id
+        Giblog.logger.error { "Invalid docid: #{id} in file #{path}, this will be ignored!" }
+        return
+      end
+
+      if docid_cache.key? id
+        Giblog.logger.warn { "Found same doc id twice (#{id})." }
+        Giblog.logger.warn { "Assigning this id to the file #{path}." }
+        Giblog.logger.warn { "Discarding this id from the file #{docid_cache[id]}." }
       end
+      docid_cache[id] = Pathname(path)
     end
   end
 
+
   # Helper method to register the docid preprocessor extension with
   # the asciidoctor engine.
   def register_extensions