giblish 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d917c8b6c513f7759aecbbdb5a93a7cb13cb5774d66ccf0d602a615248723f76
-  data.tar.gz: b94be771b19dd5890e238ffc0ee0ee5af361919c0e526d63ac4f380b4f6698a0
+  metadata.gz: 70c09507979ec9eacf59cfcb8405c929b35b7c24882db0099d4493c18439b754
+  data.tar.gz: e707817cee1413bbc9fd28a04ac54a1f5147176ef01070e189096a387620a0e9
 SHA512:
-  metadata.gz: 4c9f6b75a6266c65baf0e7876016139703b7b46677fea2dcee54b9ad95b23c04756c8b9383398cdd8055c91e78ea3d275c7968eeabf1154478a44b76faf6c27c
-  data.tar.gz: c7cb03e7fe95cdf3a13a74c36f0d5efbb06e49828ff04db05b5d231f098bb411ab34584067e03b7a3b93c025224d3d93ccd13366e951fe93826cfdafeaae1bd9
+  metadata.gz: 54fbe435b49ec492065b3ba9f9c6bab31d08e56f5843937b36a4bd8c0bd4253ec6bacecc5f2cc530a1ebb188e8289c498fd68d8a7a6951b7b3831d2e7956bffe
+  data.tar.gz: 83eb9c41b4437f29e4e779ca7782bc464d42daffd97e0d36ef8482f7155c2ce9364097b97745d700773368c419354d086d2b767e08d1758f9c7ddb11dfdb6aca

data/README.adoc

@@ -174,3 +174,82 @@ cgi-script must be located at http://your_web_site.com/cgi-bin/giblish-search.cg
 and this gem provides a default implementation that you can copy from the .../lib
 folder to the correct destination.
 ====
+
+== Text search implementation
+
+The text search enables a user to search for a text string and receive matching
+sections in the documentation tree.
+
+To make this work, three things are needed
+
+ . the source text of all adoc files together with a JSON file that maps sections to
+   their line numbers. This 'search data' is collected by giblish when it generates the
+   html files to the destination directory. The JSON file and all adoc source files
+   are copied to a well-known place in the destination tree (see below).
+ . an html form somewhere in the rendered pages that receives the user input (text string
+   and other parameters) to start a search.
+ ** giblish injects such an html form in the generated index page when the user
+    specifies the '-m' switch.
+ . a server side script that
+ ** receive a text string to search for
+ ** parses the search data for matches to the text string
+ ** presents the result to the user
+
+This gem contains an example implementation of a server side script. It is implemented
+in ruby and uses 'grep' to parse the search data. It then generates a result page where
+each matching section is shown and when clicked, will navigate the user to that section
+in the corresponding document.
+
+=== Search data and html form parameters
+
+giblish will copy all search data to a 'search_assets' dir just under the destination
+root. This is illustrated below.
+
+.When rendering documents from a git branch
+ dst_root_dir
+ |- branch_1_top_dir
+ |     |- index.html
+ |     |- file_1.html
+ |     |- dir_1
+ |     |   |- file2.html
+ |- branch_2_top_dir
+ |- branch_x_...
+ |- web_assets
+ |- search_assets
+ |     |- branch_1_top_dir
+ |           |- heading_index.json
+ |           |- file1.adoc
+ |           |- dir_1
+ |           |   |- file2.adoc
+ |           |- ...
+ |     |- branch_2_top_dir
+ |           | ...
+
+assume that the file tree looks like this when not
+rendering a git branch:
+
+.When rendering documents not in a git branch
+ dst_root_dir
+ |- index.html
+ |- file_1.html
+ |- dir_1
+ |   |- file2.html
+ |...
+ |- web_assets (only if a custom stylesheet is used...)
+ |- search_assets
+ |     |- heading_index.json
+ |     |- file1.adoc
+ |     |- dir_1
+ |     |   |- file2.adoc
+ |     |- ...
+
+The parameters that is sent to the cgi script via the html form generated
+by giblish are:
+
+  * searchphrase -> the text string to search for
+  * ignorecase -> wether to ignore case or not
+  * useregexp -> wether the searchphrase above is treated as a regexp or
+    ordinary text
+  * css -> the css file name to use when styling the search result page
+  * topdir -> the absolute path to the root of the generated document tree
+  * reltop -> <clarify this>

data/Rakefile

@@ -13,6 +13,24 @@ Rake::TestTask.new(:current) do |t|
   t.test_files = FileList["test/**/index_heading_test.rb"]
 end
 
+Rake::TestTask.new(:paths) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/pathmanager_test.rb"]
+end
+
+Rake::TestTask.new(:graph) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/depgraph_test.rb"]
+end
+
+Rake::TestTask.new(:css) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/linkcss_test.rb"]
+end
+
 Rake::TestTask.new(:sandbox) do |t|
   t.libs << "test"
   t.libs << "lib"

data/docgen/scripts/Jenkinsfile

@@ -0,0 +1,18 @@
+pipeline {
+    agent any
+    stages {
+        stage('Render html documentation') {
+            steps {
+                echo "workspace path: ${env.WORKSPACE}"
+                // render html versions of all docs found under the 'docs' subdir
+                // in the repo
+                sh "giblish -n -f html -w ${env.WORKSPACE} -s giblish -r docgen/resources docs gendocs"
+            }
+        }
+//        stage('Render pdf documentation') {
+//            steps {
+//                sh "giblish -n -f pdf -s vironova-theme -r scripts/adocgen/resources Documents/MiniTEM/third_party_software/ MiniTEM/Deployment/doc"
+//            }
+//        }
+    }
+}

data/docgen/scripts/githook_examples/post-update.example

@@ -0,0 +1,24 @@
+#!/bin/sh
+#
+# This hook script kicks-in after git has completed
+# a push, it will thus never be able to abort a push.
+#
+# This hook will:
+# - ping Jenkins to trigger any builds related to the
+#   git push
+
+# let the user perfoming a git push know that we actually do something
+echo "Start post-update"
+
+# Hit Jenkins to initiate a Jenkins poll for which jobs that shall be started as
+# consequence of a push to a specific git repo. The generic format for this is:
+# curl <jenkins_url>/git/notifyCommit?url=<git repo url>
+#
+# If jenkins is accessible on http://jenkins.example.com:8080 and
+# you want to initiate a poll for jobs associated with the giblish repository on
+# github located at https://github.com/rillbert/giblish.git
+# you would use the following:
+curl http://jenkins.example.com:8080/git/notifyCommit?url=https://github.com/rillbert/giblish.git
+
+# Tell user we're done
+echo "Finished post-update"

data/docs/setup_server.adoc

@@ -0,0 +1,67 @@
+= Setup web site powered by giblish
+:imagesdir: setup_server_assets
+:numbered:
+
+== Purpose
+
+To describe how to setup a web site with documents automatically generated from a git repo.
+
+== Toolchain
+
+ * git
+ * giblish
+ * git server side hooks to kick-off the document rendering after a git push.
+ * a tool that can execute scripts after a git push. *Jenkins* is used in this instruction. Some advantages over calling giblish directly from a git hook:
+ ** the document rendering is asynchronous to the git push from the client.
+ ** the script executed by Jenkins (the 'pipeline' in Jenkis lingo) can be stored and versioned in the same git repo as the documents to be rendered.
+ * a web server to publish the rendered html documents.
+
+=== Sequence for rendering documents
+
+The following image shows how the sequence from user commit to rendered documents.
+
+image::Render Documents.png[]
+
+=== Sequence for viewing documents
+
+This is just the standard way of accessing a web site. The html page served by the web server will be the latest generated html page.
+
+image::View Documents.png[]
+
+== Server requirements
+
+The server that will render the documents need the following tools installed:
+
+ * git
+ * giblish
+
+The server that runs Jenkins will (of course) need Jenkins installed.
+
+=== Setup server for both Jenkins and doc rendering on Ubuntu 16.04
+
+The easiest setup is to use the same server to run Jenkins and to render the documents. For an Ubuntu 16.04 installation, you can install the needed tools as follows:
+
+ * install git `sudo apt install git`
+ * install Jenkins See https://www.digitalocean.com/community/tutorials/how-to-install-jenkins-on-ubuntu-16-04[this doc].
+ * install giblish `sudo gem install giblish`
+
+
+== server side git hooks
+
+git supports hooks in several parts of the sequence of getting changes ommitted and pushed to a remote repo. For details on git hooks see https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[this doc]. See <<post-update-hook>> An example of a `post-update` hook that triggers Jenkins
+
+
+[appendix]
+[[post-update-hook]]
+== post-update hook
+
+Below is an example of a `post-update` hook that triggers Jenkins jobs after a push to a git repo. This hook should be installed on the server side git repository to trigger Jenkins builds
+
+.Example of a git hook triggering Jenkins builds
+----
+include::../docgen/scripts/githook_examples/post-update.example[]
+----
+
+== Jenkins pipeline script
+
+Below is a very basic example of a Jenkins pipeline that triggers giblish to render html and pdf documents located in a specific directory in a git repository.

data/giblish.gemspec

@@ -38,11 +38,8 @@ Gem::Specification.new do |spec|
   # Usage: spec.add_runtime_dependency "[gem name]", [[version]]
   spec.add_runtime_dependency "asciidoctor", "~>2.0", ">= 2.0.10"
   spec.add_runtime_dependency "asciidoctor-diagram", ["~> 1.5"]
-  spec.add_runtime_dependency "asciidoctor-pdf", [">= 1.5.0.alpha.18"]
+  spec.add_runtime_dependency "asciidoctor-pdf", [">= 1.5.0.beta.6"]
   spec.add_runtime_dependency "git", "~> 1.3"
   spec.add_runtime_dependency "rouge", "~> 3.3"
-  # needed by asciidoctor-pdf, see instructions at
-  # https://github.com/asciidoctor/asciidoctor-pdf/releases
-#  spec.add_runtime_dependency "prawn-svg", "~> 0.27.1"
- spec.add_runtime_dependency "prawn-svg", "~> 0.29.1"
+  spec.add_runtime_dependency "prawn-svg", "~> 0.29.1"
 end

data/lib/giblish-search.rb

@@ -215,10 +215,7 @@ class SearchDocTree
   private
 
   def get_uri_top
-    if @input_data[:gitbranch]
-      return @input_data[:referer][0,@input_data[:referer].rindex('/')]
-    end
-    return @input_data[:referer].chomp('/')
+    return @input_data[:referer][0,@input_data[:referer].rindex('/')]
   end
 
   def wash_line line
@@ -239,6 +236,8 @@ class SearchDocTree
   # ...
   def format_search_adoc index,uri_top
     str = ""
+    # debug print referer...
+    # str << "uri_top: #{uri_top}\n"
     index.each do |file_info|
       filename = Pathname.new(file_info["filepath"]).basename
       str << "== #{file_info["title"]}\n\n"
@@ -313,7 +312,7 @@ def cgi_main cgi
       ignorecase: cgi.has_key?("ignorecase"),
       useregexp: cgi.has_key?("useregexp"),
       doc_root_abs: Pathname.new(cgi["topdir"]),
-      referer_rel_top: Pathname.new("/#{cgi["reltop"]}"),
+      referer_rel_top: Pathname.new("#{cgi["reltop"]}"),
       referer: cgi.referer,
       uri_path: URI(cgi.referer).path,
       client_css: cgi["css"],
@@ -328,17 +327,16 @@ def cgi_main cgi
   #
   # if the source was rendered from a git branch, the paths
   # search_assets = <index_dir>/../search_assets/<branch_name>/
-  # styles_dir = ../web_assets/css
+  # styles_top = ../web_assets/css
   #
   # and if not, the path is
   # search_assets = <index_dir>/search_assets
-  # styles_dir = ./web_assets/css
+  # styles_top = /web_assets/css
+  # <link rel="stylesheet" href="/web_assets/css/virodoc.css">
   #
-  # The styles dir shall be a relative path
   if input_data[:doc_root_abs].join("./search_assets").exist?
     # this is not from a git branch
     input_data[:search_top] = input_data[:doc_root_abs].join("./search_assets")
-    # input_data[:styles_top] = Pathname.new(input_data[:uri_path]).join("./web_assets/css")
     input_data[:styles_top] = Pathname.new(input_data[:referer_rel_top]).join("web_assets/css")
     input_data[:gitbranch] = false
   elsif input_data[:doc_root_abs].join("../search_assets").exist?
@@ -350,21 +348,53 @@ def cgi_main cgi
     raise ScriptError, "Could not find search_assets dir!"
   end
 
-  # use a relative stylesheet (same as the index page was rendered with)
-  adoc_options =  {
+  # Set some reasonable default attributes and options
+  adoc_attributes = {
       "data-uri" => 1,
-      "linkcss" => 1,
-      "stylesdir" => input_data[:styles_top].to_s,
-      "stylesheet" => input_data[:client_css],
-      "copycss!" => 1
   }
 
+  converter_options = {
+      backend: "html5",
+      # need this to let asciidoctor include the default css if user
+      # has not specified any css
+      safe: Asciidoctor::SafeMode::SAFE,
+      header_footer: true,
+      attributes: adoc_attributes
+  }
+
+  # use a relative stylesheet (same as the index page was rendered with)
+  # if the script has received input in the client_css form field
+  if !input_data[:client_css].nil? && !input_data[:client_css].empty?
+    css_path = if input_data[:styles_top].to_s[0] != '/'
+                 "/" + input_data[:styles_top].to_s
+               else
+                 input_data[:styles_top].to_s
+               end
+    adoc_attributes.merge!({
+                            "linkcss" => 1,
+                            "stylesdir" => css_path,
+                            "stylesheet" => input_data[:client_css],
+                            "copycss!" => 1
+                        })
+  end
+
   # search the docs and render html
   sdt = SearchDocTree.new(input_data)
   docstr = sdt.search
 
+# used for debug purposes
+#   docstr = <<~EOF
+#
+#     #{input_data[:referer_rel_top]} is branch: #{input_data[:gitbranch]}
+#
+#     #{adoc_attributes.to_s}
+#
+#
+#     #{sdt.search}
+#   EOF
+
   # send the result back to the client
-  print Asciidoctor.convert docstr, header_footer: true, attributes: adoc_options
+  print Asciidoctor.convert(docstr, converter_options)
 end
 
 # assume that the file tree looks like this when running
@@ -410,10 +440,14 @@ end
 
 # Usage:
 #   to start a local web server for development work
-# giblish-giblish-search.rb <web_root>
+# giblish-search.rb <web_root>
+#
+#   to run as a cgi script via a previously setup web server
+# giblish-search.rb
 #
-#   to run as a cgi script via a previously setup web server:
-# giblish-giblish-search.rb
+# (note that you might need to rename the script to eg
+# giblish-search.cgi or similar depending on your web server
+# setup)
 #
 if __FILE__ == $PROGRAM_NAME
 
@@ -425,7 +459,6 @@ if __FILE__ == $PROGRAM_NAME
     cgi = CGI.new
     print cgi.header
     begin
-      # hello_world
       cgi_main cgi
     rescue Exception => e
       print e.message

data/lib/giblish/buildgraph.rb

@@ -26,17 +26,20 @@ module Giblish
       @next_id = 0
       @processed_docs = processed_docs
       @paths = paths
-      @options = options.dup
-      @extension = options.key?(:extension) ? options[:extension] : "html"
+      @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
     end
 
     # get the asciidoc source for the document.
-    def source
+    def source(make_searchable = false)
       <<~DOC_STR
         #{generate_header}
+        #{add_search_box if make_searchable}
+        #{generate_graph_header}
         #{generate_labels}
         #{generate_deps}
         #{generate_footer}
@@ -58,15 +61,9 @@ module Giblish
       result
     end
 
-    def generate_header
+    def generate_graph_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.
 
@@ -84,6 +81,18 @@ module Giblish
       DOC_STR
     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')}
+
+      DOC_STR
+    end
+
     def generate_footer
       <<~DOC_STR
         }
@@ -91,6 +100,15 @@ module Giblish
       DOC_STR
     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
+      )
+    end
+
     def make_dot_entry(doc_dict, info)
       # split title into multiple rows if it is too long
       line_length = 15

data/lib/giblish/buildindex.rb

@@ -58,33 +58,13 @@ module Giblish
 
     def add_search_box
       # TODO: Fix the hard-coded path
-      cgi_path = "/cgi-bin/giblish-search.cgi"
-      css = @converter.converter_options[:attributes]["stylesheet"]
-
-      # button with magnifying glass icon (not working when deployed)
-      # <button id="search" type="submit"><i class="fa fa-search"></i></button>
-      <<~SEARCH_INFO
-      ++++
-        <form class="example" action="#{cgi_path}" style="margin:20px 0px 20px 0px;max-width:380px">
-            Search all documents: 
-            <input id="searchphrase" type="text" placeholder="Search.." name="searchphrase"/>
-            <button id="search" type="submit">Search</button>
-            <br>
-
-            <input id="ignorecase" type="checkbox" value="true" name="ignorecase" checked/>
-            <label for="ignorecase">Ignore Case</label>
-            &nbsp;&nbsp;
-            <input id="useregexp" type="checkbox" value="true" name="regexp"/>
-            <label for="useregexp">Use Regexp</label>
-
-            <input type="hidden" name="topdir" value="#{@paths.dst_root_abs.to_s}"</input>
-            <input type="hidden" name="reltop" value="#{@paths.reldir_from_web_root(@paths.dst_root_abs)}"</input>
-            <input type="hidden" name="css" value="#{css}"</input>
-        </form>
-      ++++
-
-      SEARCH_INFO
+      Giblish::generate_search_box_html(
+          @converter.converter_options[:attributes]["stylesheet"],
+          "/cgi-bin/giblish-search.cgi",
+          @paths
+      )
     end
+
     def get_docid_statistics
       largest = ""
       clash = []

data/lib/giblish/core.rb

@@ -69,38 +69,53 @@ module Giblish
       # build index and other fancy stuff if not suppressed
       unless @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
+        dep_graph_exist = @options[:resolveDocid] && build_graph_page
 
         # build a reference index
-        adoc_logger = Giblish::AsciidoctorLogger.new Logger::Severity::WARN
-        ib = index_factory
-        @converter.convert_str(
-            ib.source(
-                dep_graph_exist,@options[:make_searchable]
-            ),
-            @paths.dst_root_abs, "index",
-            logger: adoc_logger)
-
-        # clean up cached files and adoc resources
-        remove_diagram_temps if dep_graph_exist
-        GC.start
+        build_index_page(dep_graph_exist)
       end
       conv_error
     end
 
     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
+        errors = @converter.convert_str(
+            gb.source(
+                @options[:make_searchable]
+            ),
+            @paths.dst_root_abs,
+            "graph"
+        )
+        remove_diagram_temps unless errors
+        !errors
+      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
+    end
+
+    def build_index_page(dep_graph_exist)
+      # build a reference index
+      adoc_logger = Giblish::AsciidoctorLogger.new Logger::Severity::WARN
+      ib = index_factory
+      @converter.convert_str(
+          ib.source(
+              dep_graph_exist,@options[:make_searchable]
+          ),
+          @paths.dst_root_abs,
+          "index",
+          logger: adoc_logger
+      )
+
+      # clean up cached files and adoc resources
+      GC.start
+    end
+
     # get the correct index builder type depending on supplied
     # user options
     def index_factory

data/lib/giblish/docconverter.rb

@@ -39,8 +39,11 @@ module Giblish
       # the user if applicable
       @converter_options[:attributes] = DEFAULT_ATTRIBUTES.dup
       @converter_options[:attributes].merge!(options[:attributes]) unless options[:attributes].nil?
-
       @converter_options[:backend] = options[:backend]
+
+      # give derived classes the opportunity to add options and attributes
+      add_backend_options(@converter_options)
+      add_backend_attributes(@converter_options[:attributes])
     end
 
     # Public: Convert one single adoc file using the specific conversion
@@ -56,23 +59,18 @@ module Giblish
 
       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])
+      # update the relevant options for each specific document
+      set_common_doc_specific_options(filepath,logger)
 
-      # set a specific logger instance to-be-used by asciidoctor
-      @converter_options[:logger] = logger unless logger.nil?
+      # give derived classes the opportunity to set doc specific attributes
+      add_doc_specific_attributes(filepath,true, @converter_options[:attributes])
 
       Giblog.logger.debug {"converter_options: #{@converter_options}"}
 
       # do the actual conversion
       doc = Asciidoctor.convert_file filepath, @converter_options
 
+      # bail out if asciidoctor failed to convert the doc
       if logger && logger.max_severity && logger.max_severity > Logger::Severity::WARN
         raise RuntimeError, "Failed to convert the file #{filepath}"
       end
@@ -88,6 +86,7 @@ module Giblish
     # Returns: whether any errors occured during conversion (true) or
     # not (false).
     def convert_str(src_str, dst_dir, basename,logger: nil)
+
       index_opts = @converter_options.dup
 
       # use the same options as when converting all docs
@@ -98,6 +97,10 @@ module Giblish
       index_opts[:base_dir] = dst_dir.to_s
       index_opts.delete_if {|k, _v| %i[to_file].include? k}
 
+      # give derived classes the opportunity to set doc specific attributes
+      index_filepath = dst_dir + "#{basename}.#{index_opts[:fileext]}"
+      add_doc_specific_attributes(index_filepath,false, index_opts[:attributes])
+
       # load and convert the document using the converter options
       doc = nil, output = nil
 
@@ -108,105 +111,176 @@ module Giblish
         doc = Asciidoctor.load src_str, index_opts
         output = doc.convert index_opts
 
-        index_filepath = dst_dir + "#{basename}.#{index_opts[:fileext]}"
-
         if logger && logger.max_severity && logger.max_severity > Logger::Severity::WARN
           raise RuntimeError, "Failed to convert string to asciidoc!! Will _not_ generate #{index_filepath.to_s}"
         end
+
+        # write the converted document to an index file located at the
+        # destination root
+        doc.write output, index_filepath.to_s
       rescue Exception => e
         Giblog.logger.error(e)
         conv_error = true
       end
 
-
-      # write the converted document to an index file located at the
-      # destination root
-      doc.write output, index_filepath.to_s
       conv_error
     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
+    # Hook for specific converters to inject their own options.
+    # 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)
+    # backend_options - the option dict from the backend implementation
+    def add_backend_options(backend_options)
+      @converter_options.merge!(backend_options)
+    end
+
+    # Hook for specific converters to inject their own attributes
+    # valid for all conversions.
+    # backend_attributes - the attribute dict from the backend implementation
+    def add_backend_attributes(backend_attributes)
+      @converter_options[:attributes].merge!(backend_attributes)
+    end
+
+    # Hook for specific converters to inject attributes on a per-doc
+    # basis
+    def add_doc_specific_attributes(filepath, is_src, attributes)
+
+    end
+
+    private
+
+    def set_common_doc_specific_options(src_filepath,logger)
+      # create an asciidoc doc object and convert to requested
+      # output using current conversion options
+      @converter_options[:to_dir] = @paths.adoc_output_dir(src_filepath).to_s
+      @converter_options[:base_dir] =
+          Giblish::PathManager.closest_dir(src_filepath).to_s
+      @converter_options[:to_file] =
+          Giblish::PathManager.get_new_basename(src_filepath,
+                                                @converter_options[:fileext])
+      @converter_options[:logger] = logger unless logger.nil?
     end
   end
 
-# Converts asciidoc files to html5 output.
+  # Converts asciidoc files to html5 output.
   class HtmlConverter < DocConverter
     def initialize(paths, options)
       super paths, options
 
-      # handle needed assets for the styling (css et al)
-      html_attrib = setup_web_assets options[:webRoot]
+      # validate that things are ok on the resource front
+      # and copy if needed
+      @dst_asset_dir = @paths.dst_root_abs.join("web_assets")
+      validate_and_copy_resources @dst_asset_dir
 
-      # Setting 'data-uri' makes asciidoctor embed images in the resulting
-      # html file
-      html_attrib["data-uri"] = 1
+      # convenience path to css dir
+      @dst_css_dir = @dst_asset_dir.join("css")
 
-      # tell asciidoctor to use the html5 backend
-      backend_options = {backend: "html5", fileext: "html"}
-      add_backend_options backend_options, html_attrib
+      # identify ourselves as an html converter
+      add_backend_options({backend: "html5", fileext: "html"})
+      # setup the attributes specific for this converter
+      add_backend_attributes(get_common_attributes)
     end
 
-    private
-
-    def setup_stylesheet_attributes(css_dir)
-      return {} if @paths.resource_dir_abs.nil?
+    protected
 
-      # use the supplied stylesheet if there is one
-      attrib = {"linkcss" => 1,
-                "stylesdir" => css_dir,
-                "stylesheet" => "giblish.css",
-                "copycss!" => 1}
+    def add_doc_specific_attributes(filepath, is_src_file, attributes)
+      doc_attributes = {}
+      if @paths.resource_dir_abs and not @web_root
+        # user wants to use own styling without use of a
+        # web root. the correct css link is the relative path
+        # from the specific doc to the common css directory
+        css_rel_dir = if is_src_file
+                        # the filepath is a src path
+                        @paths.relpath_to_dir_after_generate(
+                          filepath,
+                          @dst_css_dir
+                        )
+                      else
+                        # the given file path is the destination path of
+                        # the generated file, find the relative path to the
+                        # css dir
+                        dst_dir = PathManager.closest_dir(filepath)
+                        @dst_css_dir.relative_path_from(dst_dir)
+                      end
+        doc_attributes["stylesdir"] = css_rel_dir.to_s
+      end
 
-      # 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
+      attributes.merge!(doc_attributes)
     end
 
-    # make sure that linked assets are available at dst_root
-    def setup_web_assets(html_dir_root = nil)
-      # only set this up if user has specified a resource dir
-      return {} unless @paths.resource_dir_abs
+    private
+
+    def get_common_attributes
+      # Setting 'data-uri' makes asciidoctor embed images in the resulting
+      # html file
+      html_attrib = {
+          "data-uri" => 1,
+      }
 
-      # 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)
+      if @paths.resource_dir_abs
+        # user wants to use own styling, set common attributes
+        html_attrib.merge!(
+            {
+                "linkcss" => 1,
+                "stylesheet" => @user_style ||= "giblish.css",
+                "copycss!" => 1
+            }
+        )
+
+        # check if user wants to use a web root path
+        @web_root = @paths.web_root_abs
+
+        if @web_root
+          # if user requested a web root to be used, the correct
+          # css link is the relative path from the web root to the
+          # css file. This is true for all documents
+          wr_rel = @dst_css_dir.relative_path_from @web_root
+          Giblog.logger.info {"Relative web root: #{wr_rel}"}
+          html_attrib["stylesdir"] = "/" << wr_rel.to_s
+        end
+      end
+      html_attrib
+    end
 
-      # copy needed assets
+    def copy_resource_dir(dst_dir)
+      # create assets_dir and copy everything in the resource dir
+      # to the destination
+      Dir.exist?(dst_dir) || FileUtils.mkdir_p(dst_dir)
+
+      # copy all subdirs that exist in the source tree to the
+      # dst tree
       %i[css fonts images].each do |dir|
         src = "#{@paths.resource_dir_abs}/#{dir}"
-        Dir.exist?(src) && FileUtils.copy_entry(src, "#{assets_dir}/#{dir}")
+        Dir.exist?(src) && FileUtils.copy_entry(src, "#{dst_dir}/#{dir}")
       end
+    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
+    # make as sure as we can that the user has given a
+    # directory with valid resources
+    def validate_and_copy_resources(dst_dir)
+      # we don't have a resource path, which is fine, use
+      # defaults
+      return nil unless @paths.resource_dir_abs
+
+      # If user has requested the use of a specific css, use that,
+      # otherwise use asciidoctor default css
+      if @user_style
+        # Make sure that a user supplied stylesheet ends with .css or .CSS
+        @user_style && @user_style =
+            /\.(css|CSS)$/ =~ @user_style ? @user_style : "#{@user_style}.css"
+
+        # bail out if we can not find the given css file
+        src_css_path = @paths.resource_dir_abs.
+            join("css").join(Pathname.new(@user_style))
+        raise RuntimeError, "Could not find the specified " +
+            "css file at: #{src_css_path}" unless src_css_path.exist?
       end
 
-      Giblog.logger.info {"stylesheet dir: #{assets_dir}"}
-      setup_stylesheet_attributes "#{assets_dir}/css"
+      copy_resource_dir dst_dir
     end
   end
 
@@ -214,10 +288,10 @@ module Giblish
     def initialize(paths, options)
       super paths, options
 
-      pdf_attrib = setup_pdf_attribs
-
-      backend_options = {backend: "pdf", fileext: "pdf"}
-      add_backend_options backend_options, pdf_attrib
+      # identify ourselves as a pdf converter
+      add_backend_options({backend: "pdf", fileext: "pdf"})
+      # setup the attributes specific for this converter
+      add_backend_attributes(setup_pdf_attribs)
     end
 
     private

data/lib/giblish/gititf.rb

@@ -25,7 +25,7 @@ module Giblish
     # parent
     # message
     def file_log(filename)
-      o, e, s = exec_cmd("log", %w[--follow --date=iso --], filename)
+      o, e, s = exec_cmd("log", %w[--follow --date=iso --], "'#{filename}'")
       raise "Failed to get git log for #{filename}!!\n#{e}" if s.exitstatus != 0
 
       process_log_output(o)

data/lib/giblish/utils.rb

@@ -86,6 +86,7 @@ module Giblish
     attr_reader :src_root_abs
     attr_reader :dst_root_abs
     attr_reader :resource_dir_abs
+    attr_reader :web_root_abs
 
     # Public:
     #
@@ -95,7 +96,7 @@ module Giblish
     #            tree
     # resource_dir - a string or pathname with the directory containing
     #                resources
-    def initialize(src_root, dst_root, resource_dir = nil, web_root = false)
+    def initialize(src_root, dst_root, resource_dir = nil, web_root = nil)
       # Make sure that the source root exists in the file system
       @src_root_abs = Pathname.new(src_root).realpath
       self.dst_root_abs = dst_root
@@ -104,7 +105,11 @@ module Giblish
       resource_dir && (@resource_dir_abs = Pathname.new(resource_dir).realpath)
 
       # Set web root if given by user
-      @web_root_abs = web_root ? Pathname.new(web_root) : nil
+      @web_root_abs = nil
+      if web_root
+        web_root = "/" + web_root unless web_root[0] == '/'
+        @web_root_abs = web_root ? Pathname.new(web_root) : nil
+      end
     end
 
     def dst_root_abs=(dst_root)
@@ -115,26 +120,72 @@ module Giblish
     end
 
     # Public: Get the relative path from the source root dir to the
-    #         source file dir.
+    #         directory where the supplied path points.
     #
-    # in_path - an absolute or relative path
+    # in_path - an absolute or relative path to a file or dir
     def reldir_from_src_root(in_path)
-      p = in_path.is_a?(Pathname) ? in_path : Pathname.new(in_path)
+      p = self.class.closest_dir in_path
+      p.relative_path_from(@src_root_abs)
+    end
 
-      # Get absolute source dir path
-      src_abs = p.directory? ? p.realpath : p.dirname.realpath
+    # Public: Get the relative path from the
+    #         directory where the supplied path points to
+    #         the src root dir
+    #
+    # path - an absolute or relative path to a file or dir
+    def reldir_to_src_root(path)
+      src = self.class.closest_dir path
+      @src_root_abs.relative_path_from(src)
+    end
 
-      # Get relative path from source root dir
-      src_abs.relative_path_from(@src_root_abs)
+    # Public: Get the relative path from the dst root dir to the
+    #         directory where the supplied path points.
+    #
+    # path - an absolute or relative path to a file or dir
+    def reldir_from_dst_root(path)
+      dst = self.class.closest_dir path
+      dst.relative_path_from(@dst_root_abs)
     end
 
-    def reldir_from_web_root(in_path)
-      p = in_path.is_a?(Pathname) ? in_path : Pathname.new(in_path)
-      return p if @web_root_abs.nil?
+    # Public: Get the relative path from the
+    #         directory where the supplied path points to
+    #         the dst root dir
+    #
+    # path - an absolute or relative path to a file or dir
+    def reldir_to_dst_root(path)
+      dst = self.class.closest_dir path
+      @dst_root_abs.relative_path_from(dst)
+    end
+
+    # return the destination dir corresponding to the given src path
+    # the src path must exist in the file system
+    def dst_abs_from_src_abs(src_path)
+      src_abs = (self.class.to_pathname src_path).realpath
+      src_rel = reldir_from_src_root src_abs
+      @dst_root_abs.join(src_rel)
+    end
 
+    # return the relative path from a generated document to
+    # the supplied folder given the corresponding absolute source
+    # file path
+    def relpath_to_dir_after_generate(src_filepath,dir_path)
+      dst_abs = dst_abs_from_src_abs(src_filepath)
+      dir = self.class.to_pathname(dir_path)
+      dir.relative_path_from(dst_abs)
+    end
+
+    def reldir_from_web_root(path)
+      p = self.class.closest_dir path
+      return p if @web_root_abs.nil?
       p.relative_path_from(@web_root_abs)
     end
 
+    def reldir_to_web_root(path)
+      p = self.class.closest_dir path
+      return p if @web_root_abs.nil?
+      @web_root_abs.relative_path_from(p)
+    end
+
     def adoc_output_file(infile_path, extension)
       # Get absolute source dir path
       src_dir_abs = self.class.closest_dir infile_path
@@ -173,6 +224,12 @@ module Giblish
       dst_abs.relative_path_from(src_abs)
     end
 
+    # return a pathname, regardless if the given path is a Pathname or
+    # a string
+    def self.to_pathname(path)
+      path.is_a?(Pathname) ? path : Pathname.new(path)
+    end
+
     # Public: Get the basename for a file by replacing the file
     #         extention of the source file with the supplied one.
     #
@@ -196,7 +253,7 @@ module Giblish
     #          - the directory itself when called with an existing directory
     #          - the parent dir when called with a non-existing file/directory
     def self.closest_dir(in_path)
-      sr = in_path.is_a?(Pathname) ? in_path : Pathname.new(in_path)
+      sr = self.to_pathname(in_path)
       if sr.exist?
         sr.directory? ? sr.realpath : sr.dirname.realpath
       else
@@ -302,4 +359,40 @@ module Giblish
   module_function :which
 
 
+  # returns raw html that displays a search box to let the user
+  # acces the text search functionality.
+  #
+  # css          - the name of the css file to use for the search box layout
+  # cgi_path     - the path to a cgi script that implements the server side
+  #                functionality of searching the text
+  # path_manager - an instance of the path manager class to keep track of all
+  #                destinations.
+  def generate_search_box_html(css, cgi_path, paths)
+
+    # button with magnifying glass icon (not working when deployed)
+    # <button id="search" type="submit"><i class="fa fa-search"></i></button>
+    <<~SEARCH_INFO
+      ++++
+        <form class="example" action="#{cgi_path}" style="margin:20px 0px 20px 0px;max-width:380px">
+            Search all documents: 
+            <input id="searchphrase" type="text" placeholder="Search.." name="searchphrase"/>
+            <button id="search" type="submit">Search</button>
+            <br>
+
+            <input id="ignorecase" type="checkbox" value="true" name="ignorecase" checked/>
+            <label for="ignorecase">Ignore Case</label>
+            &nbsp;&nbsp;
+            <input id="useregexp" type="checkbox" value="true" name="regexp"/>
+            <label for="useregexp">Use Regexp</label>
+
+            <input type="hidden" name="topdir" value="#{paths.dst_root_abs}"</input>
+            <input type="hidden" name="reltop" value="#{paths.reldir_from_web_root(paths.dst_root_abs)}"</input>
+            <input type="hidden" name="css" value="#{css}"</input>
+        </form>
+      ++++
+
+    SEARCH_INFO
+  end
+  module_function :generate_search_box_html
+
 end

data/lib/giblish/version.rb

@@ -1,3 +1,3 @@
 module Giblish
-  VERSION = "0.5.2".freeze
+  VERSION = "0.6.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: giblish
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Anders Rillbert
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-06-22 00:00:00.000000000 Z
+date: 2019-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -106,14 +106,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.5.0.alpha.18
+        version: 1.5.0.beta.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.5.0.alpha.18
+        version: 1.5.0.beta.6
 - !ruby/object:Gem::Dependency
   name: git
   requirement: !ruby/object:Gem::Requirement
@@ -181,6 +181,20 @@ files:
 - data/testdocs/wellformed/docidtest/docid_2.adoc
 - data/testdocs/wellformed/simple.adoc
 - data/testdocs/wellformed/source_highlighting/highlight_source.adoc
+- docgen/resources/css/giblish.css
+- docgen/resources/fonts/Ubuntu-B.ttf
+- docgen/resources/fonts/Ubuntu-BI.ttf
+- docgen/resources/fonts/Ubuntu-R.ttf
+- docgen/resources/fonts/Ubuntu-RI.ttf
+- docgen/resources/fonts/mplus1p-regular-fallback.ttf
+- docgen/resources/images/giblish_logo.png
+- docgen/resources/images/giblish_logo.svg
+- docgen/resources/themes/giblish.yml
+- docgen/scripts/Jenkinsfile
+- docgen/scripts/githook_examples/post-update.example
+- docs/setup_server.adoc
+- docs/setup_server_assets/Render Documents.png
+- docs/setup_server_assets/View Documents.png
 - exe/giblish
 - giblish.gemspec
 - lib/giblish-search.rb
@@ -198,15 +212,6 @@ files:
 - lib/giblish/pathtree.rb
 - lib/giblish/utils.rb
 - lib/giblish/version.rb
-- resources/css/giblish.css
-- resources/fonts/Ubuntu-B.ttf
-- resources/fonts/Ubuntu-BI.ttf
-- resources/fonts/Ubuntu-R.ttf
-- resources/fonts/Ubuntu-RI.ttf
-- resources/fonts/mplus1p-regular-fallback.ttf
-- resources/images/giblish_logo.png
-- resources/images/giblish_logo.svg
-- resources/themes/giblish.yml
 homepage: https://github.com/rillbert/giblish
 licenses:
 - MIT