giblish 2.1.2 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22133b3cded62a83b48e863debd9f87aa046934504fa382251b96253926e7475
-  data.tar.gz: 59aaff1c7e7264fd3e02303dd07b8ffe736b66b41ea62af23bc5a9923cfa0de8
+  metadata.gz: 695c1b3dfb96c74e96d97663179345ab09f875bfb0839ea1816b6599d61d4721
+  data.tar.gz: 15d5cac96d3d8fbcdcc418a9e62385bec617699139203d8c94ccc1080f90b3f8
 SHA512:
-  metadata.gz: 01c930aa02c6cbb16325f3fb9981bd1d53396d992e7386cc189fa6c21804e872d56da7a6a343f0988c9403697bf64c3b5ea583363c9433813fcd0d65aa82f149
-  data.tar.gz: b1cb48faa21d4305adf4981f75148b1db995a5a23af0187f0bcd69fffb0e920b6a4c980917bfc6adf24a39b0d889b75cf071a7194163af137cf71d6628fb80e9
+  metadata.gz: eb87d5182932e143e3a98330d70b730dcc110849c9ce8d6bdf18509ca87eb9751407660b58b352464ae803e2a08aa1264279aec440226fbc026a8acc932d29f9
+  data.tar.gz: d8ff66b28ed0c6e4987ca56795abf20061af0ed50d08c9e7ff01fc45f0712f5762bacb94153868c0d2f0fe66a02977f30f76f5ddfb0b6cecd93085fce3118334

data/Changelog.adoc

@@ -3,11 +3,19 @@
 
 == Some of the things Not yet in place
 
- * Investigate how to remove tmp/cache files and dirs during graph generation
  * Update docs for giblish.
  ** write instructions for github webhook triggered generation
  * Update the default css for giblish html generation.
- * Implement a way for a user to customize the index page
+
+== v2.2.0
+
+ * enable customization of the index pages using erb templates
+
+== v2.1.2
+
+ * enable asciidoc-mathematical (if it is accessible on the system) when rendering pdfs
+ ** force the output format for equations to svg
+ ** remove stem-...svg files created by asciidoctor-mathematical
 
 == v2.1.0
 

data/README.adoc

@@ -9,6 +9,15 @@ image::https://github.com/rillbert/giblish/actions/workflows/unit_tests.yml/badg
 
 giblish converts a source directory tree containing AsciiDoc files to a destination directory tree containing the corresponding html or pdf files. It adds some handy tools for easier navigation of the resulting destination tree.
 
+.Two-liner conversion
+[source, bash]
+----
+# install giblish (requires a working ruby installation on the system)
+gem install giblish
+# convert all adoc files recursively under 'my/src' and place them (recursively) under "the/dest"
+$ giblish my/src the/dest
+----
+
 == Examples
 
 IMPORTANT: The examples below are *not* the official documentation for the corresponding projects.
@@ -35,13 +44,14 @@ IMPORTANT: The examples below are *not* the official documentation for the corre
 
 The features of giblish include:
 
- * An index page listing all rendered documents with clickable links.
- * If the source directory tree is part of a git repository, giblish can generate separate html/pdf trees for branches and/or tags that match a user specified regexp (see examples below).
- * Document ids - Note: the implementation of this is giblish-specific and thus you need to render your adoc files using giblish to make this work as intended. You can use document ids to:
+ * Simple conversion of whole document trees into both html and pdf.
+ * Customizable index pages that list all rendered documents with clickable links.
+ * Generate separate destination trees per branch in a git repo in one go (see examples below).
+ * Document ids - a (non-standard) way of referencing other documents in the same tree, you can use document ids to:
  ** Reference one doc in the source tree from another doc without depending on file names or relative paths. The referenced doc can thus be moved within the source tree or change its file name and the reference will still be valid.
  ** Validate doc id references during document rendering and thus be alerted to any invalid doc id references.
  ** Let giblish generate a clickable graph of all document references (requires graphviz and the 'dot' tool).
- * A stripped-down, but nonetheless useful, text-search of your html documents. This requires that you publish your docs to a web-server and setup an application on that same web-server. `giblish` provides most of the scaffolding though.
+ * Text-search - a stripped-down, but nonetheless useful, text-search of your html documents. This requires that you publish your docs to a web-server and setup an application on that same web-server. `giblish` provides most of the scaffolding though.
 
 == Dependencies and credits
 
@@ -63,24 +73,6 @@ When using giblish for generating docs the following applies:
  * giblish requires that the git working tree and index of the repo containing source documents are clean when generating documentation.
  * giblish will make explicit check-outs of all the branches or tags that matches the selection criteria. The working dir of the source git repo will thus have the last branch that giblish checked-out as the current branch after doc generation.
 
-== Contributing
-
-If you want to contribute to giblish, great :) Use the standard GitHub flow of forking the repo and submit a pull request.
-
-Pull requests must meet the following to be considered for merging:
-
- * Tests have been added for new or updated functionality
- * The code has been linted using the `standardrb` tool. 
- ** The version of standardrb shall be the same as the one used in the target branch for the PR. 
-
-To develop on giblish, you:
-
- . Install ruby on your local machine (rbenv is a good choice for handling ruby installations)
- . Install necessary dependencies to install the ruby 'mathematica' gem, see eg https://github.com/gjtorikian/mathematical/blob/47041d5492cc7c5f04105031430fb44119406f49/script/install_linux_deps
- . Install graphviz
- . Clone or fork the repository
- . Run the `bin/setup` script from a bash prompt
-
 == Document ids and the reference graph
 
 NOTE: This is a non-standard extension of asciidoc. If you use this feature, you will need to generate your documents using giblish to make this work as intended.
@@ -139,7 +131,7 @@ The above reference will work even if either document changes location or file n
 [[usage_examples]]
 == Usage Examples
 
-Here follows a number of usages for giblish in increasing order of complexity.
+A number of use cases for giblish in increasing order of complexity.
 
 === Get available options
 
@@ -163,6 +155,16 @@ The default asciidoctor css will be used in the html conversion.
 
 The default asciidoctor pdf theme will be used in the pdf conversion.
 
+=== Customize the index pages generated by giblish
+
+Add a file `idx_template.erb` under a directory of your choice, in this example `style_resources` is used. An example of the available customization options is https://github.com/rillbert/giblish/blob/personal/rillbert/data/resources/erb/idx_template.erb[this file] from the giblish test data set.
+
+Invoke `giblish` with the resource directory set using the `-r` flag.
+
+ giblish -r style_resource my_src_root my_dst_root
+
+Your erb template is used to generate the index page(es).
+
 === Using a custom css for the generated html
 
 Generate html that can be browsed locally from file:://<my_dst_root>.
@@ -192,6 +194,24 @@ Generate html that can be browsed locally from file:://<my_dst_root>.
  ** generate an index page named `index.html` that contains links and some info about the converted files. The file is placed in the `my_dst_root/<branch_name` dir.
  * generate a summary page containing links to a all branches and place it in the `my_dst_root` dir.
 
+== Contributing
+
+If you want to contribute to giblish, great :) Use the standard GitHub flow of forking the repo and submit a pull request.
+
+Pull requests must meet the following to be considered for merging:
+
+ * Tests have been added for new or updated functionality
+ * The code has been linted using the `standardrb` tool.
+ ** The version of standardrb shall be the same as the one used in the target branch for the PR.
+
+To develop on giblish, you:
+
+ . Install ruby on your local machine (rbenv is a good choice for handling ruby installations)
+ . Install necessary dependencies to install the ruby 'mathematica' gem, see eg https://github.com/gjtorikian/mathematical/blob/47041d5492cc7c5f04105031430fb44119406f49/script/install_linux_deps
+ . Install graphviz
+ . Clone or fork the repository
+ . Run the `bin/setup` script from a bash prompt
+
 // === Publish the asciidoctor.org documents with text search
 
 // giblish can be used to generate html docs suitable for serving via a web server (e.g. Apache). You can use the cgi script included in the giblish gem to provide text search capabilities.

data/lib/giblish/cmdline.rb

@@ -276,10 +276,14 @@ module Giblish
         raise OptionParser::InvalidArgument, "The '-w' flag can only be used for the 'html' format flags"
       end
 
-      if opts.resource_dir.nil? ^ opts.style_name.nil?
-        raise OptionParser::InvalidArgument, "Either both '-s' and '-r' flags must be given or none of them."
+      if opts.style_name && opts.resource_dir.nil?
+        raise OptionParser::InvalidArgument, "The '-s' flag requires the use of the '-r' flag as well."
       end
 
+      # if opts.resource_dir.nil? ^ opts.style_name.nil?
+      #   raise OptionParser::InvalidArgument, "Either both '-s' and '-r' flags must be given or none of them."
+      # end
+
       if opts.resource_dir && !opts.resource_dir.exist?
         raise OptionParser::InvalidArgument, "Could not find resource path #{opts.resource_dir}"
       end

data/lib/giblish/config_utils.rb

@@ -26,6 +26,9 @@ module Giblish
 
     def method_missing(m, *args, &block)
       del = @delegates&.find { |d| d.respond_to?(m) }
+      if del.nil?
+        Giblog.logger.warn { "Did not find method '#{m}' in any delegate (#{@delegates}"}
+      end
 
       del.nil? ? super : del.send(m, *args, &block)
     end

data/lib/giblish/configurator.rb

@@ -13,26 +13,24 @@ module Giblish
   class HtmlLayoutConfig
     attr_reader :pre_builders, :post_builders, :adoc_extensions, :adoc_api_opts, :docattr_providers
 
-    def initialize(config_opts)
+    def initialize(resource_paths, config_opts)
       @adoc_api_opts = {backend: "html"}
       @pre_builders = []
       @post_builders = []
       @adoc_extensions = {}
       @docattr_providers = []
-      case config_opts
-        in resource_dir:
-          # copy local resources to dst and link the generated html with
-          # the given css
-          @pre_builders << CopyResourcesPreBuild.new(config_opts)
-
-          # make sure generated html has relative link to the copied css
-          @docattr_providers << RelativeCssDocAttr.new(ResourcePaths.new(config_opts).dst_style_path_rel)
-        in server_css:
-          # do not copy any local resources, use the given web path to link to css
-          @docattr_providers << AbsoluteLinkedCss.new(config_opts.server_css)
-        else
-          4 == 5 # workaround for bug in standardrb formatting
-        end
+
+      if resource_paths.src_resource_dir_abs && resource_paths.dst_style_path_rel
+        # copy local resources to dst and link the generated html with
+        # the given css
+        @pre_builders << CopyResourcesPreBuild.new(resource_paths)
+
+        # make sure generated html has relative link to the copied css
+        @docattr_providers << RelativeCssDocAttr.new(resource_paths.dst_style_path_rel)
+      elsif config_opts.server_css
+        # do not copy any local resources, use the given web path to link to css
+        @docattr_providers << AbsoluteLinkedCss.new(config_opts.server_css)
+      end
 
       if config_opts.make_searchable
         # enabling text search
@@ -49,7 +47,7 @@ module Giblish
   # A combined docattr_provider and post-processor that:
   # - instructs asciidoctor-mathematical to use svg as format
   # - removes svg cache files produced by asciidoctor-mathematical
-  class PdfMathHelper
+  class PdfMathPostbuilder
     # called by the TreeConverter during the post_build phase
     def on_postbuild(src_topdir, dst_tree, converter)
       dst_top = src_topdir.pathname
@@ -71,7 +69,7 @@ module Giblish
   class PdfLayoutConfig
     attr_reader :pre_builders, :post_builders, :adoc_extensions, :adoc_api_opts, :docattr_providers
 
-    def initialize(config_opts)
+    def initialize(resource_paths)
       @adoc_api_opts = {backend: "pdf"}
       @pre_builders = []
       @post_builders = []
@@ -80,17 +78,19 @@ module Giblish
 
       begin
         require "asciidoctor-mathematical"
-        cc = PdfMathHelper.new
+        cc = PdfMathPostbuilder.new
         @post_builders << cc
         @docattr_providers << cc
       rescue LoadError
         Giblog.logger.warn { "Did not find asciidoctor-mathematical. stem blocks will not be rendered correctly!" }
       end
 
-      unless config_opts.resource_dir.nil?
+      if resource_paths.src_style_path_abs
         # generate pdf using asciidoctor-pdf with custom styling
-        rp = ResourcePaths.new(config_opts)
-        @docattr_providers << PdfCustomStyle.new(rp.src_style_path_abs, *rp.font_dirs_abs.to_a)
+        @docattr_providers << PdfCustomStyle.new(
+          resource_paths.src_style_path_abs,
+          *resource_paths.font_dirs_abs.to_a
+        )
       end
     end
   end
@@ -103,6 +103,8 @@ module Giblish
     # config_opts:: a Cmdline::Options instance with config info
     def initialize(config_opts)
       @config_opts = config_opts
+      @resource_paths = ResourcePaths.new(config_opts)
+
       @build_options = {
         pre_builders: [],
         post_builders: [],
@@ -117,8 +119,8 @@ module Giblish
       )
 
       layout_config = case config_opts
-      in format: "html" then HtmlLayoutConfig.new(config_opts)
-      in format: "pdf" then PdfLayoutConfig.new(config_opts)
+      in format: "html" then HtmlLayoutConfig.new(@resource_paths, config_opts)
+      in format: "pdf" then PdfLayoutConfig.new(@resource_paths)
       else
         raise OptionParser::InvalidArgument, "The given cmd line flags are not supported: #{config_opts.inspect}"
       end
@@ -131,7 +133,7 @@ module Giblish
       )
 
       setup_docid(config_opts, @build_options, @doc_attr)
-      setup_index_generation(config_opts, @build_options, @doc_attr)
+      setup_index_generation(config_opts, @resource_paths, @build_options, @doc_attr)
 
       # setup all pre,post, and build options
       @build_options[:adoc_api_opts] = layout_config.adoc_api_opts
@@ -147,11 +149,14 @@ module Giblish
 
     protected
 
-    def setup_index_generation(config_opts, build_options, doc_attr)
+    def setup_index_generation(config_opts, resource_paths, build_options, doc_attr)
       return if config_opts.no_index
 
       # setup index generation
-      idx = SubtreeInfoBuilder.new(doc_attr, nil, SubtreeIndexBase, config_opts.index_basename)
+      adoc_src_provider = SubtreeIndexBase.new(
+        {erb_template_path: resource_paths.idx_erb_template_abs}
+      )
+      idx = SubtreeInfoBuilder.new(doc_attr, nil, adoc_src_provider, config_opts.index_basename)
       build_options[:post_builders] << idx
     end
 
@@ -184,11 +189,16 @@ module Giblish
 
     protected
 
-    def setup_index_generation(config_opts, build_options, doc_attr)
+    def setup_index_generation(config_opts, resource_paths, build_options, doc_attr)
       return if config_opts.no_index
 
       build_options[:post_builders] << AddHistoryPostBuilder.new(@git_repo_dir)
-      build_options[:post_builders] << SubtreeInfoBuilder.new(doc_attr, nil, SubtreeIndexGit, config_opts.index_basename)
+
+      # setup index generation
+      adoc_src_provider = SubtreeIndexGit.new(
+        {erb_template_path: resource_paths.idx_erb_template_abs}
+      )
+      build_options[:post_builders] << SubtreeInfoBuilder.new(doc_attr, nil, adoc_src_provider, config_opts.index_basename)
     end
   end
 end

data/lib/giblish/gitrepos/history_pb.rb

@@ -19,7 +19,6 @@ module Giblish
           dst_node.data.add(FileHistory.new(current_branch))
           next
         end
-        # next unless dst_node.leaf?
 
         src_node = dst_node.data.src_node
         next unless src_node.pathname.exist?

data/lib/giblish/indexbuilders/{standard_index.erb → idx_template.erb}

@@ -1,4 +1,4 @@
-= Documents under '<%= @title %>'
+= Documents under '<%= @dirname %>'
 Generated at: <%= Time.now.strftime("%Y-%m-%d %H:%M") %>
 :icons: font
 

data/lib/giblish/indexbuilders/subtree_indices.rb

@@ -1,22 +1,30 @@
 require "erb"
 require_relative "verbatimtree"
 require_relative "d3treegraph"
+require_relative "../resourcepaths"
 
 module Giblish
   class SubtreeIndexBase < SubtreeSrcItf
     attr_reader :src_location
 
-    DEFAULT_INDEX_ERB = "/standard_index.erb"
+    # Required options:
+    #   :erb_template_path - the absolute path to the erb template that will be used when generating
+    #                        the indices.
+    def initialize(opts)
+      raise InvalidArgument unless opts.key?(:erb_template_path)
 
-    def initialize(pathtree, output_basename)
+      @erb_path = Pathname(opts[:erb_template_path])
+    end
+
+    def adoc_source(pathtree, output_basename)
       @pathtree = pathtree
       @output_basename = output_basename
-      @src_location = pathtree.pathname.dirname
-      @title = pathtree.segment
-    end
+      @parent_dirpath = pathtree.pathname.dirname
+      @dirname = pathtree.segment
+
+      Giblog.logger.debug { "using erb template: #{@erb_path} for index generation" }
+      erb_template = File.read(@erb_path)
 
-    def adoc_source
-      erb_template = File.read(__dir__ + DEFAULT_INDEX_ERB)
       ERB.new(erb_template, trim_mode: "<>").result(binding)
     end
 
@@ -91,17 +99,21 @@ module Giblish
     # The fixed heading of the table used to display file history
     HISTORY_TABLE_HEADING = <<~HISTORY_HEADER
       File history::
-  
+
       [cols=\"2,3,8,3\",options=\"header\"]
       |===
       |Date |Author |Message |Sha1
     HISTORY_HEADER
 
     HISTORY_TABLE_FOOTING = <<~HIST_FOOTER
-      
+
       |===\n\n
     HIST_FOOTER
 
+    def initialize(erb_template_path)
+      super(erb_template_path)
+    end
+
     def subtitle(dst_node)
       "from #{dst_node.data.branch}"
     end
@@ -122,8 +134,8 @@ module Giblish
         <<~HISTORY_ROW
           |#{h.date.strftime("%Y-%m-%d")}
           |#{h.author}
-          |#{h.message}  
-          |#{h.sha1[0..7]} ... 
+          |#{h.message}
+          |#{h.sha1[0..7]} ...
         HISTORY_ROW
       end.join("\n\n")
       HISTORY_TABLE_HEADING + rows + HISTORY_TABLE_FOOTING

data/lib/giblish/resourcepaths.rb

@@ -3,7 +3,7 @@ require "pathname"
 module Giblish
   # Provides relevant paths for layout resources based on the given options
   class ResourcePaths
-    STYLE_EXTENSIONS = {
+    FORMAT_CONVENTIONS = {
       "html5" => ".css",
       "html" => ".css",
       "pdf" => ".yml",
@@ -11,7 +11,8 @@ module Giblish
     }
 
     FONT_REGEX = /.*\.(ttf)|(TTF)$/
-    RESOURCE_DST_TOP_BASENAME = Pathname.new("web_assets")
+    WEB_ASSET_TOP_BASENAME = Pathname.new("web_assets")
+    IDX_ERB_TEMPLATE_BASENAME = "idx_template.erb"
 
     # the relative path from the top of the resource area to the
     # style file
@@ -28,37 +29,91 @@ module Giblish
     attr_reader :dst_style_path_rel
 
     # the abs path to the top of the destination dir for resources
-    attr_reader :dst_resource_dir_abs
+    attr_reader :dst_webasset_dir_abs
 
+    # the abs path to the top of the source dir for resources
+    attr_reader :src_resource_dir_abs
+
+    # the relative path to the erb template for index generation
+    attr_reader :idx_erb_template_rel
+
+    # the absolute path to the erb template for index generation
+    attr_reader :idx_erb_template_abs
+
+    # attributes:
+    #   .format        required
+    #   .resource_dir  required
+    #   .dst_dir       required
+    #   .style_name    optional
+    #   .idx_erb_basename    optional
     def initialize(cmd_opts)
-      @style_ext = STYLE_EXTENSIONS.fetch(cmd_opts.format, nil)
-      raise OptionParser::InvalidArgument, "Unsupported format: #{cmd_opts.format}" if @style_ext.nil?
-
-      # Cache all file paths in the resource area
-      r_top = cmd_opts.resource_dir
-      file_tree = PathTree.build_from_fs(r_top)
-
-      # find and validate paths
-      @dst_resource_dir_abs = cmd_opts.dstdir / RESOURCE_DST_TOP_BASENAME
-      @src_style_path_rel = find_style_file(file_tree, cmd_opts)
-      @src_style_path_abs = r_top / @src_style_path_rel
-      @dst_style_path_rel = RESOURCE_DST_TOP_BASENAME / @src_style_path_rel
+      raise InvalidArgument, "Unsupported format: #{cmd_opts.format}" unless FORMAT_CONVENTIONS.key?(cmd_opts.format)
+
+      init_to_default(cmd_opts)
+
+      return if @src_resource_dir_abs.nil?
+
+      # Tweak paths based on the content of a given resource dir
+      file_tree = PathTree.build_from_fs(@src_resource_dir_abs)
+
+      @src_style_path_rel = find_style_file(file_tree, cmd_opts.format, cmd_opts.style_name)
+      @src_style_path_abs = @src_resource_dir_abs / @src_style_path_rel if @src_style_path_rel
+      @dst_style_path_rel = WEB_ASSET_TOP_BASENAME / @src_style_path_rel if @src_style_path_rel
+
       @font_dirs_abs = find_font_dirs(file_tree)
+
+      erb_template = find_unique_file(file_tree, IDX_ERB_TEMPLATE_BASENAME)
+      if erb_template
+        @idx_erb_template_rel = erb_template
+        @idx_erb_template_abs = @src_resource_dir_abs / @idx_erb_template_rel
+      end
     end
 
     private
 
+    # initialize paths to default values
+    def init_to_default(cmd_opts)
+      # the top dir for resources
+      @src_resource_dir_abs = cmd_opts.resource_dir
+
+      # the destination dir for webassets is always valid for html conversion
+      @dst_webasset_dir_abs = cmd_opts.dstdir / WEB_ASSET_TOP_BASENAME if cmd_opts.format.start_with?("html")
+
+      # use the hard-coded default erb template
+      @idx_erb_template_rel = Pathname("indexbuilders/#{IDX_ERB_TEMPLATE_BASENAME}")
+      @idx_erb_template_abs = Pathname(__dir__) / @idx_erb_template_rel
+
+      @src_style_path_rel = nil
+      @src_style_path_abs = nil
+
+      @font_dirs_abs = nil
+    end
+
     # returns:: the relative path from the top of the file_tree to
     # the style file
-    def find_style_file(file_tree, cmd_opts)
+    def find_style_file(file_tree, format, style_name)
+      return nil if style_name.nil?
+
       # Get all files matching the style name
-      style_basename = Pathname.new(cmd_opts.style_name).sub_ext(@style_ext)
-      style_tree = file_tree.match(/.*#{style_basename}$/)
+      style_basename = Pathname.new(style_name).sub_ext(
+        FORMAT_CONVENTIONS[format]
+      )
+      find_unique_file(file_tree, style_basename)
+    end
 
-      # make sure we have exactly one css file with the given name
-      raise OptionParser::InvalidArgument, "Did not find #{style_basename} under #{file_tree.pathname}" if style_tree.nil?
+    # returns the (relative) pathname of the file with the given basename or
+    # nil if no match was found.
+    #
+    # Throws if multiple entries exists.
+    def find_unique_file(file_tree, basename)
+      files = file_tree.match(/.*#{basename}$/)
 
-      l = style_tree.leave_pathnames(prune: true)
+      if files.nil?
+        Giblog.logger.warn { "Did not find #{basename} under #{file_tree.pathname}" }
+        return nil
+      end
+
+      l = files.leave_pathnames(prune: true)
       if l.count > 1
         raise OptionParser::InvalidArgument, "Found #{l.count} instances of #{style_basename} under #{file_tree.pathname}. Requires exactly one."
       end
@@ -67,6 +122,8 @@ module Giblish
       l[0]
     end
 
+    # returns:: a Set(Pathname) with all (absolute) directories matching the name criteria
+    # for fonts
     def find_font_dirs(file_tree)
       tree = file_tree.match(FONT_REGEX)
       dirs = Set.new
@@ -87,23 +144,22 @@ module Giblish
     # style_name:: basename of the css to use for styling
     # dstdir:: Pathname to the destination dir where the copied resources will be
     # stored.
-    def initialize(cmd_opts)
-      @opts = cmd_opts.dup
-      @paths = ResourcePaths.new(cmd_opts)
+    def initialize(resource_paths)
+      @paths = resource_paths
     end
 
     def on_prebuild(src_tree, dst_tree, converter)
-      copy_resource_area(@opts)
+      copy_resource_area
     end
 
     private
 
     # copy everyting under cmd_opts.resource_dir to @web_asset_dir
-    def copy_resource_area(cmd_opts)
-      web_assets_dir = @paths.dst_resource_dir_abs
+    def copy_resource_area
+      web_assets_dir = @paths.dst_webasset_dir_abs
       web_assets_dir.mkpath unless web_assets_dir.exist?
 
-      resource_dir = cmd_opts.resource_dir.cleanpath.to_s + "/."
+      resource_dir = @paths.src_resource_dir_abs.to_s + "/."
 
       Giblog.logger&.info "Copy web assets (stylesheets et al) from #{resource_dir} to #{web_assets_dir}"
       FileUtils.cp_r(
@@ -113,6 +169,8 @@ module Giblish
     end
   end
 
+  # copy all directories whose name matches a given regex from
+  # the source tree to the destination tree.
   class CopyAssetDirsPostBuild
     def initialize(cmd_opts)
       @asset_regex = cmd_opts.copy_asset_folders

data/lib/giblish/subtreeinfobuilder.rb

@@ -3,12 +3,21 @@ require_relative "pathtree"
 
 module Giblish
   class SubtreeSrcItf
-    attr_reader :adoc_source
-    def initialize(dst_node, output_basename)
+    def initialize(opts = {})
+      raise NotImplementedError
+    end
+
+    def adoc_source(dst_node, output_basename)
       raise NotImplementedError
     end
   end
 
+  # A post builder that provides the ability for a adoc source provider to
+  # run on each directory node in the destination pathtree output from the build step.
+  #
+  # The adoc source provider is invoked on each directory node depth-first. The
+  # resulting adoc source is converted and the result added to the destination
+  # pathtree from the build step.
   class SubtreeInfoBuilder
     attr_accessor :docattr_provider
 
@@ -21,7 +30,15 @@ module Giblish
     def initialize(docattr_provider = nil, api_opt_provider = nil, adoc_src_provider = nil, basename = DEFAULT_BASENAME)
       @docattr_provider = docattr_provider
       @api_opt_provider = api_opt_provider
+
       @adoc_src_provider = adoc_src_provider || SubtreeIndexBase
+      if @adoc_src_provider.is_a?(Class)
+        @adoc_src_provider = @adoc_src_provider.new(
+          {docattr_provider: docattr_provider,
+           api_opt_provider: api_opt_provider}
+        )
+      end
+
       @basename = basename
       @adoc_source = nil
     end
@@ -52,12 +69,7 @@ module Giblish
         index_dir = dst_node.pathname.relative_path_from(dst_tree.pathname).cleanpath
         Giblog.logger.debug { "Creating #{@basename} under #{index_dir}" }
 
-        # get the adoc source from the provider (Class or instance)
-        @adoc_source = if @adoc_src_provider.is_a?(Class)
-          @adoc_src_provider.new(dst_node, @basename).adoc_source
-        else
-          @adoc_src_provider.adoc_source
-        end
+        @adoc_source = @adoc_src_provider.adoc_source(dst_node, @basename)
 
         # add a virtual 'index.adoc' node as the only node in a source tree
         # with this object as source for conversion options

data/lib/giblish/version.rb

@@ -1,3 +1,3 @@
 module Giblish
-  VERSION = "2.1.2".freeze
+  VERSION = "2.2.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: giblish
 version: !ruby/object:Gem::Version
-  version: 2.1.2
+  version: 2.2.0
 platform: ruby
 authors:
 - Anders Rillbert
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-04 00:00:00.000000000 Z
+date: 2023-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -322,7 +322,7 @@ files:
 - lib/giblish/indexbuilders/d3treegraph.rb
 - lib/giblish/indexbuilders/depgraphbuilder.rb
 - lib/giblish/indexbuilders/dotdigraphadoc.rb
-- lib/giblish/indexbuilders/standard_index.erb
+- lib/giblish/indexbuilders/idx_template.erb
 - lib/giblish/indexbuilders/subtree_indices.rb
 - lib/giblish/indexbuilders/templates/circles.html.erb
 - lib/giblish/indexbuilders/templates/flame.html.erb