origen_doc_helpers 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ee3e3f947570dd8db7cd7eeca0321269b048e832
-  data.tar.gz: 3674401952587d0d7a14421b205935b6dcafc44b
+  metadata.gz: 25148e1c8c40efe62a9f793aa7df9281ce5b7e07
+  data.tar.gz: 4318d42ec7a1aaae0007e8dd37adcec8f1eaa5a5
 SHA512:
-  metadata.gz: 2999b9c681e79d2625cb9c4f2c1eccda196573d7a68357d29adad24a25a34cd4d577541d26bef76932ab6d9b4e4ee46f38112973f480cc745b1690e88acd92ee
-  data.tar.gz: bb1b457ffa445709a35f91a05f8d0181c4cab356cbde177dfb803193ec2e5c8dac87ef8b51281be56fbdb4a4dccd11207ca65434e20085f1977f8f12a8f4de74
+  metadata.gz: 526bcb1a4d23c2662ec7b037bae220e6387739e135f8a90a6188ba0e36a387003f1767c825c5e591fe70b43ea0cf03170760de195f089758b3422d734c4bf559
+  data.tar.gz: fd4d0f42ffddda0e4eb8a17d6c69b4b080dea33cdffdf740bf2644405ae97e8c235e2589e8bae90842dfb9d623674ff9e2af70c9363399abb6c054532b989623

data/config/boot.rb

@@ -0,0 +1,19 @@
+# This file is used to boot your plugin when it is running in standalone mode
+# from its own workspace - i.e. when the plugin is being developed.
+#
+# It will not be loaded when the plugin is imported by a 3rd party app - in that
+# case only lib/origen_doc_helpers.rb is loaded.
+#
+# Therefore this file can be used to load anything extra that you need to boot
+# the development environment for this app. For example this is typically used
+# to load some additional test classes to use your plugin APIs so that they can
+# be tested and/or interacted with in the console.
+require "origen_doc_helpers"
+
+# Load a Top-level/DUT class that is defined within this plugin's lib directory
+# and is required by some of our tests.
+# Normally such a class should not be exposed to 3rd party users of the plugin,
+# so we required it here rather than in lib/origen_doc_helpers.rb.
+module OrigenDocHelpers
+  autoload :DUT, "origen_doc_helpers/dut"
+end

data/config/version.rb

@@ -1,6 +1,6 @@
 module OrigenDocHelpers
   MAJOR = 0
-  MINOR = 3
+  MINOR = 4
   BUGFIX = 0
   DEV = nil
 

data/lib/origen_doc_helpers.rb

@@ -1,2 +1,22 @@
+require 'origen'
 require_relative '../config/application.rb'
-require_relative '../config/environment.rb'
+
+module OrigenDocHelpers
+  autoload :PDF, 'origen_doc_helpers/pdf'
+  autoload :HtmlFlowFormatter, 'origen_doc_helpers/html_flow_formatter'
+  autoload :ListFlowFormatter, 'origen_doc_helpers/list_flow_formatter'
+  autoload :FlowPageGenerator, 'origen_doc_helpers/flow_page_generator'
+  autoload :ModelPageGenerator, 'origen_doc_helpers/model_page_generator'
+end
+
+require 'origen_doc_helpers/helpers'
+
+module OrigenDocHelpers
+  def self.generate_flow_docs(options = {}, &block)
+    FlowPageGenerator.run(options, &block)
+  end
+
+  def self.generate_model_docs(options = {}, &block)
+    ModelPageGenerator.run(options, &block)
+  end
+end

data/lib/origen_doc_helpers/flow_page_generator.rb

@@ -0,0 +1,110 @@
+module OrigenDocHelpers
+  class FlowPageGenerator
+    class << self
+      attr_accessor :layout_options
+      attr_accessor :layout
+      attr_reader :pages
+
+      def run(options)
+        @pages = {}
+        unless options[:layout]
+          fail 'You must pass a :layout option providing an absolute path to the layout file to be used'
+        end
+        unless File.exist?(options[:layout].to_s)
+          fail "This layout file does not exist: #{options[:layout]}"
+        end
+        self.layout = options.delete(:layout)
+        self.layout_options = options
+        yield self
+        write_index unless @pages.size == 0
+        @pages = nil
+      end
+
+      def page(options)
+        if !options[:name] || !(options[:flow] || options[:flows]) ||
+           !options[:target]
+          fail 'The following options are required: :name, :flow(s), :target'
+        end
+        p = new(options)
+        pages[options[:group]] ||= []
+        pages[options[:group]] << p
+        p.run
+      end
+
+      def write_index
+        f = "#{Origen.root}/web/content/flows.md"
+        Origen.log.info "Building flow index page: #{f}"
+        t = Origen.compile index_page_template,
+                           layout:         layout,
+                           layout_options: layout_options,
+                           no_group_pages: pages.delete(nil),
+                           pages:          pages
+
+        File.write(f, t)
+      end
+
+      def index_page_template
+        @index_page_template ||= "#{Origen.root!}/templates/flow_index.md.erb"
+      end
+    end
+
+    def initialize(options)
+      @options = options
+    end
+
+    def run
+      Origen.log.info "Building flow page: #{output_file}"
+      t = Origen.compile flow_page_template,
+                         layout:         self.class.layout,
+                         layout_options: self.class.layout_options,
+                         flow_template:  flow_template,
+                         heading:        heading,
+                         target:         @options[:target],
+                         flows:          [@options[:flows] || @options[:flow]].flatten,
+                         context:        @options[:context] || {}
+      File.write(output_file, t)
+    end
+
+    def name
+      @options[:name]
+    end
+
+    def heading
+      if @options[:group]
+        @options[:group] + ': ' + @options[:name]
+      else
+        @options[:name]
+      end
+    end
+
+    def output_file
+      f = @options[:name].to_s.symbolize
+      "#{output_dir}/#{f}.md"
+    end
+
+    def output_path
+      p = 'flows'
+      if @options[:group]
+        p += ('/' + @options[:group].to_s.symbolize.to_s)
+      end
+      p + '/' + @options[:name].to_s.symbolize.to_s
+    end
+
+    def output_dir
+      d = "#{Origen.root}/web/content/flows"
+      if @options[:group]
+        d += ('/' + @options[:group].to_s.symbolize.to_s)
+      end
+      FileUtils.mkdir_p(d) unless File.exist?(d)
+      d
+    end
+
+    def flow_page_template
+      @flow_page_template ||= "#{Origen.root!}/templates/flow_page.md.erb"
+    end
+
+    def flow_template
+      @flow_template ||= "#{Origen.root!}/templates/shared/test/_flow.md.erb"
+    end
+  end
+end

data/lib/origen_doc_helpers/model_page_generator.rb

@@ -0,0 +1,151 @@
+module OrigenDocHelpers
+  class ModelPageGenerator
+    class << self
+      attr_accessor :layout_options
+      attr_accessor :layout
+      attr_reader :pages
+
+      def run(options)
+        @pages = {}
+        unless options[:layout]
+          fail 'You must pass a :layout option providing an absolute path to the layout file to be used'
+        end
+        unless File.exist?(options[:layout].to_s)
+          fail "This layout file does not exist: #{options[:layout]}"
+        end
+        self.layout = options.delete(:layout)
+        self.layout_options = options
+        yield self
+        write_index unless @pages.size == 0
+        @pages = nil
+      end
+
+      def page(options)
+        unless options[:model]
+          fail 'The following options are required: :model'
+        end
+        p = new(options)
+        pages[options[:group]] ||= []
+        pages[options[:group]] << p
+        p.run
+      end
+
+      def write_index
+        f = "#{Origen.root}/web/content/models.md"
+        Origen.log.info "Building models index page: #{f}"
+        t = Origen.compile index_page_template,
+                           layout:         layout,
+                           layout_options: layout_options,
+                           no_group_pages: pages.delete(nil),
+                           pages:          pages
+
+        File.write(f, t)
+      end
+
+      def index_page_template
+        @index_page_template ||= "#{Origen.root!}/templates/model_index.md.erb"
+      end
+    end
+
+    attr_reader :model
+
+    def initialize(options)
+      @options = options
+      @model = options[:model]
+    end
+
+    def run
+      create_page(@model, top: true, breadcrumbs: [['Top', output_path]], path: output_path, origen_path: '')
+    end
+
+    def create_page(model, options = {})
+      output_file = "#{Origen.root}/web/content/#{options[:path]}.md"
+
+      Origen.log.info "Building model page: #{output_file}"
+      t = Origen.compile model_page_template,
+                         layout:         self.class.layout,
+                         layout_options: self.class.layout_options,
+                         heading:        heading,
+                         search_id:      search_id,
+                         model:          model,
+                         breadcrumbs:    options[:breadcrumbs],
+                         path:           options[:path],
+                         origen_path:    options[:origen_path]
+
+      write_out(output_file, t)
+
+      model.sub_blocks.each do |name, block|
+        path = options[:path] + "/#{name}"
+        if options[:origen_path].empty?
+          origen_path = name.to_s
+        else
+          origen_path = options[:origen_path] + ".#{name}"
+        end
+        create_page block,
+                    breadcrumbs: options[:breadcrumbs] + [[name, path]],
+                    path:        path,
+                    origen_path: origen_path
+      end
+    end
+
+    def write_out(file, content)
+      d = Pathname.new(file).dirname.to_s
+      FileUtils.mkdir_p(d) unless File.exist?(d)
+
+      yaml = ''
+      # Remove any frontmatter inherited from the caller's layout, this is being done via disk for
+      # large files due to previous issues with sub'ing on large files that contain many registers
+      File.open(file, 'w') do |f|
+        frontmatter_done = false
+        frontmatter_open = false
+        content.each_line do |line|
+          if frontmatter_done
+            f.puts line
+          elsif frontmatter_open
+            if line =~ /^\s*---\s*$/
+              frontmatter_done = true
+            else
+              yaml += line
+            end
+          else
+            if line =~ /^\s*---\s*$/
+              frontmatter_open = true
+            elsif !line.strip.empty?
+              frontmatter_done = true
+            end
+          end
+        end
+      end
+
+      # Write out an attribute file containing the search ID to pass it to nanoc
+      yaml += "search_id: model_#{id}"
+      File.write(file.sub(/\.[^\.]*$/, '.yaml'), yaml)
+    end
+
+    # Returns a Pathname to a uniquely named temporary file
+    def temporary_file
+      # Ensure this is unique so that is doesn't clash with parallel compile processes
+      Pathname.new "#{Origen.root}/tmp/model_#{id}_compiler_#{Process.pid}_#{Time.now.to_f}"
+    end
+
+    def search_id
+      "model_#{id}"
+    end
+
+    def id
+      @id ||= model.class.to_s.symbolize.to_s.gsub('::', '_')
+    end
+
+    def heading
+      model.class.to_s
+    end
+
+    def output_path
+      "models/#{id}"
+    end
+
+    def model_page_template
+      @model_page_template ||= "#{Origen.root!}/templates/model_page.md.erb"
+    end
+  end
+end

data/templates/flow_index.md.erb

@@ -0,0 +1,19 @@
+% opts = options
+% render options[:layout], options[:layout_options] do
+
+# Test Program Flows
+
+% (opts[:no_group_pages] || []).each do |page|
+* [<%= page.name %>](<%= path page.output_path %>)
+% end
+
+% (opts[:pages] || {}).each do |group, pages|
+### <%= group %>
+
+%   pages.each do |page|
+* [<%= page.name %>](<%= path page.output_path %>)
+%   end
+
+% end
+
+% end

data/templates/flow_page.md.erb

@@ -0,0 +1,4 @@
+% opts = options
+% render options[:layout], options[:layout_options] do
+<%= render opts[:flow_template], heading: opts[:heading], target: opts[:target], flow: opts[:flows], context: opts[:context] %>
+% end

data/templates/model_index.md.erb

@@ -0,0 +1,24 @@
+% opts = options
+% render options[:layout], options[:layout_options] do
+
+<div class="row" style="margin-top: 10px; margin-bottom: 15px;">
+  <div class="col-md-9">
+    <img src="http://origen-sdk.org/img/origen-device.png" style="float: left; height:50px; width: 50px; margin-top: 14px;">
+    <h1 style="float: left; margin-left: 10px;">Models</h1>
+  </div>
+</div>
+
+% (opts[:no_group_pages] || []).each do |page|
+* [<%= page.heading %>](<%= path page.output_path %>)
+% end
+
+% (opts[:pages] || {}).each do |group, pages|
+### <%= group %>
+
+%   pages.each do |page|
+* [<%= page.heading %>](<%= path page.output_path %>)
+%   end
+
+% end
+
+% end

data/templates/model_page.md.erb

@@ -0,0 +1,125 @@
+% opts = options
+% model = options[:model]
+% render options[:layout], options[:layout_options] do
+
+<script type="text/javascript">
+  // Modified from: http://jsfiddle.net/jhfrench/mc4Qd/
+  window.onload = function() {
+    // Links to the top of the page
+    $('.top-link').click(function() {
+      jQuery('html,body').animate({scrollTop: 0}, 500);
+      return false;
+    });
+  };
+</script>
+
+<style>
+  tr.clickable td { padding: 0px !important; }
+  tr.clickable a { display: block; height: 100%; width: 100%; padding: 8px; text-decoration: none; }
+</style>
+
+<div class="row" style="margin-top: 10px; margin-bottom: 15px;">
+  <div class="col-md-9">
+    <img src="http://origen-sdk.org/img/origen-device.png" style="float: left; height:50px; width: 50px; margin-top: 14px;">
+    <h1 style="float: left; margin-left: 10px;"><%= opts[:heading] %></h1>
+  </div>
+  <div id="search" class="col-md-3" style="margin-top: 20px;">
+    <form style="margin-bottom: 15px;">
+      <div class="input-group">
+        <input class="form-control" type="search" placeholder="Search within this model..."/>
+        <span class="input-group-btn">
+          <button type="submit" class="btn btn-search">GO!</button>
+        </span>
+      </div>
+    </form>
+  </div>
+</div>
+
+<div class="row">
+  <div class="col-md-12">
+    <ol class="breadcrumb">
+%   size = opts[:breadcrumbs].size      
+%   opts[:breadcrumbs].each_with_index do |crumb, i|
+%     if i == size - 1
+      <li class="active"><%= crumb[0] %></li>
+%     else
+      <li><a href="<%= path crumb[1] %>"><%= crumb[0] %></a></li>
+%     end
+%   end      
+    </ol>
+  </div>
+</div>
+
+<div class="row">
+  <div class="col-md-12 search-results">
+  </div>
+</div>
+
+<div class="row">
+  <div class="col-md-6">
+    <h3>Blocks</h3>
+
+    <table class="table table-hover">
+      <thead><tr>
+        <th>Address</th>
+        <th>Name</th>
+      </tr></thead>
+      <tbody>
+%   model.sub_blocks.sort_by { |name, block| block.base_address }.each do |name, block|
+        <tr class="clickable"> 
+          <td><a href="<%= path "#{opts[:path]}/#{name}" %>"><%= block.base_address.to_hex %></a></td>
+          <td><a href="<%= path "#{opts[:path]}/#{name}" %>"><%= name %></a></td>
+        </tr> 
+%   end
+      </tbody>
+    </table>
+  </div>
+
+  <div class="col-md-6">
+    <h3>Registers</h3>
+
+    <table class="table table-hover">
+      <thead><tr>
+        <th>Address</th>
+        <th>Name</th>
+      </tr></thead>
+      <tbody>
+%   model.regs.sort_by { |name, reg| reg.offset }.each do |name, reg|
+        <tr class="clickable"> 
+          <td><a href="#<%= reg.name %>"><%= reg.address.to_hex %></a></td>
+          <td><a href="#<%= reg.name %>"><%= name %></a></td>
+        </tr> 
+%   end
+      </tbody>
+    </table>
+  </div>
+</div>
+
+
+%   if model.owns_registers?
+
+<hr>
+<div class="row">
+  <div class="col-md-12">
+    <article>
+    <h3>Registers of <%= model.model.class%> <%= model.name ? "(#{model.name})" : model.try(:includes_origen_top_level?) ? "(dut)" : "" %></h3>
+
+%     model.regs.sort_by { |name, reg| reg.offset }.each do |name, reg|
+
+    <div>
+      <span class="pull-right"><a class="top-link" href="#">back to top</a></span>
+    </div>
+
+<%= render "doc_helpers/register.html", reg: reg, preserve_target: true, descriptions: true, origen_path: opts[:origen_path] %>
+
+%     end
+
+    </article>
+  </div>
+</div>
+
+%   end
+
+% end
+<script>window.origen_search_id = "<%= opts[:search_id] %>";</script>
+<script src="<%= path "search.js" %>"></script>