origen_doc_helpers 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 494c09ae485338938797abd0324eb40bf5d668bb
-  data.tar.gz: 46e71f84f0db94e14db584d114a140b7305e4d75
+  metadata.gz: f10206613a76375cd6ec5925e33ea6a4928585a5
+  data.tar.gz: 713eef54df6cbaa62ce7b30b9bf63aba164b29c6
 SHA512:
-  metadata.gz: 374e1f62aa9eaeb2dc2bcf40f1670a12932ba395dc8ea1cdeb1624aaba00fee6badcc4a90ebf82e29ab387d6b64ac5b44b7c094d69da5bbda479a05d9c542fd8
-  data.tar.gz: bb32e4b3ba62b228285a7968a598afd5695440887a699361e555c1f0c8b923c92f655629301cebbf06d6e9ca459ebe04c67ff07321a97ad12611282cc447963f
+  metadata.gz: e64c3ceefca6c63d72b561a20c5ca6bfd776e4ed62e1c0f2447757f31dd8f80d73b6505ae26703a49e3192f75451d2428297e8e7b7e69b2c53d369b5dbe7efe2
+  data.tar.gz: 13036d3ddafdbed4126f94f752e6e9f667a62d351b6e56523047fce98ce918f9779953343db3e9a5456fe59e324584708f22fac1d25fe108bac672fe91ae24b5

data/bin/fix_my_workspace

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+$VERBOSE = nil  # Don't care about world writable dir warnings and the like
+
+if $_fix_my_workspace_version_check
+  $_fix_my_workspace_version = '0.7.0'
+else
+  if File.exist?(File.expand_path('../../lib/origen.rb', __FILE__))
+    # If this script is being run from within an origen-core workspace, use that Origen-core,
+    # not the system-installed origen-core version.
+    $LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+    require 'origen'
+  else
+    # Use system-installed Origen (the gem in system Ruby)
+    require 'origen'
+  end
+
+  if !Origen.site_config.gem_manage_bundler
+    puts 'Sorry but you have opted to manage Bundler yourself via your Origen site config, and this means'
+    puts 'that I cannot make certain assumptions about how your workspace is configured.'
+    puts 'You will need to either resolve this problem yourself, or else change the value of'
+    puts 'gem_mange_bundler to true.'
+    puts 'See here for more details on how to do that: http://origen-sdk.org/origen/guides/starting/company/'
+
+  else
+    ENV['BUNDLE_GEMFILE'] = File.join(Origen.root, 'Gemfile')
+    ENV['BUNDLE_PATH'] = File.expand_path(Origen.site_config.gem_install_dir)
+    ENV['BUNDLE_BIN'] = File.join(Origen.root, 'lbin')
+
+    # Force copy system gems to local gems
+    if Origen.site_config.gem_use_from_system
+      local_gem_dir = "#{ENV['BUNDLE_PATH']}/ruby/#{Pathname.new(Gem.dir).basename}"
+      gem_dir = Pathname.new(Gem.dir)
+
+      Origen.site_config.gem_use_from_system.each do |gem, version|
+        begin
+          # This will raise an error if the system doesn't have this gem installed, that
+          # will be rescued below
+          spec = Gem::Specification.find_by_name(gem, version)
+
+          local_dir = File.join(local_gem_dir, Pathname.new(spec.gem_dir).relative_path_from(gem_dir))
+          FileUtils.mkdir_p local_dir
+          FileUtils.cp_r("#{spec.gem_dir}/.", local_dir)
+
+          local_file = Pathname.new(File.join(local_gem_dir, Pathname.new(spec.cache_file).relative_path_from(gem_dir)))
+          FileUtils.mkdir_p local_file.dirname
+          FileUtils.cp(spec.cache_file, local_file)
+
+          if spec.extension_dir && File.exist?(spec.extension_dir)
+            local_dir = File.join(local_gem_dir, Pathname.new(spec.extension_dir).relative_path_from(gem_dir))
+            FileUtils.mkdir_p local_dir
+            FileUtils.cp_r("#{spec.extension_dir}/.", local_dir)
+          end
+
+          local_file = Pathname.new(File.join(local_gem_dir, Pathname.new(spec.spec_file).relative_path_from(gem_dir)))
+          FileUtils.mkdir_p local_file.dirname
+          FileUtils.cp(spec.spec_file, local_file)
+
+        rescue Gem::LoadError
+          # This just means that one of the gems that should be copied from the system
+          # was not actually installed in the system, so nothing we can do about that here
+        end
+      end
+    end
+
+    # Delete lbin
+    FileUtils.rm_rf(ENV['BUNDLE_BIN']) if File.exist?(ENV['BUNDLE_BIN'])
+
+    # Run bundler with correct switches
+    cmd = "bundle install --gemfile #{ENV['BUNDLE_GEMFILE']} --binstubs #{ENV['BUNDLE_BIN']} --path #{ENV['BUNDLE_PATH']}"
+    `chmod o-w #{Origen.root}` # Stops some annoying world writable warnings during install
+    `chmod o-w #{Origen.root}/bin` if File.exist?("#{Origen.root}/bin")
+    `chmod o-w #{Origen.root}/.bin` if File.exist?("#{Origen.root}/.bin")
+
+    # Try again, this time updating the bundle
+    if system(cmd)
+      fixed = true
+    elsif system 'bundle update'
+      fixed = true
+    end
+
+    if File.exist?(ENV['BUNDLE_BIN'])
+      `chmod o-w #{ENV['BUNDLE_BIN']}`
+
+      # Make .bat versions of all executables, Bundler should really be doing this when running
+      # on windows
+      if Origen.os.windows?
+        Dir.glob("#{ENV['BUNDLE_BIN']}/*").each do |bin|
+          unless bin =~ /.bat$/
+            bat = "#{bin}.bat"
+            unless File.exist?(bat)
+              File.open(bat, 'w') { |f| f.write('@"ruby.exe" "%~dpn0" %*') }
+            end
+          end
+        end
+      end
+    end
+
+    system 'origen -v' if fixed
+  end
+end

data/config/commands.rb

@@ -20,14 +20,14 @@ aliases ={
 # Now branch to the specific task code
 case @command
 
-# Here is an example of how to implement a command, the logic can go straight
-# in here or you can require an external file if preferred.
-when "execute"
-  puts "Executing something..."
-  require "commands/execute"    # Would load file lib/commands/execute.rb
-  # You must always exit upon successfully capturing a command to prevent 
-  # control flowing back to Origen
-  exit 0
+## Example of how to make a command to run unit tests, this simply invokes RSpec on
+## the spec directory
+when "specs"
+  ARGV.unshift "spec"
+  require "rspec"
+  require "rspec/autorun"
+  exit 0 # This will never be hit on a fail, RSpec will automatically exit 1
+
 
 # Always leave an else clause to allow control to fall back through to the
 # Origen command handler.
@@ -35,8 +35,8 @@ when "execute"
 # origen -h, you can do this be assigning the required text to @application_commands
 # before handing control back to Origen. Un-comment the example below to get started.
 else
-#  @application_commands = <<-EOT
-# execute      Execute something I guess
-#  EOT
+  @application_commands = <<-EOT
+  specs        Run the specs (tests), -c will enable coverage
+EOT
 
 end 

data/config/version.rb

@@ -1,7 +1,7 @@
 module OrigenDocHelpers
   MAJOR = 0
-  MINOR = 6
-  BUGFIX = 2
+  MINOR = 7
+  BUGFIX = 0
   DEV = nil
 
   VERSION = [MAJOR, MINOR, BUGFIX].join(".") + (DEV ? ".pre#{DEV}" : '')

data/lib/origen_doc_helpers.rb

@@ -7,6 +7,7 @@ module OrigenDocHelpers
   autoload :ListFlowFormatter, 'origen_doc_helpers/list_flow_formatter'
   autoload :FlowPageGenerator, 'origen_doc_helpers/flow_page_generator'
   autoload :ModelPageGenerator, 'origen_doc_helpers/model_page_generator'
+  autoload :GuideIndex, 'origen_doc_helpers/guide_index'
 end
 
 require 'origen_doc_helpers/helpers'

data/lib/origen_doc_helpers/guide_index.rb

@@ -0,0 +1,162 @@
+module OrigenDocHelpers
+  # Provides an API to programatically construct an index hash as used
+  # by the Searchable Documents helper -
+  # http://origen-sdk.org/doc_helpers/helpers/searchable/intro/#The_Document_Index
+  class GuideIndex
+    def initialize
+      @index = {}
+      @section_keys = {}
+      @pending_sections = []
+      @pending_pages = []
+    end
+
+    def section(id, options = {}, &block)
+      @current_section_id = id
+      if options[:heading]
+        # This is to handle the corner case where an id reference was originally supplied
+        # without the heading, then a later reference added the heading
+        if @section_keys[id]
+          if @section_keys[id] != options[:heading]
+            change_key(:@index, @section_keys[id], options[:heading])
+            @section_keys[id] = options[:heading]
+          end
+        else
+          @section_keys[id] = options[:heading]
+        end
+      else
+        @section_keys[id] ||= id
+      end
+      @section_keys[id] ||= @section_keys[id].to_s if @section_keys[id]
+      section_pending = false
+      unless @index[section_key]
+        if options[:after]
+          if has_key?(:@index, section_key(options[:after]))
+            insert_after(:@index, section_key, section_key(options[:after]), {})
+          else
+            @pending_sections << [id, options.dup, block] unless @no_pending
+            section_pending = true
+          end
+        elsif options[:before]
+          if has_key?(:@index, section_key(options[:before]))
+            insert_before(:@index, section_key, section_key(options[:before]), {})
+          else
+            @pending_sections << [id, options.dup, block] unless @no_pending
+            section_pending = true
+          end
+        else
+          @index[section_key] = {}
+        end
+      end
+      @current_section = @index[section_key]
+      yield self unless section_pending
+      @current_section = nil
+
+      # See if any pending sections can now be inserted
+      unless @no_pending
+        @pending_sections.each do |id, opts, blk|
+          @no_pending = true
+          section(id, opts, &blk)
+          @no_pending = false
+        end
+      end
+      self
+    end
+
+    def page(id, options = {})
+      unless @current_section
+        fail 'page can only be called from within a section block!'
+      end
+      @current_topic_id = id
+      value = options[:heading] || id
+      value = value.to_s if value
+      page_pending = false
+      if options[:after]
+        if has_key?(:@current_section, topic_key(options[:after]))
+          insert_after(:@current_section, topic_key, topic_key(options[:after]), value)
+        else
+          @pending_pages << [id, options.dup] unless @no_page_pending
+          page_pending = true
+        end
+      elsif options[:before]
+        if has_key?(:@current_section, topic_key(options[:before]))
+          insert_before(:@current_section, topic_key, topic_key(options[:before]), value)
+        else
+          @pending_pages << [id, options.dup] unless @no_page_pending
+          page_pending = true
+        end
+      else
+        @current_section[topic_key] = value
+      end
+      # Update the parent reference, required if before or after was used to create a new
+      # @current_section hash
+      @index[section_key] = @current_section unless page_pending
+
+      # See if any pending pages can now be inserted
+      unless @no_page_pending
+        @pending_pages.each do |id, opts|
+          @no_page_pending = true
+          page(id, opts)
+          @no_page_pending = false
+        end
+      end
+
+      self
+    end
+
+    def to_h
+      @index
+    end
+
+    private
+
+    def section_key(id = nil)
+      @section_keys[id || @current_section_id]
+    end
+
+    def topic_key(id = nil)
+      if @current_section_id
+        "#{@current_section_id}_#{id || @current_topic_id}".to_sym
+      else
+        "#{id || @current_topic_id}".to_sym
+      end
+    end
+
+    def has_key?(var, id)
+      instance_variable_get(var).key?(id)
+    end
+
+    def change_key(var, existing, new)
+      h = {}
+      instance_variable_get(var).each do |key, val|
+        if key == existing
+          h[new] = val
+        else
+          h[key] = val
+        end
+      end
+      instance_variable_set(var, h)
+    end
+
+    def insert_after(var, id, after, value)
+      new = {}
+      instance_variable_get(var).each do |key, val|
+        new[key] = val
+        if key == after
+          new[id] = value
+        end
+      end
+      instance_variable_set(var, new)
+    end
+
+    def insert_before(var, id, before, value)
+      new = {}
+      instance_variable_get(var).each do |key, val|
+        if key == before
+          new[id] = value
+        end
+        new[key] = val
+      end
+      instance_variable_set(var, new)
+    end
+  end
+end

data/lib/origen_doc_helpers/helpers.rb

@@ -273,6 +273,13 @@ END
               options[:tab]
             else
               rel = options[:top_level_file].relative_path_from(_doc_root_dir(options)).sub_ext('').sub_ext('').to_s
+              # If the file lives outside of the current app (e.g. it comes from a plugin), then the above approach
+              # doesn't work, so let's just take the last dirname and the filename
+              if rel =~ /\.\./
+                dir = options[:top_level_file].dirname.basename
+                file = options[:top_level_file].basename('.*').basename('.*')  # twice to allow for my_file.md.erb
+                rel = "#{dir}_#{file}"
+              end
               rel.gsub(/(\/|\\)/, '_').downcase.to_sym
             end
           end

data/templates/shared/_searchable.html.erb

@@ -1,6 +1,7 @@
 % options[:root] ||= "docs"
 % options[:path_separator] ||= "_"
 % pdf_filename = ::OrigenDocHelpers::PDF.register(options)
+% options[:index] = options[:index].to_h
 
 <div class="row">
   <div class="col-md-3 sidebar-nav-container">

data/templates/web/helpers/searchable/intro.md.erb

@@ -43,6 +43,51 @@ index["Topic 1"] = {
 }
 ~~~
 
+#### Guide Index API
+
+An API is available to programatically define the document index, here is the first example above defined
+via the API rather than creating the hash explicitly:
+
+~~~ruby
+index = OrigenDocHelpers::GuideIndex.new
+index.section nil do |section|
+  section.page :intro, heading: "Introduction"
+  section.page :page2, heading: "Page 2"
+  end
+index.section :topic1, heading: "Topic 1" do |section|
+  section.page :item1, heading: "First Item"
+  section.page :item2, heading: "Second Item"
+end
+~~~
+
+
+On the face of it, this is just a slightly different way of writing the same thing and you may or may not prefer
+using the API vs. defining the hash directly.
+
+However, the advantage of the API is that it allows the index to be defined out of order, allowing the user
+to insert entries at specific points in the index table. This can be useful to allow plugins to add pages to
+a parent application's guide section.
+
+This is achieved by adding `:before` and `:after` options, here for example to add a new section before "Topic 1":
+
+~~~ruby
+index.section :topic0, heading: "Topic 0", before: :topic1 do |section|
+  section.page :my_topic
+end
+~~~
+
+or to add a new page within the "Topic 1" section:
+
+~~~ruby
+index.section :topic1 do |section|
+  section.page :my_topic, heading: "My Heading", after: :item1
+end
+~~~
+
+Note that both the `.section` and `.page` methods support the use of `:before` or `:after`.
+
+If neither option is given when referencing an existing `GuideIndex` instance then the new section/page
+will simply be appended onto the end.
 
 ### The Layout Helper
 

data/templates/web/layouts/_doc.html.erb

@@ -6,17 +6,17 @@ analytics: UA-64455560-1
 
 %# Add/edit sections here, the code below will expand this with the correct markup, 
 %# pass in the topic you want selected via the :tab option.
-% s = {}
-% s[nil] = {
-%   :intro => "Introduction",
-%   :page2 => "Page 2",
-% }
-% s["Topic 1"] = {
-%   :topic1_item1 => "First Item",
-%   :topic1_item2 => "Second Item",
-% }
+% i = OrigenDocHelpers::GuideIndex.new
+% i.section nil do |section|
+%   section.page :intro, heading: "Introduction"
+%   section.page :page2, heading: "Page 2"
+% end
+% i.section :topic1, heading: "Topic 1" do |section|
+%   section.page :item1, heading: "First Item"
+%   section.page :item2, heading: "Second Item"
+% end
 
-% render "templates/shared/searchable.html", options.merge(:index => s, :root => "helpers/searchable") do
+% render "templates/shared/searchable.html", options.merge(:index => i, :root => "helpers/searchable") do
 
 <%= yield %>    
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: origen_doc_helpers
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Stephen McGinty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-18 00:00:00.000000000 Z
+date: 2018-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: origen
@@ -24,20 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.7.15
-- !ruby/object:Gem::Dependency
-  name: origen_testers
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: 
 email:
 - stephen.f.mcginty@gmail.com
@@ -45,6 +31,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- bin/fix_my_workspace
 - config/application.rb
 - config/boot.rb
 - config/commands.rb
@@ -52,6 +39,7 @@ files:
 - config/version.rb
 - lib/origen_doc_helpers.rb
 - lib/origen_doc_helpers/flow_page_generator.rb
+- lib/origen_doc_helpers/guide_index.rb
 - lib/origen_doc_helpers/helpers.rb
 - lib/origen_doc_helpers/html_flow_formatter.rb
 - lib/origen_doc_helpers/list_flow_formatter.rb
@@ -109,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.8.11
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.7
+rubygems_version: 2.6.14.1
 signing_key: 
 specification_version: 4
 summary: Snippets and helpers for creating Origen web documents