origen_doc_helpers 0.3.0 → 0.4.0

data/templates/shared/_register.html.erb

@@ -5,10 +5,16 @@
 <a class="anchor" name="<%= "#{reg.name}" %>"></a>
 
 <a href='#<%= reg.name %>'>
+% if options[:origen_path] && !options[:origen_path].empty?
+%   reg_path = options[:origen_path] + "." + reg.name.to_s
+%   reg_path = "#{reg.name} - #{reg_path}"
+% else
+%   reg_path = reg.name
+% end
 % if reg.full_name
-<h4>0x<%= reg.address.to_s(16).upcase %> - <%= reg.full_name %> (<%= reg.name %>)</h4>
+<h4>0x<%= reg.address.to_s(16).upcase %> - <%= reg.full_name %> (<%= reg_path %>)</h4>
 % else
-<h4>0x<%= reg.address.to_s(16).upcase %> - <%= reg.name %></h4>
+<h4>0x<%= reg.address.to_s(16).upcase %> - <%= reg_path %></h4>
 % end
 </a>
 
@@ -22,10 +28,11 @@
 </div>
 % end
 
-% (reg.size / 8).times do |byte_index|
+% num_bytes = (reg.size / 8.0).ceil
+% num_bytes.times do |byte_index|
 %   # Need to add support for little endian regs here?
-%   byte_number = (reg.size / 8) - byte_index
-%   max_bit = reg.size - (byte_index * 8) - 1
+%   byte_number = num_bytes - byte_index
+%   max_bit = (byte_number * 8) - 1
 %   min_bit = max_bit - 8 + 1
 
 <table class="reg table table-condensed" style="margin-bottom: 0; table-layout: fixed;">
@@ -33,7 +40,12 @@
     <tr class="bit-positions">
       <th class="spacer"></th>
 % 8.times do |i|
-      <th class="bit-position"><%= reg.size - i - 1 - (byte_index * 8) %></th>
+%   bit_num = (byte_number * 8) - i - 1
+%   if bit_num > reg.size - 1
+      <th class="spacer"></th>
+%   else
+      <th class="bit-position"><%= bit_num %></th>
+%   end
 % end
     </tr>
   </thead>
@@ -46,12 +58,21 @@
       <td class="heading">R</td>
 % reg.named_bits :include_spacers => true do |name, bit|
 %  if _bit_in_range?(bit, max_bit, min_bit)
+%   if max_bit > (reg.size - 1)
+%     (max_bit - (reg.size - 1)).times do
+      <td class="spacer"></td>
+%     end
+%   end
 %   if bit.size > 1
 %     if name
 %       if bit.readable?
 %         bit_name = "#{name}[#{bit.size - 1}:0]"
       <td class="<%= _bit_rw(bit) %>" colspan="<%= _num_bits_in_range(bit, max_bit, min_bit) %>">
+% if options[:descriptions] && !bit.description.empty?
+         <span><a href="#<%= "#{reg.name}_#{name}_#{bit.position}" %>"><%= bit_name %></a></span>
+% else
          <span><%= bit_name %></span>
+% end
       </td>
 %       else
 %         if bit.access == :worz
@@ -72,7 +93,11 @@
 %   else
 %     if name
 %       if bit.readable?
+%         if options[:descriptions] && !bit.description.empty?
+      <td class="<%= _bit_rw(bit) %>"><span><a href="#<%= "#{reg.name}_#{name}_#{bit.position}" %>"><%= name %></a></span></td>
+%         else
       <td class="<%= _bit_rw(bit) %>"><span><%= name %></span></td>
+%         end
 %       else
       <td class="<%= _bit_rw(bit) %>"></td>
 %       end
@@ -91,12 +116,21 @@
       <td class="heading">W</td>
 % reg.named_bits :include_spacers => true do |name, bit|
 %  if _bit_in_range?(bit, max_bit, min_bit)
+%   if max_bit > (reg.size - 1)
+%     (max_bit - (reg.size - 1)).times do
+      <td class="spacer"></td>
+%     end
+%   end
 %   if bit.size > 1
 %     if name
 %       if !bit.readable?
 %         bit_name = "#{name}[#{bit.size - 1}:0]"
       <td class="<%= _bit_rw(bit) %>" colspan="<%= _num_bits_in_range(bit, max_bit, min_bit) %>">
+% if options[:descriptions] && !bit.description.empty?
+         <span><a href="#<%= "#{reg.name}_#{name}_#{bit.position}" %>"><%= bit_name %></a></span>
+% else
          <span><%= bit_name %></span>
+% end
       </td>
 %       else
       <td class="<%= _bit_rw(bit) %>" colspan="<%= _num_bits_in_range(bit, max_bit, min_bit) %>"></td>
@@ -111,7 +145,11 @@
 %   else
 %     if name
 %       if !bit.readable?
+%         if options[:descriptions] && !bit.description.empty?
+      <td class="<%= _bit_rw(bit) %>"><span><a href="#<%= "#{reg.name}_#{name}_#{bit.position}" %>"><%= name %></a></span></td>
+%         else
       <td class="<%= _bit_rw(bit) %>"><span><%= name %></span></td>
+%         end
 %       else
       <td class="<%= _bit_rw(bit) %>"></td>
 %       end
@@ -130,6 +168,11 @@
       <td class="heading">Reset</td>
 % reg.named_bits :include_spacers => true do |name, bit|
 %  if _bit_in_range?(bit, max_bit, min_bit)
+%   if max_bit > (reg.size - 1)
+%     (max_bit - (reg.size - 1)).times do
+      <td class="spacer"></td>
+%     end
+%   end
 %   if bit.size > 1
 %     if name
 %       if bit.nvm_dep != 0 || bit.reset_val == :memory
@@ -164,7 +207,7 @@
 
 % end # Byte index loop
 
-% if options[:descriptions]
+% if options[:descriptions] && reg.named_bits.any? { |name, bits| !bits.description.empty? }
 <table class="bit-descriptions table table-condensed table-bordered" style="margin: 20px 0 0 0">
   <thead>
     <tr>
@@ -177,6 +220,7 @@
     <tr>
       <td>
         <p>
+          <a class="anchor" name="<%= "#{reg.name}_#{name}_#{bits.position}" %>"></a>
 % if bits.size == 1        
           <%= bits.position %>
 % else

data/templates/shared/_searchable.html.erb

@@ -59,7 +59,7 @@
 %# The markdown attribute is important if you are going to include content written
 %# in markdown, without this is will be included verbatim
   <div class="col-md-9 nav-page-container" markdown="1">
-  <article markdown="1">  
+  <article markdown="1" class="search-results">  
 
 % found = options[:index].find{ |k,v| v.has_key?(_resolve_tab(options)) }
 % topic_key = found ? found[0] : nil

data/templates/shared/test/_flow.md.erb

@@ -4,9 +4,8 @@
 % flows = options[:flow] || options[:flows] 
 % flows = flows ? [flows].flatten : nil
 
-% if !program
-%   Origen.target.temporary = options[:target]
-%   program =  OrigenTesters.program
+% Origen.target.temporary = options[:target]
+% program =  OrigenTesters.program
 
 <style>
   .clickable { cursor: pointer }
@@ -19,6 +18,7 @@
   .test-overview .panel-group { margin-bottom: 0; }
   h4 .test-number { font-size: 14px; }
   table tr th { text-align: left !important; }
+  .test-overview:last-child { border-bottom: none; }
 </style>
 
 <script type="text/javascript">
@@ -186,230 +186,3 @@
     </div>
   </div>
 </div>
-
-% # Legacy output based on Doc tester, abandon hope all ye who enter here...
-% else
-
-<div class="row">
-%# The markdown attribute is important if you are going to include content written
-%# in markdown, without this is will be included verbatim
-%# One downside is that html cannot be indented here, otherwise it will be parsed
-%# as a code block.
-<div class="col-md-12" markdown="1">
-<div class="panel-group" id="test_flow">  
-
-<a href="#_" class="expandcollapse btn btn-xs pull-right btn-default" state="0"><i class='fa fa-plus'></i></a>
-
-<h2><%= options[:heading] %> <span style="font-size: 14px">(generated for target '<%= program.target %>')</span></h2>
-
-% program.each_in_flow(flows, :context => options[:context]) do |t|
-%   type = t[:type]
-%   instances = t[:instance]
-%   i = instances
-%   flow = t[:flow]
-%   f = flow
-%   context = t[:context]
-%   c = context
-%   description = t[:description]
-
-%   if type == :label || type == :branch
-%     # Need to decide how to deal with label based jumps
-
-%   elsif type == :section_start
-
-<%= _stop_test_flow_table %>
-<%= _start_accordion(description.first) %>
-
-%     description.each_with_index do |line, ix|
-%       unless ix == 0
-<%= line %>
-%       end
-%     end
-
-%   elsif type == :section_stop
-
-<%= _stop_test_flow_table %>
-<%= _stop_accordion %>
-
-%   else
-
-%     unless flow[:name] == "power_cycle_ti"
-<%= _start_test_flow_table %>
-
-<tr>
-<td class="col1">
-<a class="anchor" name="<%= "#{_test_name(t)}_#{_test_number(t)}" %>"></a>
-<div><%= _test_to_local_link(t) %></div>  
-
-% if f[:id]
-% dependents = program.dependents_of(f[:id], flows, :context => options[:context])
-%   unless dependents.empty?
-<div class="alert alert-info">
-%     if dependents[:if_failed]  
-  <p><strong>Note</strong>
-  - This test does not bin out as later tests are dependent on it.
-  </p>
-  <p>These tests will run if this test FAILS:
-  <ul>
-%       dependents[:if_failed].each do |dependent|
-  <li><%= _test_to_local_link(dependent) %></li>
-%       end 
-  </ul></p>
-%     end 
-%     if dependents[:if_passed]  
-  <p><strong>Note</strong>
-  - This test does not bin out as later tests are dependent on it.
-  </p>
-  <p>These tests will run if this test PASSES:
-  <ul>
-%       dependents[:if_passed].each do |dependent|
-  <li><%= _test_to_local_link(dependent) %></li>
-%       end 
-  </ul></p>
-%     end 
-%     if dependents[:if_ran]  
-  <p><strong>Note</strong> - These tests will run if this test RUNS:
-  <ul>
-  <ul>
-%       dependents[:if_ran].each do |dependent|
-  <li><%= _test_to_local_link(dependent) %></li>
-%       end 
-  </ul></p>
-%     end 
-%     if dependents[:unless_ran]  
-  <p><strong>Note</strong> - These tests will run if this test DOES NOT RUN:
-  <ul>
-%       dependents[:unless_ran].each do |dependent|
-  <li><%= _test_to_local_link(dependent) %></li>
-%       end 
-  </ul></p>
-%     end 
-</div>
-%   end
-% end
-
-% if c[:if_enable]
-<div class="alert alert-success">
-  <strong>Note</strong>
-  - This test will only run when '<%= c[:if_enable] %>' is enabled.
-</div>
-% end
-
-% if c[:unless_enable]
-<div class="alert alert-success">
-  <strong>Note</strong>
-  - This test will NOT run when '<%= c[:unless_enable] %>' is enabled.
-</div>
-% end
-
-% if f[:continue]
-<div class="alert alert-danger">
-  <strong>Warning!</strong>
-  - This test does not bin out when failed.
-</div>
-% end
-
-% if c[:if_passed]
-<div class="alert alert-success">
-  <p><strong>Note</strong>
-  - This test will only run if this test PASSED:
-  <ul><li><%= _test_to_local_link(program.find_by_id(c[:if_passed], flows, :context => options[:context])) %></li></ul>
-  </p>
-</div>
-% end
-
-% if c[:if_failed]
-<div class="alert alert-success">
-  <p><strong>Note</strong>
-  - This test will only run if this test FAILED:
-  <ul><li><%= _test_to_local_link(program.find_by_id(c[:if_failed], flows, :context => options[:context])) %></li></ul>
-  </p>
-</div>
-% end
-
-% if c[:if_ran]
-<div class="alert alert-success">
-  <p><strong>Note</strong>
-  - This test will only run if this test RAN:
-  <ul><li><%= _test_to_local_link(program.find_by_id(c[:if_ran], flows, :context => options[:context])) %></li></ul>
-  </p>
-</div>
-% end
-
-% if c[:unless_ran]
-<div class="alert alert-success">
-  <p><strong>Note</strong>
-  - This test will only run if this test DID NOT RUN:
-  <ul><li><%= _test_to_local_link(program.find_by_id(c[:unless_ran], flows, :context => options[:context])) %></li></ul>
-  </p>
-</div>
-% end
-
-
-</td>
-<td class="col2">#<%= _test_number(t) %></td>
-<td class="col3">B<%= _bin_number(t) %></td>
-<td class="col4">B<%= _sbin_number(t) %></td>
-<td class="col5 attributes" markdown="1">
-
-% instances.each_with_index do |instance, i|
-%   if i > 0
-
-***
-
-%   end
-%   instance.each do |key, val|
-%     unless [:patterns, :pattern, :by_block, :name, :id].include?(key)
-%#       if val.is_a?(Numeric)
-%#         if val > 1000000
-%#           val = 
-%#         if val > 1000000
-%#       end
-* **<%= key.to_s.capitalize.gsub("_", " ") %>**: <%= val %>
-%     end
-%   end
-%   patterns = [instance[:pattern], instance[:patterns]].flatten.compact
-%   unless patterns.empty?
-%     if options[:link_to_pattern_docs]
-
-<div class="pattern-links">
-%       patterns.each_with_index do |pattern, i|
-%         if patterns.size > 1
-%         txt = "Pattern #{i}"
-%         else
-%         txt = "Pattern"
-%         end
-<a href="<%= path "/patterns/#{pattern}" %>" role="button" class="btn btn-primary btn-small"><%= txt %></a>
-%       end
-</div>
-%     else
-* **Patterns**:
-%       patterns.each_with_index do |pattern, i|
-  * <%= pattern %>
-%       end
-
-%     end
-%     
-%   end
-% end
-</td>
-
-<td class="col6" markdown="1">
-
-%     description.each do |line|
-<%= line %>
-%     end
-
-</td>
-</tr>
-%   end              
-% end
-% end
-
-<%= _stop_test_flow_table %>
-
-</div>
-</div>
-</div>
-
-% end

data/templates/web/helpers.md.erb

@@ -0,0 +1,25 @@
+% render "layouts/basic.html", :tab => :helpers do
+
+# Available Helpers
+
+These are the helpers currently provided by this plugin, click the helper of
+of interest to see a live example of it and the required application code to use it.
+
+### Complete Web Pages
+
+These helpers will generate complete web pages for you.
+
+[Model Documentation](<%= path "/helpers/model" %>)  | Create a reference manual style set of doc pages for a given model, including full register descriptions
+[Test Program Flow](<%= path "/helpers/flow" %>)     | Create documentation for a test program flow that has been created using Origen Testers
+
+### Components
+
+The following are components that you can embed within your own web pages.
+
+| [Searchable Documents](<%= path "/helpers/searchable/intro" %>) | Provides a layout for a guides section of your website, complete with search box (the [Origen Guides](http://origen-sdk.org/guides) uses this)
+| [Register Descriptions](<%= path "/helpers/register" %>)        | Create a tabular register view, similar to that used in device reference manuals
+| [Yammer Comments](<%= path "/helpers/yammer" %>)                | Embed a comments section at the bottom of your page using Yammer
+| [Disqus Comments](<%= path "/helpers/disqus" %>)                | Embed a comments section at the bottom of your page using Disqus
+
+
+% end

data/templates/web/{examples → helpers}/disqus.md.erb

@@ -1,13 +1,13 @@
-% render "../layouts/examples.html" do
+% render "../layouts/helpers.html" do
 
 # Disqus Comments
 
 These helpers make it easy to drop a [Disqus](https://disqus.com/) comments section at the
-bottom of your pages, just like [the one below](<%= path "examples/disqus/#Comments" %>).
+bottom of your pages, just like [the one below](<%= path "helpers/disqus/#Comments" %>).
 
 Note that such comments will be externally visible and therefore **this should not be used for
 company internal applications/web pages**. For similar functionality within a company you
-can use [Yammer comments](<%= path "examples/yammer" %>) instead if your company uses the
+can use [Yammer comments](<%= path "helpers/yammer" %>) instead if your company uses the
 Office 365 suite.
 
 ## Community Selection

data/templates/web/helpers/flow.md.erb

@@ -0,0 +1,113 @@
+% render "../layouts/helpers.html" do
+
+# Test Program Flow Documentation
+
+This helper will build a web page to document a test program flow the has been created with Origen.
+
+[Here is an example](http://origen-sdk.org/link_demo/flows/probe_1_flow/).
+
+Multiple flows can be supplied and an [index page like this](http://origen-sdk.org/link_demo/flows)
+is generated to help locate the documentation for a given flow.
+
+## How To Use
+
+Call the helper from an <code>after_web_site_compile</code> callback handler in your
+application's <code>config/application.rb</code> like this:
+
+~~~ruby
+def after_web_site_compile(options)
+  # First build the program to create a flow model
+  Origen.app.runner.launch action: :program, files: "program/probe1.rb"
+  # Then the documentation for it
+  OrigenDocHelpers.generate_flow_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :flows  do |d|
+    d.page flow: :probe1,
+           name: "Probe 1 Flow",
+           target: "default.rb"
+  end
+end
+~~~
+
+Pages for multiple flows can be created like this:
+
+~~~ruby
+def after_web_site_compile(options)
+  # First build the program to create a flow model
+  Origen.app.runner.launch action: :program, files: "program/production.list"
+  # Then the documentation for it
+  OrigenDocHelpers.generate_flow_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :flows  do |d|
+    d.page flow: :probe1,
+           name: "Probe 1 Flow",
+           target: "default.rb"
+    d.page flow: :probe2,
+           name: "Probe 2 Flow",
+           target: "default.rb"
+    d.page flow: :ft,
+           name: "Final Test Flow",
+           target: "default.rb"
+  end
+end
+~~~
+
+Multiple flows can be included on the one page like this:
+
+~~~ruby
+def after_web_site_compile(options)
+  # First build the program to create a flow model
+  Origen.app.runner.launch action: :program, files: "program/production.list"
+  # Then the documentation for it
+  OrigenDocHelpers.generate_flow_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :flows  do |d|
+    d.page flows: [:probe1_start, :probe1_middle, :probe1_end],
+           name: "Probe 1 Flow",
+           target: "default.rb"
+  end
+end
+~~~
+
+Or finally the same flow can be documented as generated for different targets:
+
+~~~ruby
+def after_web_site_compile(options)
+  # First build the program to create a flow model
+  Origen.target.loop targets: ["device_a", "device_b"] do
+    Origen.app.runner.launch action: :program, files: "program/production.list"
+  end
+  # Then the documentation for it
+  OrigenDocHelpers.generate_flow_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :flows  do |d|
+    ["device_a", "device_b"].each do |target|
+      d.page flows: [:probe1_start, :probe1_middle, :probe1_end],
+             name: "Probe 1 Flow",
+             target: target
+    end
+  end
+end
+~~~
+
+## Options
+
+<code>OrigenDocHelpers.generate_flow_docs</code>
+
+* <code>:layout</code> - **Required**, supply a full path to your application's layout file
+* Any other options will be passed to your layout file unmodified, e.g. to set the tab in the generated
+  pages in the above example
+
+<code>page</code>  
+
+* <code>:flow(s)</code> - **Required**, the ID of the flow or flows to run, this is the ID that would be referenced when running <code>origen testers:run FLOW_ID</code>
+* <code>:name</code> - **Required**, the name of the given flow
+* <code>:target</code> - **Required**, the name of the target that has been used to generate the program model
+* <code>:group</code> - Optional, a heading to group similar flows under on the index page, e.g. "Production", "In Development"
+* <code>:context</code> - Optional, a hash of flow runtime conditions, similar to that accepted by <code>origen testers:run</code>, e.g. <code>{ job: "P1" }</code>. This will determine what tests are included in the documentation.
+
+## Website Integration
+
+The flows index page will be generated at path <code>/flows</code> within your application, and it is common
+to create a "Flows(s)" tab in your website's navigation bar to link to this.
+
+If your application only has one flow, then the navbar link should be setup to point directly to
+that flows's page.
+
+The location of the pages for the individual flows are based on the flow name and will be unique to each application,
+you can find them initially via the index page.
+
+
+% end