giblish 0.7.6 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01704f427e4785240f22f270809fc7daba1b92a420064459d1d77bfce5091e10
-  data.tar.gz: 6ae9177e72be9aa5a21f3e0b622e2756dc579b704cbaa64767503a1b06666074
+  metadata.gz: a797e1a9f716863a0aa11f0fa22eb83da66d42d2d3d4e2ed722def41b2b79f59
+  data.tar.gz: f3eaee6f9a9e2478401e9fadeb60ef0e22233352f49e5b6d20162adc3b301241
 SHA512:
-  metadata.gz: 06de334ef986255d0559dcb1ca38850205a2f21c9eafe7c803508b8942cb9abdb8f194f9010ba716b7f3bb9bca834511e04c8d3ec8b5ab5af8d905874dd5edba
-  data.tar.gz: 30150805ce92a8aaa23dc67167cea23db43a7adcb9b688d64352019a7e60b2a0b5fa0c6aef6d01e75d83f7c4dd018a763fc5ebdf6b4e8df95f161883a8212376
+  metadata.gz: d671ffe2adbdd555e8a0253ccaa0a2ccb3756bfed0745642e7de47d5786bc65556b996cb4d7bd3d11a7ce0477c395b5f675970b61be47db1d128a52d87295201
+  data.tar.gz: 44874cd2385f1b263389255a2ee2d8bb18a644c4937aea661b2739a9b7b2d605bf1b6e3ff05954b7b915c290183b8f890507ce4ffda9bc0b21135a331fa76839

data/.rubocop.yml

@@ -1,7 +1,6 @@
 
 AllCops:
-  TargetRubyVersion: 2.3
-  Enabled: true
+  TargetRubyVersion: 2.7
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/.ruby-version

@@ -1 +1 @@
-2.6.1
+2.7.3

data/giblish.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
                        EOF
   spec.homepage      = "https://github.com/rillbert/giblish"
   spec.license       = "MIT"
-  spec.required_ruby_version = ">= 2.3"
+  spec.required_ruby_version = ">= 2.7"
 
   # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
   # delete this section to allow pushing this gem to any host.
@@ -38,12 +38,13 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 11.0"
   spec.add_development_dependency "oga", "~> 2.15"
   spec.add_development_dependency 'thor', '~> 0.20.3'
+  spec.add_development_dependency "asciidoctor-mathematical", "~> 0.3.5"
 
   # 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", ">= 1.5.3"]
-  spec.add_runtime_dependency "git", "~> 1.7"
-  spec.add_runtime_dependency "rouge", "~> 3.24"
-  spec.add_runtime_dependency "prawn-svg", "~> 0.30.0"
+  spec.add_runtime_dependency "asciidoctor", "~>2.0", ">= 2.0.16"
+  spec.add_runtime_dependency "asciidoctor-diagram", ["~> 2.1"]
+  spec.add_runtime_dependency "asciidoctor-pdf", ["~> 1.6", ">= 1.6.0"]
+  spec.add_runtime_dependency "git", "~> 1.9"
+  spec.add_runtime_dependency "rouge", "~> 3.0"
+  spec.add_runtime_dependency "prawn-svg", "~> 0.32.0"
 end

data/lib/giblish/application.rb

@@ -1,19 +1,13 @@
-
 require_relative "cmdline"
 require_relative "core"
 require_relative "utils"
 
 module Giblish
+  # The 'main' class of giblish
   class Application
-
-    # return exit status (0 for success)
-    def run_with_args(args)
-      run args
-    end
-
     # does not return, exits with status code
     def run_from_cmd_line
-      status = run ARGV
+      status = run(ARGV)
       exit(status)
     end
 
@@ -27,36 +21,45 @@ module Giblish
 
       # Parse cmd line
       cmdline = CmdLineParser.new args
-
       Giblog.logger.debug { "cmd line args: #{cmdline.args}" }
 
-      # Convert using given args
+      exit_code = execute_conversion(cmdline)
+      Giblog.logger.info { "Giblish is done!" } if exit_code.zero?
+      exit_code
+    end
+
+    private
+
+    # Convert using given args
+    # return exit code (0 for success)
+    def execute_conversion(cmdline)
       conv_error = false
       begin
-        if cmdline.args[:gitRepoRoot]
-          Giblog.logger.info { "User asked to parse a git repo" }
-          gc = GitRepoConverter.new cmdline.args
-          conv_error = gc.convert
-        else
-          tc = FileTreeConverter.new cmdline.args
-          conv_error = tc.convert
-        end
-        Giblog.logger.info { "Giblish is done!" }
-      rescue Exception => e
+        conv_error = converter_factory(cmdline).convert
+      rescue StandardError => e
         log_error e
         conv_error = true
       end
       conv_error ? 1 : 0
     end
 
-    private
+    # return the converter corresponding to the given cmd line
+    # options
+    def converter_factory(cmdline)
+      if cmdline.args[:gitRepoRoot]
+        Giblog.logger.info { "User asked to parse a git repo" }
+        GitRepoConverter.new(cmdline.args)
+      else
+        FileTreeConverter.new(cmdline.args)
+      end
+    end
 
-    def log_error(ex)
+    def log_error(exc)
       Giblog.logger.error do
         <<~ERR_MSG
-          Error: #{ex.message}
+          Error: #{exc.message}
           Backtrace:
-          \t#{ex.backtrace.join("\n\t")}
+          \t#{exc.backtrace.join("\n\t")}
 
           cmdline.usage
         ERR_MSG

data/lib/giblish/buildgraph.rb

@@ -1,4 +1,3 @@
-
 module Giblish
   # Builds an asciidoc page with an svg image with a
   # digraph showing how documents reference each other.
@@ -6,16 +5,14 @@ module Giblish
   # Graphviz is used as the graph generator and must be available
   # as a valid engine via asciidoctor-diagram for this class to work.
   class GraphBuilderGraphviz
-
     # the dependency graph relies on graphwiz (dot), check if we can access that
     def self.supported
-      return !Giblish.which('dot').nil?
+      !Giblish.which("dot").nil?
     end
 
     # Supported options:
     # :extension - file extension for URL links (default is .html)
     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
 
@@ -28,20 +25,19 @@ module Giblish
       @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,
+        web_assets_top: @deployment_info.web_path,
+        search_assets_top: @deployment_info.search_assets_path
       }
     end
 
     # get the asciidoc source for the document.
-    def source(make_searchable = false)
-      <<~DOC_STR
+    def source(make_searchable: false)
+      s = <<~DOC_STR
         #{generate_header}
         #{add_search_box if make_searchable}
         #{generate_graph_header}
@@ -49,6 +45,7 @@ module Giblish
         #{generate_deps}
         #{generate_footer}
       DOC_STR
+      s
     end
 
     def cleanup
@@ -56,7 +53,7 @@ module Giblish
       # 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}"}
+      Giblog.logger.info { "Removing cached files at: #{@paths.dst_root_abs.join('docdeps.svg')}" }
       @paths.dst_root_abs.join("docdeps.svg").delete
     end
 
@@ -70,13 +67,13 @@ module Giblish
           doc.src_file.to_s.eql? src_file
         end
         raise "Inconsistent docs when building graph!! found no match for #{src_file}" if d.nil?
+
         result[d] = id_array if d.converted
       end
       result
     end
 
     def generate_graph_header
-      t = Time.now
       <<~DOC_STR
         Below is a graph that visualizes what documents (by doc-id) a specific
         document references.
@@ -89,7 +86,7 @@ module Giblish
                 fillcolor="#ebf26680",
                 style="filled,solid"
               ]
-        
+
         rankdir="LR"
 
       DOC_STR
@@ -115,10 +112,10 @@ module Giblish
     end
 
     def add_search_box
-      Giblish::generate_search_box_html(
-          @converter_options[:attributes]["stylesheet"],
-          "/cgi-bin/giblish-search.cgi",
-          @search_opts
+      Giblish.generate_search_box_html(
+        @converter_options[:attributes]["stylesheet"],
+        "/cgi-bin/giblish-search.cgi",
+        @search_opts
       )
     end
 
@@ -126,18 +123,20 @@ module Giblish
       # split title into multiple rows if it is too long
       line_length = 15
       lines = [""]
-      info.title.split(" ").inject("") do |l,w|
-        line = l + " " + w
-        lines[-1] = line
-        if line.length > line_length
-          # create a new, empty, line
-          lines << ""
-          ""
-        else
-          line
+      unless info&.title.nil?
+        info.title.split(" ").inject("") do |l, w|
+          line = "#{l} #{w}"
+          lines[-1] = line
+          if line.length > line_length
+            # create a new, empty, line
+            lines << ""
+            ""
+          else
+            line
+          end
         end
-      end unless info.title.nil?
-      title = lines.select { |l| l.length > 0 }.map {|l| l}.join("\n")
+      end
+      title = lines.select { |l| l.length.positive? }.map { |l| l }.join("\n")
 
       # create the label used to display the node in the graph
       dot_entry = if info.doc_id.nil?
@@ -151,12 +150,12 @@ module Giblish
       # add clickable links in the case of html output (this is not supported
       # out-of-the-box for pdf).
       rp = info.rel_path.sub_ext(".#{@extension}")
-      case @extension
-        when "html"
-          dot_entry += ", URL=\"#{rp}\" ]"
-        else
-          dot_entry += " ]"
-      end
+      dot_entry += case @extension
+                   when "html"
+                     ", URL=\"#{rp}\" ]"
+                   else
+                     " ]"
+                   end
       doc_dict[doc_id] = dot_entry
     end
 
@@ -172,10 +171,9 @@ module Giblish
       node_dict = node_dict.sort.reverse.to_h
 
       # produce the string with all node entries
-      node_str = node_dict.map do |k,v|
+      node_dict.map do |_k, v|
         v
       end.join("\n")
-      node_str
     end
 
     def generate_deps
@@ -183,7 +181,7 @@ module Giblish
       @dep_graph.each do |info, targets|
         # set either the real or the generated id as source
         src_part = if info.doc_id.nil?
-                      "\"#{@noid_docs[info]}\""
+                     "\"#{@noid_docs[info]}\""
                    else
                      "\"#{info.doc_id}\""
                    end
@@ -208,11 +206,11 @@ module Giblish
     end
   end
 
+  # specializes generation of a document dependency graph for
+  # docs rendered from a git repo.
   class GitGraphBuilderGraphviz < GraphBuilderGraphviz
-    def initialize(processed_docs, paths, deployment_info, options = {}, git_repo)
+    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

@@ -6,7 +6,6 @@ require_relative "gititf"
 require_relative "docinfo"
 
 module Giblish
-
   # Base class with common functionality for all index builders
   class BasicIndexBuilder
     # set up the basic index building info
@@ -19,29 +18,42 @@ module Giblish
       @src_str = ""
       @manage_docid = handle_docid
       @search_opts = {
-          web_assets_top: @deployment_info.web_path,
-          search_assets_top: @deployment_info.search_assets_path,
+        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)
+    def source(dep_graph_exists: false, make_searchable: false)
       <<~DOC_STR
         #{generate_title_and_header}
+
         #{generate_date_info}
+
         #{add_search_box if make_searchable}
-        #{generate_tree(dep_graph_exists)}
+
+        #{add_docid_info if @manage_docid}
+
+        #{add_depgraph_id if dep_graph_exists}
+
+        #{generate_tree}
+
         #{generate_details}
+
         #{generate_footer}
       DOC_STR
     end
 
     protected
+
+    def source_root
+      @paths.src_root_abs
+    end
+
     def generate_title_and_header
       <<~DOC_HEADER
         = Document index
-        from #{@paths.src_root_abs}
+        from #{source_root}
         :icons: font
-
       DOC_HEADER
     end
 
@@ -50,7 +62,6 @@ module Giblish
       <<~SRC_FILE_TXT
         Source file::
         #{doc_info.src_file}
-
       SRC_FILE_TXT
     end
 
@@ -62,14 +73,14 @@ module Giblish
     end
 
     def add_search_box
-      Giblish::generate_search_box_html(
-          @converter.converter_options[:attributes]["stylesheet"],
-          "/cgi-bin/giblish-search.cgi",
-          @search_opts
+      Giblish.generate_search_box_html(
+        @converter.converter_options[:attributes]["stylesheet"],
+        "/cgi-bin/giblish-search.cgi",
+        @search_opts
       )
     end
 
-    def get_docid_statistics
+    def docid_statistics
       largest = ""
       clash = []
       @processed_docs.each do |d|
@@ -82,52 +93,42 @@ module Giblish
       # find the duplicate doc ids (if any)
       duplicates = clash.select { |id| clash.count(id) > 1 }.uniq.sort
 
-      return largest,duplicates
+      [largest, duplicates]
     end
 
-    def generate_doc_id_info(dep_graph_exists)
-      largest,duplicates = get_docid_statistics
-      docid_info_str = if ! @manage_docid
-                         ""
-                       else
-                         "The 'largest' document id found when resolving :docid: tags in all documents is *#{largest}*."
-                       end
-
-      docid_warn_str = if duplicates.length.zero?
-                         ""
-                       else
-                         "WARNING: The following document ids are used for more than one document. " +
-                             "_#{duplicates.map {|id| id.to_s}.join(",") }_"
-                       end
+    def add_docid_info
+      largest, duplicates = docid_statistics
+      <<~DOC_ID_INFO
+        *Document id numbers:* The 'largest' document id found when resolving
+        :docid: tags in all documents is *#{largest}*.
+
+        #{if duplicates.length.zero?
+            ''
+          else
+            'WARNING: The following document ids are used for '\
+            'more than one document. '\
+            "_#{duplicates.map(&:to_s).join(',')}_"
+          end}
+
+      DOC_ID_INFO
+    end
 
+    def add_depgraph_id
       # include link to dependency graph if it exists
-      dep_graph_str = if dep_graph_exists
-                        "_(a visual graph of document dependencies can be found " \
-                      "<<./graph.adoc#,here>>)_"
-                      else
-                        ""
-                      end
-
-      if @manage_docid
-        <<~DOC_ID_INFO
-        *Document id numbers:* #{docid_info_str} #{dep_graph_str}
-  
-        #{docid_warn_str}
-
-        DOC_ID_INFO
-      else
-        ""
-      end
+      <<~DEPGRAPH_STR
+        _A visual graph of document dependencies can be found
+        <<./graph.adoc#,here>>
+      DEPGRAPH_STR
     end
 
-    def generate_tree(dep_graph_exists)
+    def generate_tree
       # output tree intro
-      tree_string = <<~DOC_HEADER
-        #{generate_doc_id_info dep_graph_exists}
-
-        [subs=\"normal\"]
-        ----
-      DOC_HEADER
+      tree_string = String.new(
+        <<~DOC_HEADER
+          [subs=\"normal\"]
+          ----
+        DOC_HEADER
+      )
 
       # build up tree of paths
       root = PathTree.new
@@ -153,10 +154,11 @@ module Giblish
 
     private
 
-    def generate_conversion_info(d)
-      return "" if d.stderr.empty?
+    def generate_conversion_info(doc_info)
+      return "" if doc_info.stderr.empty?
+
       # extract conversion warnings from asciddoctor std err
-      conv_warnings = d.stderr.gsub(/^/, " * ")
+      conv_warnings = doc_info.stderr.gsub(/^/, " * ")
 
       # assemble info to index page
       <<~CONV_INFO
@@ -198,7 +200,7 @@ module Giblish
 
       # Calculate padding to get (conv issues) and details aligned between entries
       padding = 70
-      [doc_title, prefix_str, warning_label].each {|p| padding -= p.length}
+      [doc_title, prefix_str, warning_label].each { |p| padding -= p.length }
       padding = 0 unless padding.positive?
       "#{prefix_str} #{doc_link}#{' ' * padding}#{warning_label} #{doc_details}"
     end
@@ -222,51 +224,51 @@ module Giblish
     end
 
     # Derived classes can override this with useful info
-    def generate_history_info(_d)
+    def generate_history_info(_doc_info)
       ""
     end
 
-    def generate_detail_fail(d)
+    def generate_detail_fail(doc_info)
       <<~FAIL_INFO
-        === #{d.src_file}
+        === #{doc_info.src_file}
 
         #{display_source_file(d)}
 
         Error detail::
-        #{d.stderr}
+        #{doc_info.stderr}
 
         ''''
 
       FAIL_INFO
     end
 
-    def generate_detail(d)
+    def generate_detail(doc_info)
       # Generate detail info
-      purpose_str = if d.purpose_str.nil?
+      purpose_str = if doc_info.purpose_str.nil?
                       ""
                     else
-                      "Purpose::\n#{d.purpose_str}"
+                      "Purpose::\n#{doc_info.purpose_str}"
                     end
 
-      doc_id_str = if !d.doc_id.nil? && @manage_docid
-                     "Doc id::\n_#{d.doc_id}_"
+      doc_id_str = if !doc_info.doc_id.nil? && @manage_docid
+                     "Doc id::\n_#{doc_info.doc_id}_"
                    else
                      ""
                    end
 
       <<~DETAIL_SRC
-        [[#{Giblish.to_valid_id(d.title.encode("utf-8"))}]]
-        === #{d.title.encode("utf-8")}
+        [[#{Giblish.to_valid_id(doc_info.title.encode('utf-8'))}]]
+        === #{doc_info.title.encode('utf-8')}
 
         #{doc_id_str}
 
         #{purpose_str}
 
-        #{generate_conversion_info d}
+        #{generate_conversion_info doc_info}
 
-        #{display_source_file(d)}
+        #{display_source_file(doc_info)}
 
-        #{generate_history_info d}
+        #{generate_history_info doc_info}
 
         ''''
 
@@ -279,7 +281,7 @@ module Giblish
         root.add_path(d.rel_path.to_s, d)
       end
 
-      details_str = "== Document details\n\n"
+      details_str = String.new("== Document details\n\n")
 
       root.traverse_top_down do |_level, node|
         details_str << if node.leaf?
@@ -318,49 +320,43 @@ module Giblish
         # a git repo root
         @git_repo = Git.open(git_repo_root)
         @git_repo_root = git_repo_root
-      rescue Exception => e
-        Giblog.logger.error {"No git repo! exception: #{e.message}"}
+      rescue StandardError => e
+        Giblog.logger.error { "No git repo! exception: #{e.message}" }
       end
     end
 
     protected
+
     # override basic version and use the relative path to the
     # git repo root instead
     def display_source_file(doc_info)
       # Use the path relative to the git repo root as display
-      src_file = Pathname.
-          new(doc_info.src_file).
-          relative_path_from(@git_repo_root).to_s
+      src_file = Pathname
+                 .new(doc_info.src_file)
+                 .relative_path_from(@git_repo_root).to_s
       <<~SRC_FILE_TXT
         Source file::
         #{src_file}
-
       SRC_FILE_TXT
     end
 
-
-    def generate_title_and_header
-      t = Time.now
-      <<~DOC_HEADER
-        = Document index
-        #{@git_repo.current_branch}
-
-        :icons:
-
-      DOC_HEADER
+    def source_root
+      @git_repo.current_branch
     end
 
-    def generate_history_info(d)
-      str = <<~HISTORY_HEADER
-        File history::
+    def generate_history_info(doc_info)
+      str = String.new(
+        <<~HISTORY_HEADER
+          File history::
 
-        [cols=\"2,3,8\",options=\"header\"]
-        |===
-        |Date |Author |Message
-      HISTORY_HEADER
+          [cols=\"2,3,8\",options=\"header\"]
+          |===
+          |Date |Author |Message
+        HISTORY_HEADER
+      )
 
       # Generate table rows of history information
-      d.history.each do |h|
+      doc_info.history.each do |h|
         str << <<~HISTORY_ROW
           |#{h.date.strftime('%Y-%m-%d')}
           |#{h.author}
@@ -431,10 +427,9 @@ module Giblish
       # get the branch-unique dst-dir
       str = <<~TAG_INFO
         == Tags
-        
-        |===
-        |Tag |Tag comment |Creator |Tagged commit 
 
+        |===
+        |Tag |Tag comment |Creator |Tagged commit
       TAG_INFO
 
       str << @tags.collect do |t|
@@ -443,8 +438,8 @@ module Giblish
 
         <<~A_ROW
           |link:#{dirname}/index.html[#{t.name}]
-          |#{t.annotated? ? t.message : "-"}
-          |#{t.annotated? ? t.tagger.name : "-"}
+          |#{t.annotated? ? t.message : '-'}
+          |#{t.annotated? ? t.tagger.name : '-'}
           |#{t.sha[0, 8]}... committed at #{c.author.date}
         A_ROW
       end.join("\n")
@@ -461,4 +456,4 @@ module Giblish
       str
     end
   end
-end
+end