giblish 0.7.5 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19bcb7fd2f476219f4f104e6e86a8688a3729225444e18d8c0c67e9288a42835
-  data.tar.gz: 2c1d85d59fe970d2fd5739fc1e1f2aa3099d128514bea3e3d8fb810205b11491
+  metadata.gz: 56f7e50e079748482350108862650f943cd6266864b285a1845808443dd46489
+  data.tar.gz: '0911983f515dd0e8719ef9836b69182f5e148b17101414cc703c080ee4681370'
 SHA512:
-  metadata.gz: d56e1b40199396e95ad66f9a1f319ff42efd6aac68db62e3e9c5b8ff593ef79f6e155999ad83fce8666c04e8f674dd8c073b305e0a33d5dde738c04a4f09fb4a
-  data.tar.gz: df30010468ce07b912cb4d2f75e66db05a3396452d15436e52b18516408b9b67b052829520d149c0c101be12615752a4fcfb4ef0950aecef91eb990132cc34c9
+  metadata.gz: 57c8f2974c53343bca7b7bd92e2417441e1c203acbac40e3e35df0502a72eb8d305bc611850c8772675f75938df61c7f4c8032124273677c7ed7e95249066ef3
+  data.tar.gz: 056b23e064ec6b71c96ef6071e5e8fe870693c0950999bea083c23e45d678287c8390f1da4343710ec853e5969632fb1e940fc9177ed7d1a5d430bcff3faa3f6

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/docs/README.adoc

@@ -12,7 +12,7 @@ a destination directory tree containing the corresponding html or pdf files
 and adds some handy tools for easier navigation of the resulting files.
 
 An example of how giblish can generate the master branch of the official asciidoc.org
-documentation git repo can be found at http://www.rillbert.se/adoc/examples/adocorg/master/myindex.html
+documentation git repo can be found at https://www.rillbert.se/asciidoctor_docs/master/myindex.html
 
 The added tools include:
 
@@ -338,10 +338,9 @@ accessible at www.mywebsite.com/cgi-bin/giblish-search.cgi
 
 In my case this returns `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish.rb`. This means that I will find the script in the same directory, i.e. `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib`.
 
- . Copy the server side script to the /cgi-bin dir on the web server. In this example the cgi-bin dir
-   is configured to be /var/www/cgi-bin
+ . Copy the server side script to the /cgi-bin dir on the web server. In this example the cgi-bin dir is configured to be `/var/www/cgi-bin`
 +
- scp /var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish-search.rb rillbert@my.web.server.org:/var/www/cgi-bin/giblish-search.cgi
+ scp /var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish-search.cgi rillbert@my.web.server.org:/var/www/cgi-bin/giblish-search.cgi
 
 ////
 

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