giblish 0.2.12 → 0.3.0

data/lib/giblish/cmdline.rb

@@ -1,5 +1,3 @@
-#!/usr/bin/ruby
-
 require_relative "utils"
 require_relative "version"
 
@@ -18,8 +16,8 @@ class CmdLineParser
  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
+  -f --format <format>       the output format, currently html or pdf are supported
+                             *html* 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
@@ -50,10 +48,16 @@ class CmdLineParser
                              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
+                             generate docs for all _remote branches on origin_ that matches
                              the given regular expression. Each git branch will
                              be generated to a separate subdir under the destination
                              root dir.
+                             NOTE: To do this, giblish will _explicitly check out the
+                             matching branches and merge them with the corresponding
+                             branch on origin_.
+                             NOTE 2: In bash, use double quotes around your regexp if
+                             you need to quote it. Single quotes are treated as part
+                             of the regexp itself. 
   -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
@@ -66,7 +70,7 @@ class CmdLineParser
                              doc ids to resolve relative paths between the
                              generated documents
   --log-level                set the log level explicitly. Must be one of
-                             debug, info, warn (default), error or fatal.
+                             debug, info (default), warn, error or fatal.
 ENDHELP
 
   def initialize(cmdline_args)
@@ -102,7 +106,7 @@ ENDHELP
   private
 
   def set_log_level
-    log_level = @args[:logLevel] || "warn"
+    log_level = @args[:logLevel] || "info"
     case log_level
       when "debug" then Giblog.logger.sev_threshold = Logger::DEBUG
       when "info"  then Giblog.logger.sev_threshold = Logger::INFO

data/lib/giblish/core.rb

@@ -1,465 +1,316 @@
-#!/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"
+require_relative "docconverter"
 require_relative "docid"
-
-# 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
-
-  # 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[:attributes] = DEFAULT_ATTRIBUTES.dup
-    @converter_options[:backend] = options[:backend]
-  end
-
-  def convert_str(input_str, src_path, output_file = nil)
-    unless input_str.is_a?(String)
-      raise ArgumentError("Trying to invoke convert_str with non-string!")
+require_relative "docinfo"
+require_relative "buildgraph"
+
+module Giblish
+
+  # Parse a directory tree and convert all asciidoc files matching the
+  # supplied critera to the supplied format
+  class FileTreeConverter
+
+    attr_reader :converter
+
+    # Required options:
+    #  srcDirRoot
+    #  dstDirRoot
+    #  resourceDir
+    def initialize(options)
+      @options = options.dup
+
+      @paths = Giblish::PathManager.new(
+          @options[:srcDirRoot],
+          @options[:dstDirRoot],
+          @options[:resourceDir]
+      )
+      @processed_docs = []
+      @converter = converter_factory
     end
 
-    # use the same options as when converting all docs
-    # in the tree but make sure Asciidoctor doesn't write to file
-    index_opts = @converter_options.dup
-    index_opts.delete(:to_file)
-    index_opts.delete(:to_dir)
+    def convert
+      # collect all doc ids and enable replacement of known doc ids with
+      # valid references to adoc files
+      manage_doc_ids if @options[:resolveDocid]
+
+      # traverse the src file tree and convert all files deemed as
+      # adoc files
+      Find.find(@paths.src_root_abs) do |path|
+        p = Pathname.new(path)
+        to_asciidoc(p) if adocfile? p
+      end if @paths.src_root_abs.directory?
+
+      # check if we shall build index or not
+      return if @options[:suppressBuildRef]
+
+      # build a dependency graph (only if we resolve docids...)
+      dep_graph_exist = if @options[:resolveDocid]
+        if Giblish::GraphBuilderGraphviz.supported
+          gb = Giblish::GraphBuilderGraphviz.new @processed_docs, @paths, {extension: @converter.converter_options[:fileext]}
+          @converter.convert_str gb.source, @paths.dst_root_abs, "graph"
+        else
+          Giblog.logger.warn { "Lacking access to needed tools for generating a visual dependency graph." }
+          Giblog.logger.warn { "The dependency graph will not be generated !!" }
+          false
+        end
+      else
+        false
+      end
 
-    # load and convert the string using the converter options
-    doc = Asciidoctor.load input_str, index_opts
-    output = doc.convert index_opts
+      # build a reference index
+      ib = index_factory
+      @converter.convert_str ib.source(dep_graph_exist), @paths.dst_root_abs, "index"
 
-    # determine the correct output path
-    if output_file.nil?
-      output_file = @paths.adoc_output_file(src_path,
-                                            @converter_options[:fileext])
+      # clean up cached files and adoc resources
+      remove_diagram_temps if dep_graph_exist
+      GC.start
     end
 
-    # write the converted document to file and return the doc
-    doc.write output, output_file.to_s
-    doc
-  end
+    protected
 
-  # 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!"
+    # get the correct index builder type depending on supplied
+    # user options
+    def index_factory
+      raise "Internal logic error!" if @options[:suppressBuildRef]
+      SimpleIndexBuilder.new(@processed_docs, @paths,
+                             @options[:resolveDocid])
     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
-
-  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
-  # Public: Setup common converter options. Required options are:
-  #         :srcDirRoot
-  #         :dstDirRoot
-  #         :resourceDir
-  def initialize(options)
-    super options
-
-    # require access to asciidoc-rouge
-    require "asciidoctor-rouge"
-
-    # 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
+    # get the correct converter type
+    def converter_factory
+      case @options[:format]
+        when "html" then
+          HtmlConverter.new @paths, @options
+        when "pdf" then
+          PdfConverter.new @paths, @options
+        else
+          raise ArgumentError, "Unknown conversion format: #{@options[:format]}"
+      end
+    end
 
-  private
+    # creates a DocInfo instance, fills it with basic info and
+    # returns the filled in instance so that derived implementations can
+    # add more data
+    def add_doc(adoc, adoc_stderr)
+      Giblog.logger.debug do
+        "Adding adoc: #{adoc} Asciidoctor stderr: #{adoc_stderr}"
+      end
+      Giblog.logger.debug {"Doc attributes: #{adoc.attributes}"}
 
-  def setup_stylesheet_attributes(css_dir)
-    return {} if @paths.resource_dir_abs.nil?
+      info = DocInfo.new(adoc: adoc, dst_root_abs: @paths.dst_root_abs, adoc_stderr: adoc_stderr)
+      @processed_docs << info
+      info
+    end
 
-    # use the supplied stylesheet if there is one
-    attrib = { "linkcss" => 1,
-               "stylesdir" => css_dir,
-               "stylesheet" => "giblish.css",
-               "copycss!" => 1 }
+    def add_doc_fail(filepath, exception)
+      info = DocInfo.new
 
-    # 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
+      # the only info we have is the source file name
+      info.converted = false
+      info.src_file = filepath
+      info.error_msg = exception.message
 
-  # 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
+      @processed_docs << info
+      info
+    end
 
-    # 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)
+    private
 
-    # 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}")
+    # remove cache dir and svg image created by asciidoctor-diagram
+    # when creating the document dependency graph
+    def remove_diagram_temps
+      adoc_diag_cache = @paths.dst_root_abs.join(".asciidoctor")
+      FileUtils.remove_dir(adoc_diag_cache) if adoc_diag_cache.directory?
+      Giblog.logger.info {"Removing cached files at: #{@paths.dst_root_abs.join("docdeps.svg").to_s}"}
+      @paths.dst_root_abs.join("docdeps.svg").delete
     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
+    # convert a single adoc doc to whatever the user wants
+    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 = @converter.convert filepath
+        end
+
+        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.error {str}
+
+        add_doc_fail(filepath, e)
+      end
     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 = setup_pdf_attribs
+    # predicate that decides if a path is a asciidoc file or not
+    def adocfile?(path)
+      fs = path.basename.to_s
 
-    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"
+      unless @options[:excludeRegexp].nil?
+        # exclude file if user wishes
+        er = Regexp.new @options[:excludeRegexp]
+        return false unless er.match(fs).nil?
+      end
 
-    pdf_attrib
-  end
-end
-
-class TreeConverter
-
-  # 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[:resolveDocid],
-                                                 options[:gitRepoRoot])
-                       else
-                         SimpleIndexBuilder.new(@paths,
-                                                options[:resolveDocid])
-                       end
+      # only include files
+      ir = Regexp.new @options[:includeRegexp]
+      return !ir.match(fs).nil?
     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
+    # Register the asciidoctor extension that handles doc ids and traverse
+    # the source tree to collect all :docid: attributes found in document
+    # headers.
+    def manage_doc_ids
+      # Register the docid preprocessor hook
+      Giblish.register_extensions
+
+      # Make sure that no prior docid's are hangning around
+      DocidCollector.clear_cache
+      DocidCollector.clear_deps
+      idc = DocidCollector.new
+
+      # traverse the src file tree and collect ids from all
+      # .adoc or .ADOC files
+      Find.find(@paths.src_root_abs) do |path|
+        p = Pathname.new(path)
+        idc.parse_file(p) if adocfile? p
+      end if @paths.src_root_abs.directory?
+      idc
+    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
+  class GitRepoConverter < FileTreeConverter
+    def initialize(options)
+      super(options)
+      # cache the top of the tree since we need to redefine the
+      # paths per branch/tag later on.
+      @master_paths = @paths.dup
+      @git_repo_root = options[:gitRepoRoot]
+      @git_repo = init_git_repo @git_repo_root, options[:localRepoOnly]
+      @user_branches = select_user_branches(options[:gitBranchRegexp])
+      @user_tags = select_user_tags(options[:gitTagRegexp])
+    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
+    # Render the docs from each branch/tag and add info to the
+    # summary page
+    def convert
+      (@user_branches + @user_tags).each do |co|
+        convert_one_checkout co
       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.error { str }
-      @options[:suppressBuildRef] || @index_builder.add_doc_fail(filepath, e)
+      # Render the summary page
+      index_builder = GitSummaryIndexBuilder.new @git_repo,
+                                                 @user_branches,
+                                                 @user_tags
+      @converter.convert_str index_builder.source, @master_paths.dst_root_abs, "index"
+      # clean up
+      GC.start
     end
-  end
 
-  def walk_dirs
-    # collect all doc ids and enable replacement of known doc ids with
-    # valid references to adoc files
-    manage_doc_ids if @options[:resolveDocid]
+    protected
 
-    # traverse the src file tree and convert all files that ends with
-    # .adoc or .ADOC
-    Find.find(@paths.src_root_abs) do |path|
-      p = Pathname.new(path)
-      to_asciidoc(p) if adocfile? p
+    def index_factory
+      GitRepoIndexBuilder.new(@processed_docs, @paths,
+                              @options[:resolveDocid], @options[:gitRepoRoot])
     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
-
-  private
-
-  # predicate that decides if a path is a asciidoc file or not
-  def adocfile?(path)
-    fs = path.basename.to_s
-
-    unless @options[:excludeRegexp].nil?
-      # exclude file if user wishes
-      er = Regexp.new @options[:excludeRegexp]
-      return false unless er.match(fs).nil?
+    def add_doc(adoc, adoc_stderr)
+      info = super(adoc, adoc_stderr)
+
+      # Redefine the srcFile to mean the relative path to the git repo root
+      src_file = Pathname.new(info.src_file).relative_path_from(@git_repo_root).to_s
+      # Get the commit history of the doc
+      # (use a homegrown git log to get 'follow' flag)
+      gi = Giblish::GitItf.new(@git_repo_root)
+      gi.file_log(src_file).each do |i|
+        h = DocInfo::DocHistory.new
+        h.date = i["date"]
+        h.message = i["message"]
+        h.author = i["author"]
+        info.history << h
+      end
     end
 
-    # only include files
-    ir = Regexp.new @options[:includeRegexp]
-    return !ir.match(fs).nil?
-  end
+    private
 
-  # Register the asciidoctor extension that handles doc ids and traverse
-  # the source tree to collect all :docid: attributes found in document
-  # headers.
-  def manage_doc_ids
-    # Register the docid preprocessor hook
-    Giblish.register_extensions
-
-    # Make sure that no prior docid's are hangning around
-    Giblish::DocidCollector.clear_cache
-    idc = Giblish::DocidCollector.new
-
-    # traverse the src file tree and collect ids from all
-    # .adoc or .ADOC files
-    Find.find(@paths.src_root_abs) do |path|
-      p = Pathname.new(path)
-      idc.parse_file(p) if adocfile? p
-    end
-    idc
-  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} !"\
+    def init_git_repo(git_repo_root, local_only)
+      # 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
+      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"\
+      # fetch all remote refs if ok with user
+      begin
+        git_repo.fetch unless local_only
+      rescue Exception => e
+        raise "Could not fetch from origin"\
             "(do you need '--local-only'?)!\n\n(#{e.message})"
+      end
+      git_repo
     end
 
-    # initialize summary builder
-    @index_builder = GitSummaryIndexBuilder.new @git_repo
+    # Get the branches/tags the user wants to parse
+    def select_user_branches(checkout_regexp)
+      return unless @options[:gitBranchRegexp]
 
-    # 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 = Regexp.new checkout_regexp
+      user_checkouts = @git_repo.branches.remote.select do |b|
         # match branches but remove eventual HEAD -> ... entry
         regexp.match b.name unless b.name =~ /^HEAD/
       end
-      Giblog.logger.debug { "selected git branches: #{@user_branches}" }
-
-      # 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
+      Giblog.logger.debug {"selected git branches: #{user_checkouts}"}
+      user_checkouts
     end
 
-    # Get the tags 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
+    def select_user_tags(tag_regexp)
+      return [] unless tag_regexp
 
-      # 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
+      regexp = Regexp.new @options[:gitTagRegexp]
+      tags = @git_repo.tags.select do |t|
+        regexp.match t.name
       end
+      tags
     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
+    def convert_one_checkout(co)
+      # determine if we are called with a tag or a branch
+      is_tag = (co.respond_to?(:tag?) && co.tag?)
 
-    # 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
+      Giblog.logger.info {"Checking out #{co.name}"}
+      @git_repo.checkout co.name
 
-    unless is_tag
-      Giblog.logger.info { "Merging with origin/#{b.name}" }
-      @git_repo.merge "origin/#{b.name}"
-    end
+      unless is_tag
+        # if this is a branch, make sure it is up-to-date
+        Giblog.logger.info {"Merging with origin/#{co.name}"}
+        @git_repo.merge "origin/#{co.name}"
+      end
 
-    # assign a branch-unique dst-dir
-    dir_name = b.name.tr("/", "_") << "/"
+      # assign a checkout-unique dst-dir
+      dir_name = co.name.tr("/", "_") << "/"
 
-    # Assign the branch specific dir as new destination root
-    options[:dstDirRoot] = @paths.dst_root_abs.realpath.join(dir_name).to_s
+      # Update needed base class members before converting a new checkout
+      @processed_docs = []
+      @paths.dst_root_abs = @master_paths.dst_root_abs.realpath.join(dir_name)
+      # @converter.paths = @paths
 
-    # Parse and render docs using given args
-    Giblog.logger.info { "Render docs to dir #{options[:dstDirRoot]}" }
-    tc = TreeConverter.new options
-    tc.walk_dirs
+      # Parse and convert docs using given args
+      Giblog.logger.info {"Convert docs into dir #{@paths.dst_root_abs}"}
+      # parent_convert
+      FileTreeConverter.instance_method(:convert).bind(self).call
+    end
   end
-end
+end