giblish 0.1.0

data/lib/giblish/cmdline.rb

@@ -0,0 +1,190 @@
+#!/usr/bin/ruby
+
+require_relative "utils"
+require_relative "version"
+
+# Parse the cmd line arguments
+# This implementation is heavily inspired by the following
+# stack overflow answer:
+# http://stackoverflow.com/questions/26434923/parse-command-line-arguments-in-a-ruby-script
+class CmdLineParser
+  attr_accessor :args
+
+  USAGE = <<~ENDUSAGE.freeze
+    Usage:
+      giblish [options] source_dir_top dest_dir_top
+  ENDUSAGE
+  HELP = <<ENDHELP.freeze
+ Options:
+  -h --help                  show this help text
+  -v --version               show version nr and exit
+  -f --format <format>       the output format, currently html5 or pdf are supported
+                             *html5* is used if -f is not supplied
+  -n --no-build-ref          suppress generation of a reference document at the destination
+                             tree root.
+  -r --resource-dir <dir>    specify a directory where fonts, themes, css and other
+                             central stuff needed for document generation are located.
+                             The resources are expected to be located in a subfolder
+                             whose name matches the resource type (font, theme
+                             or css). If no resource dir is specified, the asciidoctor
+                             defaults are used.
+  -s --style <name>          The style information used when converting the documents
+                             using the -r option for specifying resource directories.
+                             For html this is a name of a css file, for pdf, this is
+                             the name of an yml file. If no style is given 'giblish'
+                             is used as default.
+  -w --web-root <path>       Specifies the top dir (DirectoryRoot) of a file system
+                             tree published by a web server. This switch is only used
+                             when generating html. The typical use case is that giblish
+                             is used to generate html docs which are linked to a css.
+                             The css link needs to be relative to the top of the web
+                             tree (DirectoryRoot on Apache) and not the full absolute
+                             path to the css directory.
+  -g --git-branches <regExp> if the source_dir_top is located within a git repo,
+                             generate docs for all remote branches that matches
+                             the given regular expression. Each git branch will
+                             be generated to a separate subdir under the destination
+                             root dir.
+  -t --git-tags <regExp>     if the source_dir_top is located within a git repo,
+                             generate docs for all tags that matches the given
+                             regular expression. Each tag will be generated to
+                             a separate subdir under the destination root dir.
+  -c --local-only            do not try to fetch git info from any remotes of the
+                             repo before generating documents.
+  --log-level                set the log level explicitly. Must be one of
+                             debug, info, warn (default), error or fatal.
+ENDHELP
+
+  def initialize(cmdline_args)
+    parse_cmdline cmdline_args
+
+    # handle help and version requests
+    if @args[:help]
+      puts HELP
+      exit
+    end
+    if @args[:version]
+      puts "Giblish v#{Giblish::VERSION}"
+      exit
+    end
+
+    # set log level
+    set_log_level
+    sanity_check_input
+    set_gitrepo_root
+    # if @args[:logfile]
+    #   $stdout.reopen( ARGS[:logfile], "w" )
+    #   $stdout.sync = true
+    #   $stderr.reopen( $stdout )
+    # end
+  end
+
+  def usage
+    USAGE
+  end
+
+  private
+
+  def set_log_level
+    log_level = @args[:logLevel] || "warn"
+    case log_level
+    when "debug" then Giblog.logger.sev_threshold = Logger::DEBUG
+    when "info"  then Giblog.logger.sev_threshold = Logger::INFO
+    when "warn"  then Giblog.logger.sev_threshold = Logger::WARN
+    when "error" then Giblog.logger.sev_threshold = Logger::ERROR
+    when "fatal" then Giblog.logger.sev_threshold = Logger::FATAL
+    else
+      puts "Invalid log level specified. Run with -h to see supported levels"
+      puts USAGE
+      exit
+    end
+  end
+
+  def sanity_check_input
+    ensure_required_args
+    prevent_invalid_combos
+  end
+
+  def parse_cmdline(cmdline_args)
+    # default values for cmd line switches
+    @args = {
+      help: false,
+      version: false,
+      force: true,
+      format: "html5",
+      flatten: false,
+      suppressBuildRef: false,
+      localRepoOnly: false,
+      webRoot: false
+    }
+
+    # set default log level
+    Giblog.logger.sev_threshold = Logger::WARN
+
+    # defines args without a corresponding flag, the order is important
+    unflagged_args = %i[srcDirRoot dstDirRoot]
+
+    # parse cmd line
+    next_arg = unflagged_args.first
+    cmdline_args.each do |arg|
+      case arg
+      when "-h", "--help"         then @args[:help]      = true
+      when "-v", "--version"      then @args[:version]   = true
+      when "-f", "--format   "    then next_arg = :format
+      when "-r", "--resource-dir" then next_arg = :resourceDir
+      when "-n", "--no-build-ref" then @args[:suppressBuildRef] = true
+      when "-g", "--git-branches" then next_arg = :gitBranchRegexp
+      when "-t", "--git-tags"     then next_arg = :gitTagRegexp
+      when "-c", "--local-only"   then @args[:localRepoOnly] = true
+      when "-s", "--style"        then next_arg = :userStyle
+      when "-w", "--web-root"     then next_arg = :webRoot
+      when "--log-level"            then next_arg = :logLevel
+      else
+        if next_arg
+          @args[next_arg] = arg
+          unflagged_args.delete(next_arg)
+        end
+        next_arg = unflagged_args.first
+      end
+    end
+  end
+
+  def prevent_invalid_combos
+    # Prevent contradicting options
+    if !@args[:resourceDir] && @args[:userStyle]
+      puts "Error: The given style would not be used since no resource dir "\
+           "was specified (-s specified without -r)"
+    else
+      return
+    end
+
+    puts USAGE
+    exit
+  end
+
+  def ensure_required_args
+    # Exit if the user does not supply the required arguments
+    return unless !@args[:srcDirRoot] || !@args[:dstDirRoot]
+
+    puts "Error: Too few arguments."
+    puts USAGE
+    exit
+  end
+
+  def set_gitrepo_root
+    # if user don't want no git repo, we're done
+    return unless @args[:gitBranchRegexp] || @args[:gitTagRegexp]
+
+    # The user wants to parse a git repo, check that the srcDirRoot is within a
+    # git repo if the user wants to generate git-branch specific docs
+    @args[:gitRepoRoot] = Giblish::PathManager.find_gitrepo_root(
+      @args[:srcDirRoot]
+    )
+    return unless @args[:gitRepoRoot].nil?
+
+    # We should not get here if everything is koscher...
+    puts "Error: Source dir not in a git working dir despite -g or -t option given!"
+    puts USAGE
+    exit
+  end
+end

data/lib/giblish/core.rb

@@ -0,0 +1,375 @@
+#!/usr/bin/env ruby
+#
+# Converts a tree of asciidoc docs to pdf/html
+#
+#
+
+require "find"
+require "fileutils"
+require "logger"
+require "pathname"
+require "asciidoctor"
+require "asciidoctor-pdf"
+
+require_relative "cmdline"
+require_relative "buildindex"
+
+# 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
+
+  # setup common options that are used regardless of the
+  # specific output format used
+  attr_reader :converter_options
+
+  # Public: Setup common converter options. Required options are:
+  #         :srcDirRoot
+  #         :dstDirRoot
+  #         :resourceDir
+  def initialize(options)
+    @paths = Giblish::PathManager.new(
+      options[:srcDirRoot], options[:dstDirRoot], options[:resourceDir]
+    )
+
+    @user_style = options[:userStyle]
+    @converter_options = COMMON_CONVERTER_OPTS.dup
+    @converter_options[:backend] = options[:backend]
+  end
+
+  # Public: Convert one single adoc file using the specific conversion
+  # options.
+  #
+  # filepath - a string with the absolute path to the input file to convert
+  #
+  # Returns: The resulting Asciidoctor::Document object
+  def convert(filepath)
+    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
+
+  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] = backend_attribs
+  end
+end
+
+# Converts asciidoc files to html5 output.
+class HtmlConverter < DocConverter
+  # Public: Setup common converter options. Required options are:
+  #         :srcDirRoot
+  #         :dstDirRoot
+  #         :resourceDir
+  def initialize(options)
+    super 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"
+
+    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(options)
+    super options
+
+    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"
+
+    backend_options = { backend: "pdf", fileext: "pdf" }
+    add_backend_options backend_options, pdf_attrib
+  end
+end
+
+class TreeConverter
+
+  # def init_dst_root
+  #   # make sure destination dir exists
+  #   Giblog.logger.info do
+  #     "Will generate docs to destination root: #{@paths.dst_root_abs}"
+  #   end
+  #   Dir.exist?(@paths.dst_root_abs) || FileUtils.mkdir_p(@paths.dst_root_abs)
+  # end
+
+  # Required options:
+  #  srcDirRoot
+  #  dstDirRoot
+  #  resourceDir
+  def initialize(options)
+    @options = options.dup
+
+    @paths = Giblish::PathManager.new(
+      @options[:srcDirRoot],
+      @options[:dstDirRoot],
+      @options[:resourceDir]
+    )
+
+    # init_dst_root
+
+    # prepare the index page if requested
+    unless @options[:suppressBuildRef]
+      @index_builder = if @options[:gitRepoRoot]
+                         GitRepoIndexBuilder.new(@paths, options[:gitRepoRoot])
+                       else
+                         SimpleIndexBuilder.new(@paths)
+                       end
+    end
+
+    @conversion =
+      case options[:format]
+      when "html" then HtmlConverter.new options
+      when "pdf" then PdfConverter.new options
+      else
+        raise ArgumentError, "Unknown conversion format: #{options[:format]}"
+      end
+  end
+
+  def generate_index(src_str, dst_dir)
+    # use the same options as when converting all docs
+    # in the tree but make sure we don't write to file
+    index_opts = @conversion.converter_options.dup
+    index_opts.delete(:to_file)
+    index_opts.delete(:to_dir)
+
+    # load and convert the document using the converter options
+    doc = Asciidoctor.load src_str, index_opts
+    output = doc.convert index_opts
+
+    # write the converted document to an index file located at the
+    # destination root
+    index_filepath = dst_dir + "index.#{index_opts[:fileext]}"
+    doc.write output, index_filepath.to_s
+  end
+
+  def to_asciidoc(filepath)
+    adoc = nil
+    begin
+      # do the conversion and capture eventual errors that
+      # the asciidoctor lib writes to stderr
+      adoc_stderr = Giblish.with_captured_stderr do
+        adoc = @conversion.convert(filepath)
+      end
+
+      # build the reference index if the user wants it
+      @options[:suppressBuildRef] || @index_builder.add_doc(adoc, adoc_stderr)
+    rescue Exception => e
+      str = "Error when converting doc: #{e.message}\n"
+      e.backtrace.each { |l| str << "#{l}\n" }
+      Giblog.logger.warn { str }
+      @options[:suppressBuildRef] || @index_builder.add_doc_fail(filepath, e)
+    end
+  end
+
+  def walk_dirs
+    # traverse the src file tree and convert all files that ends with
+    # .adoc or .ADOC
+    Find.find(@paths.src_root_abs) do |path|
+      ext = File.extname(path)
+      to_asciidoc(path) if !ext.empty? && ext.casecmp(".ADOC").zero?
+    end
+
+    # check if we shall build index or not
+    return if @options[:suppressBuildRef]
+
+    # build a reference index
+    generate_index @index_builder.index_source, @paths.dst_root_abs
+
+    # clean up adoc resources
+    @index_builder = nil
+    GC.start
+  end
+end
+
+class GitRepoParser
+  def initialize(options)
+    @options = options
+    @paths = Giblish::PathManager.new(
+      @options[:srcDirRoot],
+      @options[:dstDirRoot],
+      @options[:resourceDir]
+    )
+    @git_repo_root = options[:gitRepoRoot]
+
+    # Sanity check git repo root
+    @git_repo_root || raise(ArgumentError("No git repo root dir given"))
+
+    # Connect to the git repo
+    begin
+      @git_repo = Git.open(@git_repo_root)
+    rescue Exception => e
+      raise "Could not find a git repo at #{@git_repo_root} !"\
+            "\n\n(#{e.message})"
+    end
+
+    # fetch all remote refs if ok with user
+    begin
+      @git_repo.fetch unless options[:localRepoOnly]
+    rescue Exception => e
+      raise "Could not fetch from origin"\
+            "(do you need '--local-only'?)!\n\n(#{e.message})"
+    end
+
+    # initialize summary builder
+    @index_builder = GitSummaryIndexBuilder.new @git_repo
+
+    # Get the branches the user wants to parse
+    if options[:gitBranchRegexp]
+      regexp = Regexp.new options[:gitBranchRegexp]
+      @user_branches = @git_repo.branches.remote.select do |b|
+        regexp.match b.name
+      end
+
+      # Render the docs from each branch and add info to the
+      # summary page
+      @user_branches.each do |b|
+        render_one_branch b, @options
+        @index_builder.add_branch b
+      end
+    end
+
+    # Get the branches the user wants to parse
+    if options[:gitTagRegexp]
+      regexp = Regexp.new options[:gitTagRegexp]
+      @user_tags = @git_repo.tags.select do |t|
+        regexp.match t.name
+      end
+
+      # Render the docs from each branch and add info to the
+      # summary page
+      @user_tags.each do |t|
+        render_one_branch t, @options, true
+        @index_builder.add_tag t
+      end
+    end
+
+    # Render the summary page
+    tc = TreeConverter.new options
+    tc.generate_index @index_builder.index_source, @paths.dst_root_abs
+
+    # clean up
+    @index_builder = nil
+    GC.start
+  end
+
+  def render_one_branch(b, opts, is_tag = false)
+    # work with local options
+    options = opts.dup
+
+    # check out the branch in question and make sure it is
+    # up-to-date
+    Giblog.logger.info { "Checking out #{b.name}" }
+    @git_repo.checkout b.name
+
+    unless is_tag
+      Giblog.logger.info { "Merging with origin/#{b.name}" }
+      @git_repo.merge "origin/#{b.name}"
+    end
+
+    # assign a branch-unique dst-dir
+    dir_name = b.name.tr("/", "_") << "/"
+
+    # Assign the branch specific dir as new destination root
+    options[:dstDirRoot] = @paths.dst_root_abs.realpath.join(dir_name).to_s
+
+    # Parse and render docs using given args
+    Giblog.logger.info { "Render docs to dir #{options[:dstDirRoot]}" }
+    tc = TreeConverter.new options
+    tc.walk_dirs
+  end
+end