giblish 0.2.12 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d124070b2a70ba613898e4ec4a55c0077b4721f8
-  data.tar.gz: 9ea41006b11273f084ae4afd2172b0e0ee5c0679
+SHA256:
+  metadata.gz: 9db70ccddaf7473a9da59c81a9a592635a027faa4ffbec31a7d30a976c9fa7c6
+  data.tar.gz: a2c1034a4ef601d1f37ec1402d07de6258d1273a8524e4b6347418f0fb42cd2e
 SHA512:
-  metadata.gz: 8c0bbd5e18a496e0405fcc9fb752102bb294d433914e46de814ad3923391b267ec8767711de17dd6258e235f2feb26126f3fc8107b8eb3040215c39a851ffe8f
-  data.tar.gz: 507dc447a1d08255a81c2cf678e3e7e0571be4317da4bc7ab2286da17ac76f93f7f21d0a2aa25eb2304a20f7c68e676cfb42dfa067e43f745a3db725beac520c
+  metadata.gz: 05d9414c48c69d13eec80cbedc5d5a6049d711e53af054a7d26af9192e7845ec114667459ab090af3c0fab610f1c3f6b50629b15a51024fc5f15b01dc546d87d
+  data.tar.gz: da0330a4f1fe0fd9b009fa2689dda4b2f6f9e95e76acd9ba6755055d252e8b1b62d0ed974cbb7ca5ddbf0dd408781d9915dff68f843c9b8cec472115d7287d1d

data/.ruby-version

@@ -0,0 +1 @@
+2.5.3

data/Rakefile

@@ -7,11 +7,10 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-Rake::TestTask.new(:current_test) do |t|
+Rake::TestTask.new(:current) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/run_test.rb"]
-  # t.test_files = FileList["test/**/docid_test.rb"]
+  t.test_files = FileList["test/**/depgraph_test.rb"]
 end
 
 Rake::TestTask.new(:sandbox) do |t|

data/giblish.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
 
   # Usage: spec.add_runtime_dependency "[gem name]", [[version]]
   spec.add_runtime_dependency "asciidoctor", "~>1.5", ">= 1.5.7.1"
+  spec.add_runtime_dependency "asciidoctor-diagram", ["~> 1.5"]
   spec.add_runtime_dependency "asciidoctor-pdf", [">= 1.5.0.alpha.16"]
   spec.add_runtime_dependency "asciidoctor-rouge", ["~> 0.3"]
   spec.add_runtime_dependency "git", "~> 1.3"

data/lib/giblish/application.rb

@@ -6,15 +6,22 @@ require_relative "utils"
 module Giblish
   class Application
 
+    # return exit status (0 for success)
     def run_with_args(args)
       run args
     end
 
+    # does not return, exits with status code
     def run_from_cmd_line
-      run ARGV
+      status = run ARGV
+      exit(status)
     end
 
+    # return exit status (0 for success)
     def run(args)
+      # force immediate output
+      $stdout.sync = true
+
       # setup logging
       Giblog.setup
 
@@ -27,15 +34,17 @@ module Giblish
       begin
         if cmdline.args[:gitRepoRoot]
           Giblog.logger.info { "User asked to parse a git repo" }
-          GitRepoParser.new cmdline.args
+          gc = GitRepoConverter.new cmdline.args
+          gc.convert
         else
-          tc = TreeConverter.new cmdline.args
-          tc.walk_dirs
+          tc = FileTreeConverter.new cmdline.args
+          tc.convert
         end
         Giblog.logger.info { "Giblish is done!" }
+        0
       rescue Exception => e
         log_error e
-        exit(1)
+        1
       end
     end
 

data/lib/giblish/buildgraph.rb

@@ -0,0 +1,179 @@
+
+module Giblish
+  # Builds an asciidoc page with an svg image with a
+  # digraph showing how documents reference each other.
+  #
+  # Graphviz is used as the graph generator and must be available
+  # as a valid engine via asciidoctor-diagram for this class to work.
+  class GraphBuilderGraphviz
+
+    # the dependency graph relies on graphwiz (dot), check if we can access that
+    def self.supported
+      return !Giblish.which('dot').nil?
+    end
+
+    # Supported options:
+    # :extension - file extension for URL links (default is .html)
+    def initialize(processed_docs, paths, options = {})
+
+      # this class relies on graphwiz (dot), make sure we can access that
+      raise "Could not find the 'dot' tool needed to generate a dependency graph!" unless GraphBuilderGraphviz.supported
+
+      # require asciidoctor module needed for generating diagrams
+      require "asciidoctor-diagram/graphviz"
+
+      @noid_docs = {}
+      @next_id = 0
+      @processed_docs = processed_docs
+      @paths = paths
+      @options = options.dup
+      @extension = options.key?(:extension) ? options[:extension] : "html"
+      @docid_cache = DocidCollector.docid_cache
+      @docid_deps =  DocidCollector.docid_deps
+      @dep_graph = build_dep_graph
+    end
+
+    # get the asciidoc source for the document.
+    def source
+      <<~DOC_STR
+        #{generate_header}
+        #{generate_labels}
+        #{generate_deps}
+        #{generate_footer}
+      DOC_STR
+    end
+
+    private
+
+    # build a hash with {DocInfo => [doc_id array]}
+    def build_dep_graph
+      result = {}
+      @docid_deps.each do |src_file, id_array|
+        d = @processed_docs.find do |doc|
+          doc.src_file.to_s.eql? src_file
+        end
+        raise "Inconsistent docs when building graph!! found no match for #{src_file}" if d.nil?
+        result[d] = id_array
+      end
+      result
+    end
+
+    def generate_header
+      t = Time.now
+      <<~DOC_STR
+        = Document-id reference graph
+        from #{@paths.src_root_abs}
+
+        Generated by Giblish at::
+        #{t.strftime('%Y-%m-%d %H:%M')}
+
+        Below is a graph that visualizes what documents (by doc-id) a specific
+        document references.
+
+        [graphviz,"docdeps","svg",options="inline"]
+        ....
+        digraph notebook {
+          bgcolor="#33333310"
+          node [shape=note,
+                fillcolor="#ebf26680",
+                style="filled,solid"
+              ]
+        
+        rankdir="LR"
+
+      DOC_STR
+    end
+
+    def generate_footer
+      <<~DOC_STR
+        }
+        ....
+      DOC_STR
+    end
+
+    def make_dot_entry(doc_dict, info)
+      # split title into multiple rows if it is too long
+      line_length = 15
+      lines = [""]
+      info.title.split(" ").inject("") do |l,w|
+        line = l + " " + w
+        lines[-1] = line
+        if line.length > line_length
+          # create a new, empty, line
+          lines << ""
+          ""
+        else
+          line
+        end
+      end unless info.title.nil?
+      title = lines.select { |l| l.length > 0 }.map {|l| l}.join("\n")
+
+      # create the label used to display the node in the graph
+      dot_entry = if info.doc_id.nil?
+                    doc_id = next_fake_id
+                    @noid_docs[info] = doc_id
+                    "\"#{doc_id}\"[label=\"-\\n#{title}\""
+                  else
+                    doc_id = info.doc_id
+                    "\"#{info.doc_id}\"[label=\"#{info.doc_id}\\n#{title}\""
+                  end
+      # add clickable links in the case of html output (this is not supported
+      # out-of-the-box for pdf).
+      rp = info.rel_path.sub_ext(".#{@extension}")
+      case @extension
+        when "html"
+          dot_entry += ", URL=\"#{rp}\" ]"
+        else
+          dot_entry += " ]"
+      end
+      doc_dict[doc_id] = dot_entry
+    end
+
+    def generate_labels
+      # create an entry in the 'dot' description for each
+      # document, sort them according to descending doc id to
+      # get them displayed in the opposite order in the graph
+      node_dict = {}
+      @dep_graph.each_key do |info|
+        make_dot_entry node_dict, info
+      end
+      # sort the nodes by reverse doc id
+      node_dict = node_dict.sort.reverse.to_h
+
+      # produce the string with all node entries
+      node_str = node_dict.map do |k,v|
+        v
+      end.join("\n")
+      node_str
+    end
+
+    def generate_deps
+      dep_str = ""
+      @dep_graph.each do |info, targets|
+        # set either the real or the generated id as source
+        src_part = if info.doc_id.nil?
+                      "\"#{@noid_docs[info]}\""
+                   else
+                     "\"#{info.doc_id}\""
+                   end
+
+        if targets.length.zero?
+          dep_str += "#{src_part}\n"
+          next
+        end
+
+        dep_str += "#{src_part} -> {" + targets.reduce("") do |acc, target|
+          acc + " \"#{target}\""
+        end
+        # replace last comma with newline
+        dep_str += "}\n"
+      end
+      dep_str
+    end
+
+    def next_fake_id
+      @next_id += 1
+      "_generated_id_#{@next_id.to_s.rjust(4, '0')}"
+    end
+  end
+end

data/lib/giblish/buildindex.rb

@@ -1,504 +1,451 @@
-#!/usr/bin/env ruby
-#
-
 require "pathname"
 require "git"
-require_relative "cmdline"
+
 require_relative "pathtree"
 require_relative "gititf"
+require_relative "docinfo"
+
+module Giblish
+
+  # Base class with common functionality for all index builders
+  class BasicIndexBuilder
+    # set up the basic index building info
+    def initialize(processed_docs, path_manager, handle_docid = false)
+      @paths = path_manager
+      @nof_missing_titles = 0
+      @processed_docs = processed_docs
+      @src_str = ""
+      @manage_docid = handle_docid
+    end
 
-# Container class for bundling together the data we cache for
-# each asciidoc file we come across
-class DocInfo
-  # Cache git info
-  class DocHistory
-    attr_accessor :date
-    attr_accessor :author
-    attr_accessor :message
-  end
+    def source(dep_graph_exists = false)
+      <<~DOC_STR
+        #{generate_header}
+        #{generate_tree(dep_graph_exists)}
+        #{generate_details}
+        #{generate_footer}
+      DOC_STR
+    end
 
-  attr_accessor :converted
-  attr_accessor :title
-  attr_accessor :doc_id
-  attr_accessor :purpose_str
-  attr_accessor :status
-  attr_accessor :history
-  attr_accessor :error_msg
-  attr_accessor :stderr
-  # these two members can have encoding issues when
-  # running in a mixed Windows/Linux setting.
-  # that is why the explicit utf-8 read methods are
-  # provided.
-  attr_accessor :relPath
-  attr_accessor :srcFile
-
-  def relPath_utf8
-    return nil if @relPath.nil?
-    @relPath.to_s.encode("utf-8")
-  end
+    protected
+    # return the adoc string for displaying the source file
+    def display_source_file(doc_info)
+      <<~SRC_FILE_TXT
+        Source file::
+        #{doc_info.srcFile_utf8}
 
-  def srcFile_utf8
-    return nil if @srcFile.nil?
-    @srcFile.to_s.encode("utf-8")
-  end
+      SRC_FILE_TXT
+    end
 
-  def initialize
-    @history = []
-  end
+    def generate_header
+      t = Time.now
+      <<~DOC_HEADER
+        = Document index
+        from #{@paths.src_root_abs}
 
-  def to_s
-    "DocInfo: title: #{@title} srcFile: #{srcFile_utf8}"
-  end
-end
-
-# Base class with common functionality for all index builders
-class BasicIndexBuilder
-  # set up the basic index building info
-  def initialize(path_manager, handle_docid = false)
-    @paths = path_manager
-    @nof_missing_titles = 0
-    @added_docs = []
-    @src_str = ""
-    @manage_docid = handle_docid
-  end
+        Generated by Giblish at::
 
-  # 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 { "Adding adoc: #{adoc} Asciidoctor stderr: #{adoc_stderr}" }
-    Giblog.logger.debug {"Doc attributes: #{adoc.attributes}"}
-
-    info = DocInfo.new
-    info.converted = true
-    info.stderr = adoc_stderr
-
-    # Get the purpose info if it exists
-    info.purpose_str = get_purpose_info adoc
-
-    # Get the relative path beneath the root dir to the doc
-    d_attr = adoc.attributes
-    info.relPath = Pathname.new(
-      "#{d_attr['outdir']}/#{d_attr['docname']}#{d_attr['docfilesuffix']}"
-    ).relative_path_from(
-      @paths.dst_root_abs
-    )
-
-    # Get the doc id if it exists
-    info.doc_id = adoc.attributes["docid"]
-
-    # Get the source file path
-    info.srcFile = adoc.attributes["docfile"]
-
-    # If a docid exists, set titel to docid - title if we care about
-    # doc ids.
-    info.title = if !info.doc_id.nil? && @manage_docid
-                   "#{info.doc_id} - #{adoc.doctitle}"
-                 else
-                   adoc.doctitle
-                 end
-
-    # Cache the created DocInfo
-    @added_docs << info
-    info
-  end
+        #{t.strftime('%Y-%m-%d %H:%M')}
 
-  def add_doc_fail(filepath, exception)
-    info = DocInfo.new
+      DOC_HEADER
+    end
 
-    # the only info we have is the source file name
-    info.converted = false
-    info.srcFile = filepath
-    info.error_msg = exception.message
+    def get_docid_statistics
+      largest = ""
+      clash = []
+      @processed_docs.each do |d|
+        # get the lexically largest doc id
+        largest = d.doc_id if !d.doc_id.nil? && d.doc_id > largest
 
-    # Cache the DocInfo
-    @added_docs << info
-    info
-  end
+        # collect all ids in an array to find duplicates later on
+        clash << d.doc_id unless d.doc_id.nil?
+      end
+      # find the duplicate doc ids (if any)
+      duplicates = clash.select { |id| clash.count(id) > 1 }.uniq.sort
 
-  def index_source
-    <<~DOC_STR
-      #{generate_header}
-      #{generate_tree}
-      #{generate_details}
-      #{generate_footer}
-    DOC_STR
-  end
+      return largest,duplicates
+    end
 
-  protected
+    def generate_doc_id_info(dep_graph_exists)
+      largest,duplicates = get_docid_statistics
+      docid_info_str = if ! @manage_docid
+                         ""
+                       else
+                         "The 'largest' document id found when resolving :docid: tags is *#{largest}*."
+                       end
 
-  def generate_header
-    t = Time.now
-    <<~DOC_HEADER
-      = Document index
-      from #{@paths.src_root_abs}
+      docid_warn_str = if duplicates.length.zero?
+                         ""
+                       else
+                         "WARNING: The following document ids are used for more than one document. " +
+                             "_#{duplicates.map {|id| id.to_s}.join(",") }_"
+                       end
 
-      Generated by Giblish at::
+      # include link to dependency graph if it exists
+      dep_graph_str = if dep_graph_exists
+                        "_(a visual graph of document dependencies can be found " \
+                      "<<./graph.adoc#,here>>)_"
+                      else
+                        ""
+                      end
+
+      if @manage_docid
+        <<~DOC_ID_INFO
+        Document id numbers::
+        The generation of this repository uses document id numbers. #{docid_info_str} #{dep_graph_str}
+  
+        #{docid_warn_str}
+
+        DOC_ID_INFO
+      else
+        ""
+      end
+    end
 
-      #{t.strftime('%Y-%m-%d %H:%M')}
+    def generate_tree(dep_graph_exists)
+      # output tree intro
+      tree_string = <<~DOC_HEADER
+        == Document Overview
 
-    DOC_HEADER
-  end
+        _Click on the title to open the document or on `details` to see more
+        info about the document. A `(warn)` label indicates that there were
+        warnings while converting the document from its asciidoc format._
 
-  def generate_footer
-    ""
-  end
+        #{generate_doc_id_info dep_graph_exists}
 
-  private
-
-  def get_purpose_info(adoc)
-    # Get the 'Purpose' section if it exists
-    purpose_str = ""
-    adoc.blocks.each do |section|
-      next unless section.is_a?(Asciidoctor::Section) &&
-                  (section.level == 1) &&
-                  (section.name =~ /^Purpose$/)
-      purpose_str = "Purpose::\n\n"
-
-      # filter out 'odd' text, such as lists etc...
-      section.blocks.each do |bb|
-        next unless bb.is_a?(Asciidoctor::Block)
-        purpose_str << "#{bb.source}\n+\n"
-      end
-    end
-    purpose_str
-  end
+        [subs=\"normal\"]
+        ----
+      DOC_HEADER
 
-  def generate_conversion_info(d)
-    return "" if d.stderr.empty?
-    # extract conversion warnings from asciddoctor std err
-    conv_warnings = d.stderr.gsub("asciidoctor:", "\n * asciidoctor:")
-    Giblog.logger.warn { "Conversion warnings: #{conv_warnings}" }
+      # build up tree of paths
+      root = PathTree.new
+      @processed_docs.each do |d|
+        root.add_path(d.rel_path.to_s, d)
+      end
 
-    # assemble info to index page
-    <<~CONV_INFO
-      Conversion info::
+      # generate each tree entry string
+      root.traverse_top_down do |level, node|
+        tree_string << tree_entry_string(level, node)
+      end
 
-      #{conv_warnings}
-    CONV_INFO
-  end
+      # generate the tree footer
+      tree_string << "\n----\n"
+    end
 
-  # Private: Return adoc elements for displaying a clickable title
-  # and a 'details' ref that points to a section that uses the title as an id.
-  #
-  # Returns [ clickableTitleStr, clickableDetailsStr ]
-  def format_title_and_ref(doc_info)
-    unless doc_info.title
-      @nof_missing_titles += 1
-      doc_info.title = "NO TITLE FOUND (#{@nof_missing_titles}) !"
+    def generate_footer
+      ""
     end
-    return "<<#{doc_info.relPath_utf8}#,#{doc_info.title}>>".encode("utf-8"),
-    "<<#{Giblish.to_valid_id(doc_info.title)},details>>\n".encode("utf-8")
-  end
 
-  # Generate an adoc string that will display as
-  # DocTitle         (warn)  details
-  # Where the DocTitle and details are links to the doc itself and a section
-  # identified with the doc's title respectively.
-  def tree_entry_converted(prefix_str, doc_info)
-    # Get the elements of the entry
-    doc_title, doc_details = format_title_and_ref doc_info
-    warning_label = doc_info.stderr.empty? ? "" : "(warn)"
-
-    # Calculate padding to get (warn) and details aligned between entries
-    padding = 80
-    [doc_info.title, prefix_str, warning_label].each { |p| padding -= p.length }
-    padding = 0 unless padding.positive?
-    "#{prefix_str} #{doc_title}#{' ' * padding}#{warning_label} #{doc_details}"
-  end
+    private
 
-  def tree_entry_string(level, node)
-    # indent 2 * level
-    prefix_str = "  " * (level + 1)
+    def generate_conversion_info(d)
+      return "" if d.stderr.empty?
+      # extract conversion warnings from asciddoctor std err
+      conv_warnings = d.stderr.gsub("asciidoctor:", "\n * asciidoctor:")
+      Giblog.logger.warn {"Conversion warnings: #{conv_warnings}"}
 
-    # return only name for directories
-    return "#{prefix_str} #{node.name}\n" unless node.leaf?
+      # assemble info to index page
+      <<~CONV_INFO
+        Conversion info::
 
-    # return links to content and details for files
-    d = node.data
-    if d.converted
-      tree_entry_converted prefix_str, d
-    else
-      # no converted file exists, show what we know
-      "#{prefix_str} FAIL: #{d.srcFile_utf8}      <<#{d.srcFile_utf8},details>>\n"
+        #{conv_warnings}
+      CONV_INFO
     end
-  end
 
-  def generate_tree
-    # build up tree of paths
-    root = PathTree.new
-    @added_docs.each do |d|
-      root.add_path(d.relPath.to_s, d)
-    end
+    # Private: Return adoc elements for displaying a clickable title
+    # and a 'details' ref that points to a section that uses the title as an id.
+    #
+    # Returns [ title, clickableTitleStr, clickableDetailsStr ]
+    def format_title_and_ref(doc_info)
+      unless doc_info.title
+        @nof_missing_titles += 1
+        doc_info.title = "NO TITLE FOUND (#{@nof_missing_titles}) !"
+      end
 
-    # output tree intro
-    tree_string = <<~DOC_HEADER
-      == Document Overview
+      # Manipulate the doc title if we have a doc id
+      title = if !doc_info.doc_id.nil? && @manage_docid
+                "#{doc_info.doc_id} - #{doc_info.title}"
+              else
+                doc_info.title
+              end
 
-      _Click on the title to open the document or on `details` to see more
-      info about the document. A `(warn)` label indicates that there were
-      warnings while converting the document._
+      [title, "<<#{doc_info.rel_path}#,#{title}>>".encode("utf-8"),
+       "<<#{Giblish.to_valid_id(doc_info.title)},details>>\n".encode("utf-8")]
+    end
 
-      [subs=\"normal\"]
-      ----
-    DOC_HEADER
+    # Generate an adoc string that will display as
+    # DocTitle         (warn)  details
+    # Where the DocTitle and details are links to the doc itself and a section
+    # identified with the doc's title respectively.
+    def tree_entry_converted(prefix_str, doc_info)
+      # Get the elements of the entry
+      doc_title, doc_link, doc_details = format_title_and_ref doc_info
+      warning_label = doc_info.stderr.empty? ? "" : "(warn)"
+
+      # Calculate padding to get (warn) and details aligned between entries
+      padding = 70
+      [doc_title, prefix_str, warning_label].each {|p| padding -= p.length}
+      padding = 0 unless padding.positive?
+      "#{prefix_str} #{doc_link}#{' ' * padding}#{warning_label} #{doc_details}"
+    end
 
-    # generate each tree entry string
-    root.traverse_top_down do |level, node|
-      tree_string << tree_entry_string(level, node)
+    def tree_entry_string(level, node)
+      # indent 2 * level
+      prefix_str = "  " * (level + 1)
+
+      # return only name for directories
+      return "#{prefix_str} #{node.name}\n" unless node.leaf?
+
+      # return links to content and details for files
+      # node.data is a DocInfo instance
+      d = node.data
+      if d.converted
+        tree_entry_converted prefix_str, d
+      else
+        # no converted file exists, show what we know
+        "#{prefix_str} FAIL: #{d.srcFile_utf8}      <<#{d.srcFile_utf8},details>>\n"
+      end
     end
 
-    # generate the tree footer
-    tree_string << "\n----\n"
-  end
+    # Derived classes can override this with useful info
+    def generate_history_info(_d)
+      ""
+    end
 
-  # Derived classes can override this with useful info
-  def generate_history_info(_d)
-    ""
-  end
+    def generate_detail_fail(d)
+      <<~FAIL_INFO
+        === #{d.srcFile_utf8}
 
-  def generate_detail_fail(d)
-    <<~FAIL_INFO
-      === #{d.srcFile_utf8}
+        #{display_source_file(d)}
 
-      Source file::
+        Error detail::
+        #{d.stderr}
 
-      #{d.srcFile_utf8}
+        ''''
 
-      Error detail::
-      #{d.stderr}
+      FAIL_INFO
+    end
 
-      ''''
+    def generate_detail(d)
+      # Generate detail info
+      purpose_str = if d.purpose_str.nil?
+                      ""
+                    else
+                      "Purpose::\n#{d.purpose_str}"
+                    end
 
-    FAIL_INFO
-  end
+      doc_id_str = if !d.doc_id.nil? && @manage_docid
+                     "Doc id::\n_#{d.doc_id}_"
+                   else
+                     ""
+                   end
 
-  def generate_detail(d)
-    # Generate detail info
-    <<~DETAIL_SRC
-      [[#{Giblish.to_valid_id(d.title.encode("utf-8"))}]]
-      === #{d.title.encode("utf-8")}
+      <<~DETAIL_SRC
+        [[#{Giblish.to_valid_id(d.title.encode("utf-8"))}]]
+        === #{d.title.encode("utf-8")}
 
-      #{d.purpose_str}
+        #{doc_id_str}
 
-      #{generate_conversion_info d}
+        #{purpose_str}
 
-      Source file::
-      #{d.srcFile_utf8}
+        #{generate_conversion_info d}
 
-      #{generate_history_info d}
+        #{display_source_file(d)}
 
-      ''''
+        #{generate_history_info d}
 
-    DETAIL_SRC
-  end
+        ''''
 
-  def generate_details
-    root = PathTree.new
-    @added_docs.each do |d|
-      root.add_path(d.relPath.to_s, d)
+      DETAIL_SRC
     end
 
-    details_str = "== Document details\n\n"
+    def generate_details
+      root = PathTree.new
+      @processed_docs.each do |d|
+        root.add_path(d.rel_path.to_s, d)
+      end
 
-    root.traverse_top_down do |_level, node|
-      details_str << if node.leaf?
-                       d = node.data
-                       if d.converted
-                         generate_detail(d)
+      details_str = "== Document details\n\n"
+
+      root.traverse_top_down do |_level, node|
+        details_str << if node.leaf?
+                         d = node.data
+                         if d.converted
+                           generate_detail(d)
+                         else
+                           generate_detail_fail(d)
+                         end
                        else
-                         generate_detail_fail(d)
+                         ""
                        end
-                     else
-                       ""
-                     end
-    end
-    details_str
-  end
-end
-
-# A simple index generator that shows a table with the generated documents
-class SimpleIndexBuilder < BasicIndexBuilder
-  def initialize(path_manager, manage_docid = false)
-    super path_manager, manage_docid
-  end
-
-  def add_doc(adoc, adoc_stderr)
-    super(adoc, adoc_stderr)
-  end
-end
-
-# Builds an index of the generated documents and includes some git metadata
-# repository
-class GitRepoIndexBuilder < BasicIndexBuilder
-  def initialize(path_manager, manage_docid, git_repo_root)
-    super path_manager, manage_docid
-
-    # initialize state variables
-    @git_repo_root = git_repo_root
-
-    # no repo root given...
-    return unless @git_repo_root
-
-    begin
-      # Make sure that we can "talk" to git if user feeds us
-      # a git repo root
-      @git_repo = Git.open(@git_repo_root)
-    rescue Exception => e
-      Giblog.logger.error { "No git repo! exception: #{e.message}" }
+      end
+      details_str
     end
   end
 
-  def add_doc(adoc, adoc_stderr)
-    info = super(adoc, adoc_stderr)
-
-    # Redefine the srcFile to mean the relative path to the git repo root
-    info.srcFile = Pathname.new(info.srcFile).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(info.srcFile_utf8).each do |i|
-      h = DocInfo::DocHistory.new
-      h.date = i["date"]
-      h.message = i["message"]
-      h.author = i["author"]
-      info.history << h
+  # A simple index generator that shows a table with the generated documents
+  class SimpleIndexBuilder < BasicIndexBuilder
+    def initialize(processed_docs, path_manager, manage_docid = false)
+      super processed_docs, path_manager, manage_docid
     end
   end
 
-  protected
-
-  def generate_header
-    t = Time.now
-    <<~DOC_HEADER
-      = Document index
-      #{@git_repo.current_branch}
-
-      Generated by Giblish at::
-
-      #{t.strftime('%Y-%m-%d %H:%M')}
-
-    DOC_HEADER
-  end
-
-  def generate_history_info(d)
-    str = <<~HISTORY_HEADER
-      File history::
-
-      [cols=\"2,3,8\",options=\"header\"]
-      |===
-      |Date |Author |Message
-    HISTORY_HEADER
+  # Builds an index of the generated documents and includes some git metadata
+  # from the repository
+  class GitRepoIndexBuilder < BasicIndexBuilder
+    def initialize(processed_docs, path_manager, manage_docid, git_repo_root)
+      super processed_docs, path_manager, manage_docid
 
-    # Generate table rows of history information
-    d.history.each do |h|
-      str << <<~HISTORY_ROW
-        |#{h.date.strftime('%Y-%m-%d')}
-        |#{h.author}
-        |#{h.message}
+      # no repo root given...
+      return unless git_repo_root
 
-      HISTORY_ROW
+      begin
+        # Make sure that we can "talk" to git if user feeds us
+        # a git repo root
+        @git_repo = Git.open(git_repo_root)
+        @git_repo_root = git_repo_root
+      rescue Exception => e
+        Giblog.logger.error {"No git repo! exception: #{e.message}"}
+      end
     end
-    str << "|===\n\n"
-  end
-end
-
-# Builds an index page with a summary of what branches have
-# been generated
-class GitSummaryIndexBuilder
-  def initialize(repo)
-    @branches = []
-    @tags = []
-    @git_repo = repo
-    @repo_url = repo.remote.url
-  end
 
-  def add_branch(b)
-    @branches << b
-  end
+    protected
+    # override basic version and use the relative path to the
+    # git repo root instead
+    def display_source_file(doc_info)
+      # Use the path relative to the git repo root as display
+      src_file = Pathname.
+          new(doc_info.src_file).
+          relative_path_from(@git_repo_root).to_s
+      <<~SRC_FILE_TXT
+        Source file::
+        #{src_file}
+
+      SRC_FILE_TXT
+    end
 
-  def add_tag(t)
-    @tags << t
-  end
 
-  def index_source
-    <<~ADOC_SRC
-      #{generate_header}
-      #{generate_branch_info}
-      #{generate_tag_info}
-      #{generate_footer}
-    ADOC_SRC
-  end
+    def generate_header
+      t = Time.now
+      <<~DOC_HEADER
+        = Document index
+        #{@git_repo.current_branch}
 
-  private
+        Generated by Giblish at::
+        #{t.strftime('%Y-%m-%d %H:%M')}
 
-  def generate_header
-    t = Time.now
-    <<~DOC_HEADER
-      = Document repository
-      From #{@repo_url}
+      DOC_HEADER
+    end
 
-      Generated by Giblish at::
+    def generate_history_info(d)
+      str = <<~HISTORY_HEADER
+        File history::
 
-      #{t.strftime('%Y-%m-%d %H:%M')}
+        [cols=\"2,3,8\",options=\"header\"]
+        |===
+        |Date |Author |Message
+      HISTORY_HEADER
 
-    DOC_HEADER
-  end
+      # Generate table rows of history information
+      d.history.each do |h|
+        str << <<~HISTORY_ROW
+          |#{h.date.strftime('%Y-%m-%d')}
+          |#{h.author}
+          |#{h.message}
 
-  def generate_footer
-    ""
+        HISTORY_ROW
+      end
+      str << "|===\n\n"
+    end
   end
 
-  def generate_branch_info
-    return "" if @branches.empty?
+  # Builds an index page with a summary of what branches have
+  # been generated
+  class GitSummaryIndexBuilder
+    def initialize(repo, branches, tags)
+      @branches = branches
+      @tags = tags
+      @git_repo = repo
+      @repo_url = repo.remote.url
+    end
 
-    # get the branch-unique dst-dir
-    str = <<~BRANCH_INFO
-      == Branches
+    def source
+      <<~ADOC_SRC
+        #{generate_header}
+        #{generate_branch_info}
+        #{generate_tag_info}
+        #{generate_footer}
+      ADOC_SRC
+    end
 
-    BRANCH_INFO
+    private
 
-    @branches.each do |b|
-      dirname = b.name.tr "/", "_"
-      str << " * link:#{dirname}/index.html[#{b.name}]\n"
-    end
-    str
-  end
+    def generate_header
+      t = Time.now
+      <<~DOC_HEADER
+        = Document repository
+        From #{@repo_url}
 
-  def generate_tag_info
-    return "" if @tags.empty?
+        Generated by Giblish at::
+        #{t.strftime('%Y-%m-%d %H:%M')}
 
-    # get the branch-unique dst-dir
-    str = <<~TAG_INFO
-      == Tags
+      DOC_HEADER
+    end
 
-      |===
-      |Tag |Tag comment |Creator |Tagged commit 
+    def generate_footer
+      ""
+    end
 
-    TAG_INFO
+    def generate_branch_info
+      return "" if @branches.empty?
 
-    str << @tags.collect do |t|
-      dirname = t.name.tr "/", "_"
-      c = @git_repo.gcommit(t.sha)
+      # get the branch-unique dst-dir
+      str = <<~BRANCH_INFO
+        == Branches
 
-      <<~A_ROW
-        |link:#{dirname}/index.html[#{t.name}]
-        |#{t.annotated? ? t.message : "-"}
-        |#{t.annotated? ? t.tagger.name : "-"}
-        |#{t.sha[0,8]}... committed at #{c.author.date}
-      A_ROW
-    end.join("\n")
+      BRANCH_INFO
 
-    str << "|===\n"
+      @branches.each do |b|
+        dirname = b.name.tr "/", "_"
+        str << " * link:#{dirname}/index.html[#{b.name}]\n"
+      end
+      str
+    end
 
-    # @tags.each do |t|
-    #   dirname = t.name.tr "/", "_"
-    #   str << " * link:#{dirname}/index.html[#{t.name}]"
-    #   if t.annotated?
-    #     str << "created at #{t.tagger.date} by #{t.tagger.name} with message: #{t.message}"
-    #   end
-    # end
-    str
+    def generate_tag_info
+      return "" if @tags.empty?
+
+      # get the branch-unique dst-dir
+      str = <<~TAG_INFO
+        == Tags
+        
+        |===
+        |Tag |Tag comment |Creator |Tagged commit 
+
+      TAG_INFO
+
+      str << @tags.collect do |t|
+        dirname = t.name.tr "/", "_"
+        c = @git_repo.gcommit(t.sha)
+
+        <<~A_ROW
+          |link:#{dirname}/index.html[#{t.name}]
+          |#{t.annotated? ? t.message : "-"}
+          |#{t.annotated? ? t.tagger.name : "-"}
+          |#{t.sha[0, 8]}... committed at #{c.author.date}
+        A_ROW
+      end.join("\n")
+
+      str << "|===\n"
+
+      # @tags.each do |t|
+      #   dirname = t.name.tr "/", "_"
+      #   str << " * link:#{dirname}/index.html[#{t.name}]"
+      #   if t.annotated?
+      #     str << "created at #{t.tagger.date} by #{t.tagger.name} with message: #{t.message}"
+      #   end
+      # end
+      str
+    end
   end
-end
+end