giblish 0.6.1 → 0.7.0

data/lib/giblish/buildgraph.rb

@@ -14,7 +14,7 @@ module Giblish
 
     # Supported options:
     # :extension - file extension for URL links (default is .html)
-    def initialize(processed_docs, paths, options = {})
+    def initialize(processed_docs, paths, deployment_info, 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
@@ -26,12 +26,17 @@ module Giblish
       @next_id = 0
       @processed_docs = processed_docs
       @paths = paths
+      @deployment_info = deployment_info
       @converter_options = options.dup
       # @options = options.dup
       @extension = @converter_options.key?(:extension) ? options[:extension] : "html"
       @docid_cache = DocidCollector.docid_cache
       @docid_deps =  DocidCollector.docid_deps
       @dep_graph = build_dep_graph
+      @search_opts = {
+          web_assets_top: @deployment_info.web_path,
+          search_assets_top: @deployment_info.search_assets_path,
+      }
     end
 
     # get the asciidoc source for the document.
@@ -46,6 +51,15 @@ module Giblish
       DOC_STR
     end
 
+    def cleanup
+      # remove cache dir and svg image created by asciidoctor-diagram
+      # when creating the document dependency graph
+      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
+
     private
 
     # build a hash with {DocInfo => [doc_id array]}
@@ -101,11 +115,10 @@ module Giblish
     end
 
     def add_search_box
-      # TODO: Fix the hard-coded path
       Giblish::generate_search_box_html(
           @converter_options[:attributes]["stylesheet"],
           "/cgi-bin/giblish-search.cgi",
-          @paths
+          @search_opts
       )
     end
 
@@ -194,4 +207,12 @@ module Giblish
       "_generated_id_#{@next_id.to_s.rjust(4, '0')}"
     end
   end
+
+  class GitGraphBuilderGraphviz < GraphBuilderGraphviz
+    def initialize(processed_docs, paths, deployment_info, options = {}, git_repo)
+      super(processed_docs, paths, deployment_info, options)
+    end
+  end
 end
+
+

data/lib/giblish/buildindex.rb

@@ -10,13 +10,18 @@ module Giblish
   # Base class with common functionality for all index builders
   class BasicIndexBuilder
     # set up the basic index building info
-    def initialize(processed_docs, converter, path_manager, handle_docid = false)
+    def initialize(processed_docs, converter, path_manager, deployment_info, handle_docid = false)
       @paths = path_manager
+      @deployment_info = deployment_info
       @nof_missing_titles = 0
       @processed_docs = processed_docs
       @converter = converter
       @src_str = ""
       @manage_docid = handle_docid
+      @search_opts = {
+          web_assets_top: @deployment_info.web_path,
+          search_assets_top: @deployment_info.search_assets_path,
+      }
     end
 
     def source(dep_graph_exists = false, make_searchable = false)
@@ -57,11 +62,10 @@ module Giblish
     end
 
     def add_search_box
-      # TODO: Fix the hard-coded path
       Giblish::generate_search_box_html(
           @converter.converter_options[:attributes]["stylesheet"],
           "/cgi-bin/giblish-search.cgi",
-          @paths
+          @search_opts
       )
     end
 
@@ -295,16 +299,16 @@ module Giblish
 
   # A simple index generator that shows a table with the generated documents
   class SimpleIndexBuilder < BasicIndexBuilder
-    def initialize(processed_docs, converter, path_manager, manage_docid = false)
-      super processed_docs, converter, path_manager, manage_docid
+    def initialize(processed_docs, converter, path_manager, deployment_info, manage_docid = false)
+      super processed_docs, converter, path_manager, deployment_info, manage_docid
     end
   end
 
   # Builds an index of the generated documents and includes some git metadata
   # from the repository
   class GitRepoIndexBuilder < BasicIndexBuilder
-    def initialize(processed_docs, converter, path_manager, manage_docid, git_repo_root)
-      super processed_docs, converter, path_manager, manage_docid
+    def initialize(processed_docs, converter, path_manager, deployment_info, manage_docid, git_repo_root)
+      super processed_docs, converter, path_manager, deployment_info, manage_docid
 
       # no repo root given...
       return unless git_repo_root

data/lib/giblish/cmdline.rb

@@ -20,6 +20,7 @@ class CmdLineParser
                              *html* is used if -f is not supplied
   -n --no-build-ref          suppress generation of a reference document at the destination
                              tree root.
+  --index-basename           set the name of the generated index file (default 'index').  
   -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
@@ -29,24 +30,28 @@ class CmdLineParser
   -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.
-  -i --include <regexp>      include only files with a filename that matches the supplied
+                             the name of an yml file. You can specify only the 
+                             basename of the file and giblish will use the suffix
+                             associated with the output format (i.e specify 'mystyle'
+                             and the mystyle.css and mystyle.yml will be used for html
+                             and pdf generation respectively)
+  -i --include <regexp>      include only files with a path that matches the supplied
                              regexp (defaults to '.*\.(?i)adoc$' meaning it matches all
                              files ending in .adoc case-insensitive). The matching is made
-                             on the _file name only_, not the full path (i.e. for the full
-                             path /my/file.adoc, only file.adoc is used in the matching).
-  -j --exclude <regexp>      exclude files with filenames matching the supplied
+                             on the full path (i.e. the regex '^.*my.*' matches the path 
+                             /my/file.adoc).
+  -j --exclude <regexp>      exclude files with a path that matches the supplied
                              regexp (no files are excluded by default). The matching is made
-                             on the _file name only_, not the full path (i.e. for the full
-                             path /my/file.adoc, only file.adoc is used in the matching).
-  -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.
+                             on the full path (i.e. the regex '^.*my.*' matches the path 
+                             /my/file.adoc).
+  -w --web-path <path>       Specifies the URL path to where the generated html documents
+                             will be deployed (only needed when serving the html docs via
+                             a web server).
+                             E.g.
+                             If the docs are deployed to 'www.example.com/site_1/blah', 
+                             this flag shall be set to '/site_1/blah'. This switch is only
+                             used when generating html. giblish use this to link the deployed
+                             html docs with the correct stylesheet. 
   -g --git-branches <regExp> if the source_dir_top is located within a git repo,
                              generate docs for all _remote branches on origin_ that matches
                              the given regular expression. Each git branch will
@@ -96,6 +101,15 @@ class CmdLineParser
                              An implementation of the giblish-search cgi-script is found
                              within the lib folder of this gem, you can copy that to your
                              cgi-bin dir in your webserver and rename it from .rb to .cgi
+  -mp, --search-assets-deploy <path> the absolute path to the 'search_assets' folder where the search
+                             script can find the data needed for implementing the text search
+                             (default is <dst_dir_top>).
+                             Set this to the file system path where the generated html
+                             docs will be deployed (if different from dst_dir_top):
+                             E.g.
+                             If the generated html docs will be deployed to the folder 
+                             '/var/www/mysite/blah/mydocs,'
+                             this is what you shall set the path to. 
   --log-level                set the log level explicitly. Must be one of
                              debug, info (default), warn, error or fatal.
 ENDHELP
@@ -159,10 +173,12 @@ ENDHELP
         excludeRegexp: nil,
         flatten: false,
         suppressBuildRef: false,
+        indexBaseName: "index",
         localRepoOnly: false,
         resolveDocid: false,
-        make_searchable: false,
-        webRoot: false
+        makeSearchable: false,
+        searchAssetsDeploy: nil,
+        webPath: nil
     }
 
     # set default log level
@@ -180,6 +196,7 @@ ENDHELP
         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 "--index-basename"     then next_arg = :indexBaseName
         when "-i", "--include"      then next_arg = :includeRegexp
         when "-j", "--exclude"      then next_arg = :excludeRegexp
         when "-g", "--git-branches" then next_arg = :gitBranchRegexp
@@ -187,9 +204,10 @@ ENDHELP
         when "-c", "--local-only"   then @args[:localRepoOnly] = true
         when "-a", "--attribute"    then next_arg = :attributes
         when "-d", "--resolve-docid" then @args[:resolveDocid] = true
-        when "-m", "--make-searchable" then @args[:make_searchable] = true
+        when "-m", "--make-searchable" then @args[:makeSearchable] = true
+        when "-mp", "--search-assets-deploy" then next_arg = :searchAssetsDeploy
         when "-s", "--style"        then next_arg = :userStyle
-        when "-w", "--web-root"     then next_arg = :webRoot
+        when "-w", "--web-path"     then next_arg = :webPath
         when "--log-level"          then next_arg = :logLevel
         else
           if next_arg
@@ -224,9 +242,12 @@ ENDHELP
     if !@args[:resourceDir] && @args[:userStyle]
       puts "Error: The given style would not be used since no resource dir "\
            "was specified (-s specified without -r)"
-    elsif @args[:make_searchable] && @args[:format] != "html"
+    elsif @args[:makeSearchable] && @args[:format] != "html"
       puts "Error: The --make-searchable option is only supported for "\
-           "html rendering"
+           "html rendering."
+    elsif @args[:searchAssetsDeploy] && !@args[:makeSearchable]
+      puts "Error: The --search-assets-deploy (-mp) flag is only supported in "\
+           "combination with the --make-searchable (-m) flag."
     else
       return
     end

data/lib/giblish/core.rb

@@ -29,11 +29,23 @@ module Giblish
           @options[:srcDirRoot],
           @options[:dstDirRoot],
           @options[:resourceDir],
-          @options[:webRoot]
+          @options[:makeSearchable]
+      )
+
+      # set the path to the search data that will be sent to the cgi search script
+      deploy_search_path = if @options[:makeSearchable]
+                            @options[:searchAssetsDeploy].nil? ?
+                                @paths.search_assets_abs : Pathname.new(@options[:searchAssetsDeploy]).join("search_assets")
+                          else
+                            nil
+                          end
+
+      @deploy_info = Giblish::DeploymentPaths.new(
+          @options[:webPath],
+          deploy_search_path
       )
       @processed_docs = []
       @converter = converter_factory
-      @search_assets_path = @paths.dst_root_abs.realpath.join("search_assets")
     end
 
 
@@ -46,7 +58,7 @@ module Giblish
       manage_doc_ids if @options[:resolveDocid]
 
       # register add-on for handling searchability
-      manage_searchability if @options[:make_searchable]
+      manage_searchability(@options) if @options[:makeSearchable]
 
       # traverse the src file tree and convert all files deemed as
       # adoc files
@@ -57,14 +69,14 @@ module Giblish
           to_asciidoc(p) if adocfile? p
         rescue Exception => e
           str = "Error when converting file #{path.to_s}: #{e.message}\nBacktrace:\n"
-          e.backtrace.each {|l| str << "   #{l}\n"}
-          Giblog.logger.error {str}
+          e.backtrace.each { |l| str << "   #{l}\n" }
+          Giblog.logger.error { str }
           conv_error = true
         end
       end if @paths.src_root_abs.directory?
 
       # create necessary search assets if needed
-      create_search_assets if @options[:make_searchable]
+      create_search_assets if @options[:makeSearchable]
 
       # build index and other fancy stuff if not suppressed
       unless @options[:suppressBuildRef]
@@ -80,23 +92,24 @@ module Giblish
     protected
 
     def build_graph_page
-      if Giblish::GraphBuilderGraphviz.supported
-        # gb = Giblish::GraphBuilderGraphviz.new @processed_docs, @paths, {extension: @converter.converter_options[:fileext]}
-        gb = Giblish::GraphBuilderGraphviz.new @processed_docs, @paths, @converter.converter_options
+      begin
+        adoc_logger = Giblish::AsciidoctorLogger.new Logger::Severity::WARN
+        gb = graph_builder_factory
         errors = @converter.convert_str(
             gb.source(
-                @options[:make_searchable]
+                @options[:makeSearchable]
             ),
             @paths.dst_root_abs,
-            "graph"
+            "graph",
+            logger: adoc_logger
         )
-        remove_diagram_temps unless errors
+        gb.cleanup
         !errors
-      else
-        Giblog.logger.warn { "Lacking access to needed tools for generating a visual dependency graph." }
+      rescue Exception => e
+        Giblog.logger.warn { e.message }
         Giblog.logger.warn { "The dependency graph will not be generated !!" }
-        false
       end
+      false
     end
 
     def build_index_page(dep_graph_exist)
@@ -105,10 +118,10 @@ module Giblish
       ib = index_factory
       @converter.convert_str(
           ib.source(
-              dep_graph_exist,@options[:make_searchable]
+              dep_graph_exist, @options[:makeSearchable]
           ),
           @paths.dst_root_abs,
-          "index",
+          @options[:indexBaseName],
           logger: adoc_logger
       )
 
@@ -120,19 +133,24 @@ module Giblish
     # user options
     def index_factory
       raise "Internal logic error!" if @options[:suppressBuildRef]
-      SimpleIndexBuilder.new(@processed_docs, @converter, @paths,
+      SimpleIndexBuilder.new(@processed_docs, @converter, @paths, @deploy_info,
                              @options[:resolveDocid])
     end
 
+    def graph_builder_factory
+      Giblish::GraphBuilderGraphviz.new @processed_docs, @paths, @deploy_info,
+                                        @converter.converter_options
+    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]}"
+      when "html" then
+        HtmlConverter.new @paths, @deploy_info, @options
+      when "pdf" then
+        PdfConverter.new @paths, @deploy_info, @options
+      else
+        raise ArgumentError, "Unknown conversion format: #{@options[:format]}"
       end
     end
 
@@ -143,7 +161,7 @@ module Giblish
       Giblog.logger.debug do
         "Adding adoc: #{adoc} Asciidoctor stderr: #{adoc_stderr}"
       end
-      Giblog.logger.debug {"Doc attributes: #{adoc.attributes}"}
+      Giblog.logger.debug { "Doc attributes: #{adoc.attributes}" }
 
       info = DocInfo.new(adoc: adoc, dst_root_abs: @paths.dst_root_abs, adoc_stderr: adoc_stderr)
       @processed_docs << info
@@ -164,26 +182,12 @@ module Giblish
 
     private
 
-    def create_search_asset_dir
-      Dir.exist?(@search_assets_path) || FileUtils.mkdir_p(@search_assets_path.to_s)
-      @search_assets_path
-    end
-
-    # 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
-
     # convert a single adoc doc to whatever the user wants
     def to_asciidoc(filepath)
       adoc = nil
       begin
         adoc_logger = Giblish::AsciidoctorLogger.new Logger::Severity::WARN
-        adoc = @converter.convert(filepath,logger: adoc_logger)
+        adoc = @converter.convert(filepath, logger: adoc_logger)
 
         add_doc(adoc, adoc_logger.user_info_str.string)
       rescue Exception => e
@@ -194,25 +198,35 @@ module Giblish
 
     # predicate that decides if a path is a asciidoc file or not
     def adocfile?(path)
-      fs = path.basename.to_s
-
+      fs = path.to_s
       unless @options[:excludeRegexp].nil?
         # exclude file if user wishes
         er = Regexp.new @options[:excludeRegexp]
         return false unless er.match(fs).nil?
       end
 
-      # only include files
+      # only include files matching the include regexp
       ir = Regexp.new @options[:includeRegexp]
       return !ir.match(fs).nil?
     end
 
-    def manage_searchability
+    def manage_searchability(opts)
       # register the extension
       Giblish.register_index_heading_extension
 
       # make sure we start from a clean slate
       IndexHeadings.clear_index
+
+      # propagate user-given id attributes to the indexing class
+      attr = opts[:attributes]
+      if !attr.nil?
+        if attr.has_key?("idprefix")
+          IndexHeadings.id_elements[:id_prefix] = attr["idprefix"]
+        end
+        if attr.has_key?("idseparator")
+          IndexHeadings.id_elements[:id_separator] = attr["idseparator"]
+        end
+      end
     end
 
     # top_dir
@@ -235,7 +249,7 @@ module Giblish
     # | ...
     def create_search_assets
       # get the proper dir for the search assets
-      assets_dir = create_search_asset_dir
+      assets_dir = @paths.search_assets_abs
 
       # store the JSON file
       IndexHeadings.serialize assets_dir, @paths.src_root_abs
@@ -280,6 +294,7 @@ module Giblish
       # cache the top of the tree since we need to redefine the
       # paths per branch/tag later on.
       @master_paths = @paths.dup
+      @master_deployment_info = @deploy_info.dup
       @git_repo_root = options[:gitRepoRoot]
       @git_repo = init_git_repo @git_repo_root, options[:localRepoOnly]
       @user_branches = select_user_branches(options[:gitBranchRegexp])
@@ -316,10 +331,15 @@ module Giblish
     protected
 
     def index_factory
-      GitRepoIndexBuilder.new(@processed_docs, @converter, @paths,
+      GitRepoIndexBuilder.new(@processed_docs, @converter, @paths, @deploy_info,
                               @options[:resolveDocid], @options[:gitRepoRoot])
     end
 
+    def graph_builder_factory
+      Giblish::GitGraphBuilderGraphviz.new @processed_docs, @paths, @deploy_info,
+                                           @converter.converter_options, @git_repo
+    end
+
     def add_doc(adoc, adoc_stderr)
       info = super(adoc, adoc_stderr)
 
@@ -370,7 +390,7 @@ module Giblish
         # match branches but remove eventual HEAD -> ... entry
         regexp.match b.name unless b.name =~ /^HEAD/
       end
-      Giblog.logger.debug {"selected git branches: #{user_checkouts}"}
+      Giblog.logger.debug { "selected git branches: #{user_checkouts}" }
       user_checkouts
     end
 
@@ -391,12 +411,12 @@ module Giblish
       # determine if we are called with a tag or a branch
       is_tag = (co.respond_to?(:tag?) && co.tag?)
 
-      Giblog.logger.info {"Checking out #{co.name}"}
+      Giblog.logger.info { "Checking out #{co.name}" }
       @git_repo.checkout co.name
 
       unless is_tag
         # if this is a branch, make sure it is up-to-date
-        Giblog.logger.info {"Merging with origin/#{co.name}"}
+        Giblog.logger.info { "Merging with origin/#{co.name}" }
         @git_repo.merge "origin/#{co.name}"
       end
 
@@ -406,10 +426,15 @@ module Giblish
       # 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)
-      @search_assets_path = @master_paths.dst_root_abs.realpath.join("search_assets").join(dir_name)
+
+      if @options[:makeSearchable] && !@master_deployment_info.search_assets_path.nil?
+        @paths.search_assets_abs = @master_paths.search_assets_abs.join(dir_name)
+        @deploy_info.search_assets_path = @master_deployment_info.search_assets_path.join(dir_name)
+        Giblog.logger.info { "will store search data in #{@paths.search_assets_abs}" }
+      end
 
       # Parse and convert docs using given args
-      Giblog.logger.info {"Convert docs into dir #{@paths.dst_root_abs}"}
+      Giblog.logger.info { "Convert docs into dir #{@paths.dst_root_abs}" }
       # parent_convert
       FileTreeConverter.instance_method(:convert).bind(self).call
     end