jekyll-theme-open-project-helpers 2.1.4 → 2.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b66bfdb58fa9bd277603af3c29b2736c8af021a144eaa150c59285fa41804ad
-  data.tar.gz: f6c21cb54b396ef4ee17869e5539ca961c9485f669d1370e4071bc5e05034369
+  metadata.gz: 5340ebd6b73a77f544854b7425860b5a2fa78ae1508182b0fa53f2aaa6002906
+  data.tar.gz: 2f9025c1a872c6176924c2f936c9bc1fdb7f14c5ce272da54a96ded564528122
 SHA512:
-  metadata.gz: 521ab65d046b3605ad8efbdb113f9a387986331c23421db0f14afe8429a9a28d4e4bce191275936b59471396541811f1aa7f0b1bd1d964ae08cee7fc227d635a
-  data.tar.gz: fbcbc3022c5930db262ea81afd94ac54544b4c32c817ad2e40f28b893cecc143bb473e66dedeec81a89c9a1585e2ba7cb1f61609a578a5528a1c8bcf11acc5a1
+  metadata.gz: 992ce56cd7eafea9d7167384a227eaff95d3dc20bd368e277f386238b13725db49662185aef4f0f415f28784fe392036bf01196af7d715fb3b1790f4ec66848e
+  data.tar.gz: 9e6d476f0a89b3aee43f1c3e5d0becc5ca2b3ee3d297eb371143587ae19d7182248fd3c6c1c14fe69bfda241e1522a062fcd363dedab3273ee05a5fc323fbb1e

data/.gitignore

@@ -0,0 +1,2 @@
+/Gemfile.lock
+/.rubocop-https*

data/.rubocop.yml

@@ -0,0 +1,10 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+
+# local repo-specific modifications
+# ...
+
+AllCops:
+  TargetRubyVersion: 2.5

data/Gemfile

@@ -0,0 +1,6 @@
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
+source "https://rubygems.org"
+
+gemspec

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/jekyll-theme-open-project-helpers.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name          = 'jekyll-theme-open-project-helpers'
-  s.version       = '2.1.4'
+  s.version       = '2.1.8'
   s.authors       = ['Ribose Inc.']
   s.email         = ['open.source@ribose.com']
 

data/lib/jekyll-theme-open-project-helpers/project_data_reader.rb

@@ -6,7 +6,9 @@ module Jekyll
     DEFAULT_DOCS_SUBTREE = 'docs'
 
     DEFAULT_REPO_REMOTE_NAME = 'origin'
-    DEFAULT_REPO_BRANCH = 'master'
+    DEFAULT_REPO_BRANCH = 'main'
+    # Can be overridden by default_repo_branch in site config.
+    # Used by shallow_git_checkout.
 
     class NonLiquidDocument < Jekyll::Document
       def render_with_liquid?
@@ -42,12 +44,14 @@ module Jekyll
               doc.read
 
               # Add document to Jekyll document database if it refers to software or spec
-              # (as opposed to be some nested document like README)
-              if (doc.url.split('/').size == 4) or (doc.url.split('/').size == 5 and collection.label === 'projects')
+              # (as opposed to be some random nested document within repository source, like a README)
+              doc_url_parts = doc.url.split('/')
+              Jekyll.logger.debug("OPF:", "Reading document in collection #{collection.label} with URL #{doc.url} (#{doc_url_parts.size} parts)")
+              if collection.label != 'projects' or doc_url_parts.size == 5
                 Jekyll.logger.debug("OPF:", "Adding document with URL: #{doc.url}")
                 collection.docs << doc
               else
-                Jekyll.logger.debug("OPF:", "Did NOT add document with URL (nesting level doesn’t match): #{doc.url}")
+                Jekyll.logger.debug("OPF:", "Did NOT add document with URL (possibly nesting level doesn’t match): #{doc.url}")
               end
             else
               Jekyll.logger.debug("OPF:", "Adding static file: #{path}")
@@ -93,7 +97,8 @@ module Jekyll
           git_shallow_checkout(
             File.join(@site.source, 'parent-hub'),
             @site.config['parent_hub']['git_repo_url'],
-            ['assets', 'title.html'])
+            ['assets', 'title.html'],
+            @site.config['parent_hub']['git_repo_branch'])
         end
       end
 
@@ -108,7 +113,8 @@ module Jekyll
           git_shallow_checkout(
             project_path,
             project['site']['git_repo_url'],
-            ['assets', '_posts', '_software', '_specs'])
+            ['assets', '_posts', '_software', '_specs'],
+            project['site']['git_repo_branch'])
 
           
           Jekyll.logger.debug("OPF:", "Reading files in project #{project_path}")
@@ -129,6 +135,7 @@ module Jekyll
         src = index_doc.data['spec_source']
         repo_url = src['git_repo_url']
         repo_subtree = src['git_repo_subtree']
+        repo_branch = src['git_repo_branch']
         build = src['build']
         engine = build['engine']
         engine_opts = build['options'] || {}
@@ -140,13 +147,9 @@ module Jekyll
                       spec_checkout_path
                     end
 
-        repo_checkout = nil
-        begin
-          repo_checkout = git_shallow_checkout(spec_checkout_path, repo_url, [repo_subtree])
-        rescue
-        end
+        repo_checkout = git_shallow_checkout(spec_checkout_path, repo_url, [repo_subtree], repo_branch)
 
-        if repo_checkout
+        if repo_checkout[:success]
           if build_pages
             builder = Jekyll::OpenProjectHelpers::SpecBuilder::new(
               @site,
@@ -217,19 +220,17 @@ module Jekyll
 
           docs = index_doc.data['docs']
           main_repo = index_doc.data['repo_url']
+          main_repo_branch = index_doc.data['repo_branch']
 
           sw_docs_repo = (if docs then docs['git_repo_url'] end) || main_repo
           sw_docs_subtree = (if docs then docs['git_repo_subtree'] end) || DEFAULT_DOCS_SUBTREE
+          sw_docs_branch = (if docs then docs['git_repo_branch'] end) || main_repo_branch
 
           docs_path = "#{index_doc.path.split('/')[0..-2].join('/')}/#{item_name}"
 
-          sw_docs_checkout = nil 
-          begin
-            sw_docs_checkout = git_shallow_checkout(docs_path, sw_docs_repo, [sw_docs_subtree])
-          rescue
-          end
+          sw_docs_checkout = git_shallow_checkout(docs_path, sw_docs_repo, [sw_docs_subtree], sw_docs_branch)
 
-          if sw_docs_checkout
+          if sw_docs_checkout[:success]
             CollectionDocReader.new(site).read(
               docs_path,
               @site.collections[collection_name])
@@ -238,9 +239,9 @@ module Jekyll
           # Get last repository modification timestamp.
           # Fetch the repository for that purpose,
           # unless it’s the same as the repo where docs are.
-          if sw_docs_checkout == nil or sw_docs_repo != main_repo
+          if !sw_docs_checkout[:success] or sw_docs_repo != main_repo
             repo_path = "#{index_doc.path.split('/')[0..-2].join('/')}/_#{item_name}_repo"
-            repo_checkout = git_shallow_checkout(repo_path, main_repo)
+            repo_checkout = git_shallow_checkout(repo_path, main_repo, [], main_repo_branch)
             index_doc.merge_data!({ 'last_update' => repo_checkout[:modified_at] })
           else
             index_doc.merge_data!({ 'last_update' => sw_docs_checkout[:modified_at] })
@@ -248,7 +249,7 @@ module Jekyll
         end
       end
 
-      def git_shallow_checkout(repo_path, remote_url, sparse_subtrees=[])
+      def git_shallow_checkout(repo_path, remote_url, sparse_subtrees, branch_name)
         # Returns hash with timestamp of latest repo commit
         # and boolean signifying whether new repo has been initialized
         # in the process of pulling the data.
@@ -285,6 +286,7 @@ module Jekyll
         end
 
         refresh_condition = @@siteconfig['refresh_remote_data'] || 'last-resort'
+        repo_branch = branch_name || @@siteconfig['default_repo_branch'] || DEFAULT_REPO_BRANCH
 
         unless ['always', 'last-resort', 'skip'].include?(refresh_condition)
           raise RuntimeError.new('Invalid refresh_remote_data value in site’s _config.yml!')
@@ -293,23 +295,42 @@ module Jekyll
         if refresh_condition == 'always'
           repo.fetch(DEFAULT_REPO_REMOTE_NAME, { :depth => 1 })
           repo.reset_hard
-          repo.checkout("#{DEFAULT_REPO_REMOTE_NAME}/#{DEFAULT_REPO_BRANCH}", { :f => true })
+          repo.checkout("#{DEFAULT_REPO_REMOTE_NAME}/#{repo_branch}", { :f => true })
 
         elsif refresh_condition == 'last-resort'
+          # This is the default case.
+
           begin
-            repo.checkout("#{DEFAULT_REPO_REMOTE_NAME}/#{DEFAULT_REPO_BRANCH}", { :f => true })
+            # Let’s try in case this repo has been fetched before (this would never be the case on CI though)
+            repo.checkout("#{DEFAULT_REPO_REMOTE_NAME}/#{repo_branch}", { :f => true })
           rescue Exception => e
-            if e.message.include? "Sparse checkout leaves no entry on working directory"
-              # Supposedly, software docs are missing! No big deal.
+            if is_sparse_checkout_error(e, sparse_subtrees)
+              # Silence errors caused by nonexistent sparse checkout directories
               return {
                 :success => false,
                 :newly_initialized => nil,
                 :modified_at => nil,
               }
             else
+              # In case of any other error, presume repo has not been fetched and do that now.
               Jekyll.logger.debug("OPF:", "Fetching & checking out #{remote_url} for #{repo_path}")
               repo.fetch(DEFAULT_REPO_REMOTE_NAME, { :depth => 1 })
-              repo.checkout("#{DEFAULT_REPO_REMOTE_NAME}/#{DEFAULT_REPO_BRANCH}", { :f => true })
+              begin
+                # Try checkout again
+                repo.checkout("#{DEFAULT_REPO_REMOTE_NAME}/#{repo_branch}", { :f => true })
+              rescue Exception => e
+                if is_sparse_checkout_error(e, sparse_subtrees)
+                  # Again, silence an error caused by nonexistent sparse checkout directories…
+                  return {
+                    :success => false,
+                    :newly_initialized => nil,
+                    :modified_at => nil,
+                  }
+                else
+                  # but this time throw any other error.
+                  raise e
+                end
+              end
             end
           end
         end
@@ -327,6 +348,15 @@ module Jekyll
   end
 end
 
+def is_sparse_checkout_error(err, subtrees)
+  if err.message.include? "Sparse checkout leaves no entry on working directory"
+    Jekyll.logger.debug("OPF: It looks like sparse checkout of these directories failed:", subtrees.to_s)
+    true
+  else
+    false
+  end
+end
+
 Jekyll::Hooks.register :site, :after_init do |site|
   if site.theme  # TODO: Check theme name
     site.reader = Jekyll::OpenProjectHelpers::OpenProjectReader::new(site)

data/lib/jekyll-theme-open-project-helpers/spec_builders/png_diagrams.rb

@@ -1,92 +1,119 @@
-require 'fastimage'
+require "fastimage"
 
 # Recursively go through given list of nav_items, including any nested items,
 # and return a flat array containing navigation items with path specified.
 def get_nav_items_with_path(nav_items)
   items_with_path = []
 
-  for item in nav_items do
-    if item['path']
+  nav_items.each do |item|
+    if item["path"]
       items_with_path.push(item)
     end
 
-    if item['items']
-      items_with_path.concat(get_nav_items_with_path(item['items']))
+    if item["items"]
+      items_with_path.concat(get_nav_items_with_path(item["items"]))
     end
   end
 
-  return items_with_path
+  items_with_path
 end
 
 module Builder
-
   class PngDiagramPage < Jekyll::Page
-    def initialize(site, base, dir, data)
+    EXTRA_STYLESHEETS = [{
+      "href" => "https://unpkg.com/leaflet@1.3.4/dist/leaflet.css",
+      "integrity" => "sha512-puBpdR0798OZvTTbP4A8Ix/l+A4dHDD0DGqYW6RQ+9jxkRFclaxxQb/SJAWZfWAkuyeQUytO7+7N4QKrDh+drA==", # rubocop:disable Layout/LineLength
+      "crossorigin" => "",
+    }].freeze
+
+    EXTRA_SCRIPTS = [{
+      "src" => "https://unpkg.com/leaflet@1.3.4/dist/leaflet.js",
+      "integrity" => "sha512-nMMmRyTVoLYqjP9hrbed9S+FzjZHW5gY1TWCHA5ckwXZBadntCNs8kEqAWdrb9O7rxbCaA4lKTIWjDXZxflOcA==", # rubocop:disable Layout/LineLength
+      "crossorigin" => "",
+    }].freeze
+
+    def initialize(site, base, dir, data) # rubocop:disable Lint/MissingSuper
       @site = site
       @base = base
       @dir = dir
-      @name = 'index.html'
+      @name = "index.html"
 
-      self.process(@name)
+      process(@name)
       self.data ||= data
 
-      self.data['extra_stylesheets'] = [{
-        "href" => "https://unpkg.com/leaflet@1.3.4/dist/leaflet.css",
-        "integrity" => "sha512-puBpdR0798OZvTTbP4A8Ix/l+A4dHDD0DGqYW6RQ+9jxkRFclaxxQb/SJAWZfWAkuyeQUytO7+7N4QKrDh+drA==",
-        "crossorigin" => "",
-      }]
-
-      self.data['extra_scripts'] = [{
-        "src" => "https://unpkg.com/leaflet@1.3.4/dist/leaflet.js",
-        "integrity" => "sha512-nMMmRyTVoLYqjP9hrbed9S+FzjZHW5gY1TWCHA5ckwXZBadntCNs8kEqAWdrb9O7rxbCaA4lKTIWjDXZxflOcA==",
-        "crossorigin" => "",
-      }]
-
-      self.data['layout'] = 'spec'
+      self.data["extra_stylesheets"] = EXTRA_STYLESHEETS
+      self.data["extra_scripts"] = EXTRA_SCRIPTS
+      self.data["layout"] = "spec"
     end
   end
 
   def build_spec_pages(site, spec_info, source, destination, opts)
     images_path = source
     spec_root = destination
-    stub_path = "#{File.dirname(__FILE__)}/png_diagram.html"
     pages = []
 
-    diagram_nav_items = get_nav_items_with_path(spec_info.data['navigation']['items'])
+    diagram_nav_items = get_nav_items_with_path(
+      spec_info.data["navigation"]["items"],
+    )
+    not_found_items = diagram_nav_items.dup
 
     Dir.glob("#{images_path}/*.png") do |pngfile|
       png_name = File.basename(pngfile)
       png_name_noext = File.basename(png_name, File.extname(png_name))
 
-      nav_item = diagram_nav_items.select { |item|
-        item['path'].start_with?(png_name_noext)
-      } [0].clone
-
-      png_dimensions = FastImage.size(pngfile)
-      data = spec_info.data.clone
-      data['image_path'] = "/#{spec_root}/images/#{png_name}"
-      data['image_width'] = png_dimensions[0]
-      data['image_height'] = png_dimensions[1]
+      nav_item = diagram_nav_items.select do |item|
+        item["path"].start_with?(png_name_noext)
+      end [0].clone
 
       if nav_item == nil
-        raise "Navigation item matching #{png_name} (#{spec_root}) was not found"
+        warn "UNUSED PNG: #{png_name} detected at source without " \
+             "a corresponding navigation item at (#{spec_root})."
+        next
       end
 
-      data = data.merge(nav_item)
+      not_found_items.delete_if { |item| item["title"] == nav_item["title"] }
+
+      data = build_spec_page_data(pngfile, spec_root, png_name, nav_item,
+                                  spec_info)
 
-      data['title'] = "#{spec_info['title']}: #{nav_item['title']}"
-      data['article_header_title'] = "#{nav_item['title']}"
+      pages << build_spec_page(site, spec_root, png_name_noext, data)
+    end
 
-      page = PngDiagramPage.new(
-        site,
-        site.source,
-        File.join(spec_root, png_name_noext),
-        data)
-      page.content = File.read(stub_path)
-      pages << page
+    not_found_items.each do |item|
+      title = item["title"]
+      warn "SPECIFIED PNG NOT FOUND: #{title}.png not found at source " \
+           "as specified at (#{spec_root})."
     end
 
-    return pages
+    pages
+  end
+
+  def build_spec_page(site, spec_root, png_name_noext, data)
+    page = PngDiagramPage.new(
+      site,
+      site.source,
+      File.join(spec_root, png_name_noext),
+      data,
+    )
+
+    stub_path = "#{File.dirname(__FILE__)}/png_diagram.html"
+    page.content = File.read(stub_path)
+
+    page
   end
 
+  def build_spec_page_data(pngfile, spec_root, png_name, nav_item, spec_info)
+    png_dimensions = FastImage.size(pngfile)
+    data = spec_info.data.clone
+    data["image_path"] = "/#{spec_root}/images/#{png_name}"
+    data["image_width"] = png_dimensions[0]
+    data["image_height"] = png_dimensions[1]
+
+    data = data.merge(nav_item)
+
+    data["title"] = "#{spec_info['title']}: #{nav_item['title']}"
+    data["article_header_title"] = nav_item["title"].to_s
+
+    data
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-open-project-helpers
 version: !ruby/object:Gem::Version
-  version: 2.1.4
+  version: 2.1.8
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-11-05 00:00:00.000000000 Z
+date: 2021-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -87,8 +87,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
+- ".rubocop.yml"
+- Gemfile
 - LICENSE.txt
 - README.md
+- Rakefile
 - develop/release
 - jekyll-theme-open-project-helpers.gemspec
 - lib/jekyll-theme-open-project-helpers.rb
@@ -119,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.0.3
 signing_key:
 specification_version: 4
 summary: Helpers for the Open Project Jekyll theme