origen_doc_helpers 0.3.0 → 0.4.0

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

@@ -0,0 +1,81 @@
+% render "../layouts/helpers.html" do
+
+# Model Documentation
+
+This helper will build a collection of web pages that document a model's attributes,
+currently this includes its sub-blocks and registers.
+
+[Here is an example](http://origen-sdk.org/link_demo/models/linkdemo_toplevel/).
+
+Multiple models can be supplied and an [index page like this](http://origen-sdk.org/link_demo/models)
+is generated to help locate the documentation for a given model.
+
+The collection of pages associated with a particular model is also fully searchable via
+the provided search box.
+
+## 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)
+  # Build the model documentation
+  OrigenDocHelpers.generate_model_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :model do |d|
+    d.page model: $dut
+  end
+end
+~~~
+
+To generate documentation for more than one model, call the page method multiple times like this:
+
+~~~ruby
+def after_web_site_compile(options)
+  # Build the model documentation
+  OrigenDocHelpers.generate_model_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :model do |d|
+    d.page model: MyApp::ModelA.new
+    d.page model: MyApp::ModelB.new
+    d.page model: MyApp::ModelC.new
+  end
+end
+~~~
+
+If the different models are all top-level instances (i.e. they include <code>Origen::TopLevel</code> and are
+what is commonly referred to as <code>$dut</code>), then a target loop should be used like this:
+
+~~~ruby
+def after_web_site_compile(options)
+  # Build the model documentation
+  OrigenDocHelpers.generate_model_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :model do |d|
+    Origen.target.loop targets: ["target_a", "target_b", "target_c"] do
+      d.page model: $dut
+    end
+  end
+end
+~~~
+
+## Options
+
+<code>OrigenDocHelpers.generate_model_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>:model</code> - **Required**, supply an instance of the model
+* <code>:group</code> - Optional, a heading to group similar models under on the index page, e.g. "Production", "In Development"
+
+## Website Integration
+
+The model index page will be generated at path <code>/models</code> within your application, and it is common
+to create a "Model(s)" tab in your website's navigation bar to link to this.
+
+If your application only has one model, then the navbar link should be setup to point directly to
+that model's page.
+
+The location of the pages for the individual models are based on the model name and will be unique to each application,
+you can find them initially via the index page.
+
+% end

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

@@ -1,4 +1,4 @@
-% render "../layouts/examples.html" do
+% render "../layouts/helpers.html" do
 
 # Register Helpers
 
@@ -56,8 +56,6 @@ end
 
 ### Basic Register Diagram
 
-<%= render "templates/shared/register", :reg => $dut.reg(:mclkdiv) %>
-
 Here is an example of how to insert a basic register diagram in
 a document:
 
@@ -71,9 +69,9 @@ a document:
 <%= "%" %> end
 ~~~
 
-### Register Diagram with Descriptions
+<%= render "templates/shared/register", :reg => $dut.reg(:mclkdiv) %>
 
-<%= render "templates/shared/register", :reg => $dut.reg(:mclkdiv), :descriptions => true %>
+### Register Diagram with Descriptions
 
 Set the <code>:descriptions</code> switch to true to include the register and
 bit descriptions:
@@ -88,6 +86,8 @@ bit descriptions:
 <%= "%" %> end
 ~~~
 
+<%= render "templates/shared/register", :reg => $dut.reg(:mclkdiv), :descriptions => true %>
+
 ### Additional Test Cases
 
 <%= render "templates/shared/register", :reg => $dut.reg(:proth) %>

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

@@ -72,7 +72,7 @@ As an example here is the actual layout that has been used to generate this page
 ---
 title: <%= options[:title] || Origen.config.name %>
 ---
-<%= "<" + "%= render \"partials/navbar.html\", tab: :examples %" + ">" %>
+<%= "<" + "%= render \"partials/navbar.html\", tab: :helpers %" + ">" %>
 
 <%= "%" %> index = {}
 <%= "%" %> index[nil] = {
@@ -84,8 +84,8 @@ title: <%= options[:title] || Origen.config.name %>
 <%= "%" %>   topic1_item2: "Second Item",
 <%= "%" %> }
 
-%#<%= "%" %> opts = options.merge(index: index, root: "examples/searchable", pdf_title: "Doc Helpers Searchable Guide")
-<%= "%" %> opts = options.merge(index: index, root: "examples/searchable")
+%#<%= "%" %> opts = options.merge(index: index, root: "helpers/searchable", pdf_title: "Doc Helpers Searchable Guide")
+<%= "%" %> opts = options.merge(index: index, root: "helpers/searchable")
 <%= "%" %> render "doc_helpers/searchable.html", options.merge(opts) do
 
 <%= "<" + "%= yield %" + ">" %>
@@ -114,7 +114,7 @@ The top-level header size in your document should be <code>h3</code> or <code>##
 
 <code>.html.erb</code> files will also work if you want to use them.
 
-Here is the actual code used behind the [Topic 1 - First Item](<%= path "examples/searchable/topic1/item1" %>)
+Here is the actual code used behind the [Topic 1 - First Item](<%= path "helpers/searchable/topic1/item1" %>)
 page (where the layout being rendered is the one above):
 
 

data/templates/web/{examples → helpers}/spec.md.erb_NOT_WORKING

@@ -1,10 +1,10 @@
-% render "../layouts/examples.html" do
+% render "../layouts/helpers.html" do
 
 # Specification Helpers
 
 Use the [Origen specification API](http://origen.freescale.net/origen/latest/guides/models/specs)
 to define specifications in the normal way,
-all of the examples shown here are based on this specification definition:
+all of the helpers shown here are based on this specification definition:
 
 ~~~ruby
 spec :soc_vdd do

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

@@ -1,4 +1,4 @@
-% render "../layouts/examples.html" do
+% render "../layouts/helpers.html" do
 
 # Yammer Comments
 

data/templates/web/index.md.erb

@@ -28,7 +28,7 @@ spec.add_development_dependency "origen_doc_helpers", ">= <%= Origen.app.version
 
 ### How To Use
 
-See the [Examples](<%= path "examples" %>) to see what is available
+See the [Available Helpers](<%= path "helpers" %>) page to see the current list of helpers
 and how to use them.
 
 ### How To Setup a Development Environment

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

@@ -2,7 +2,7 @@
 title: <%= options[:title] || Origen.config.name %>
 analytics: UA-64455560-1
 ---
-<%= render "partials/navbar.html", :tab => :examples %>
+<%= render "partials/navbar.html", :tab => :helpers %>
 
 %# 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.
@@ -16,7 +16,7 @@ analytics: UA-64455560-1
 %   :topic1_item2 => "Second Item",
 % }
 
-% render "templates/shared/searchable.html", options.merge(:index => s, :root => "examples/searchable") do
+% render "templates/shared/searchable.html", options.merge(:index => s, :root => "helpers/searchable") do
 
 <%= yield %>    
 

data/templates/web/layouts/{_examples.html.erb → _helpers.html.erb}

@@ -1,4 +1,4 @@
-% render "basic.html", :tab => :examples do
+% render "basic.html", :tab => :helpers do
 
 <%= yield %>
 

data/templates/web/partials/_navbar.html.erb

@@ -11,7 +11,7 @@
     </div>
     <div id="navbar" class="collapse navbar-collapse">
       <ul class="nav navbar-nav">
-        <li class="<%= options[:tab] == :examples ? 'active' : '' %>"><a href="<%= path "/examples" %>">Examples</a></li>
+        <li class="<%= options[:tab] == :helpers ? 'active' : '' %>"><a href="<%= path "/helpers" %>">Helpers</a></li>
         <li class="<%= options[:tab] == :release ? 'active' : '' %>"><a href="<%= path "/release_notes" %>">Release Notes</a></li>
         <li><a href="https://github.com/Origen-SDK/origen_doc_helpers">Github</a></li>
       </ul>

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: origen_doc_helpers
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Stephen McGinty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-25 00:00:00.000000000 Z
+date: 2016-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: origen
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: 0.7.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: 0.7.7
 - !ruby/object:Gem::Dependency
   name: origen_testers
   requirement: !ruby/object:Gem::Requirement
@@ -46,41 +46,42 @@ extensions: []
 extra_rdoc_files: []
 files:
 - config/application.rb
+- config/boot.rb
 - config/commands.rb
-- config/development.rb
-- config/environment.rb
 - config/users.rb
 - config/version.rb
-- lib/helpers.rb
 - lib/origen_doc_helpers.rb
-- lib/origen_doc_helpers/doc_interface.rb
 - lib/origen_doc_helpers/dut.rb
+- lib/origen_doc_helpers/flow_page_generator.rb
+- lib/origen_doc_helpers/helpers.rb
 - lib/origen_doc_helpers/html_flow_formatter.rb
 - lib/origen_doc_helpers/list_flow_formatter.rb
+- lib/origen_doc_helpers/model_page_generator.rb
 - lib/origen_doc_helpers/pdf.rb
-- program/_func.rb
-- program/_hvst.rb
-- program/_para.rb
-- program/probe_1.rb
+- templates/flow_index.md.erb
+- templates/flow_page.md.erb
+- templates/model_index.md.erb
+- templates/model_page.md.erb
 - templates/pdf/topic_wrapper.html
 - templates/shared/_register.html.erb
 - templates/shared/_searchable.html.erb
 - templates/shared/_spec.html.erb
 - templates/shared/test/_flow.md.erb
-- templates/web/examples.md.erb
-- templates/web/examples/disqus.md.erb
-- templates/web/examples/register.md.erb
-- templates/web/examples/searchable/intro.md.erb
-- templates/web/examples/searchable/page2.md.erb
-- templates/web/examples/searchable/topic1/item1.md.erb
-- templates/web/examples/searchable/topic1/item2.html.erb
-- templates/web/examples/spec.md.erb_NOT_WORKING
-- templates/web/examples/test/flow.md.erb
-- templates/web/examples/yammer.md.erb
+- templates/web/helpers.md.erb
+- templates/web/helpers/disqus.md.erb
+- templates/web/helpers/flow.md.erb
+- templates/web/helpers/model.md.erb
+- templates/web/helpers/register.md.erb
+- templates/web/helpers/searchable/intro.md.erb
+- templates/web/helpers/searchable/page2.md.erb
+- templates/web/helpers/searchable/topic1/item1.md.erb
+- templates/web/helpers/searchable/topic1/item2.html.erb
+- templates/web/helpers/spec.md.erb_NOT_WORKING
+- templates/web/helpers/yammer.md.erb
 - templates/web/index.md.erb
 - templates/web/layouts/_basic.html.erb
 - templates/web/layouts/_doc.html.erb
-- templates/web/layouts/_examples.html.erb
+- templates/web/layouts/_helpers.html.erb
 - templates/web/partials/_navbar.html.erb
 - templates/web/release_notes.md.erb
 homepage: http://origen-sdk.org/doc_helpers
@@ -103,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.8.11
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.6.2
 signing_key: 
 specification_version: 4
 summary: Snippets and helpers for creating Origen web documents

data/config/development.rb

@@ -1,16 +0,0 @@
-# This file is similar to environment.rb and will be loaded
-# automatically at the start of each invocation of Origen.
-#
-# However the major difference is that it will not be loaded
-# if the application is imported by a 3rd party app - in that
-# case only environment.rb is loaded.
-#
-# Therefore this file should be used to load anything you need
-# to setup a development environment for this app, normally
-# this would be used to load some dummy classes to instantiate
-# your objects so that they can be tested and/or interacted with
-# in the console.
-module OrigenDocHelpers
-  autoload :DUT, "origen_doc_helpers/dut"
-end
-require "origen_doc_helpers/doc_interface"

data/config/environment.rb

@@ -1,32 +0,0 @@
-# This file will be required by Origen before your target is loaded, you 
-# can use this to require all of your files, which is the easiest way
-# to get started. As your experience grows you may wish to require only the
-# minimum files required to allow the target to be initialized and let 
-# each class require its own dependencies.
-#
-# It is recommended that you keep all of your application logic in lib/
-# The lib directory has already been added to the search path and so any files
-# in there can be referenced from here with a relative path.
-#
-# Note that pattern files do not need to be referenced from here and these
-# will be located automatically by origen.
-
-# This says load the file "lib/pioneer.rb" the first time anyone makes a 
-# reference to the class name 'Pioneer'.
-#autoload :Pioneer,   "pioneer"
-# This is generally preferable to using require which will load the file
-# regardless of whether it is needed by the current target or not:
-#require "pioneer"
-# Sometimes you have to use require however:-
-#   1. When defining a test program interface:
-#require "interfaces/j750"
-#   2. If you want to extend a class defined by an imported application, in
-#      this case your must use required and supply a full path (to distinguish
-#      it from the one in the parent application):
-#require "#{Origen.root}/c90_top_level/p2"
-module OrigenDocHelpers
-  autoload :PDF, "origen_doc_helpers/pdf"
-  autoload :HtmlFlowFormatter, "origen_doc_helpers/html_flow_formatter"
-  autoload :ListFlowFormatter, "origen_doc_helpers/list_flow_formatter"
-end
-require "helpers"

data/lib/origen_doc_helpers/doc_interface.rb

@@ -1,74 +0,0 @@
-module OrigenDocHelpers
-  class DocInterface
-    include OrigenTesters::Doc::Generator
-
-    def initialize(_options = {})
-    end
-
-    def log(_msg)
-    end
-
-    def instance_name(name, options = {})
-      name = pattern_name(name)
-      if options[:vdd] || options[:vdd] != :nom
-        name += "_#{options[:vdd]}"
-      end
-      name
-    end
-
-    def pattern_name(name, _options = {})
-      name.to_s
-    end
-
-    def vdd_loop(options)
-      [options[:vdd]].flatten.each do |vdd|
-        yield options.merge(vdd: vdd)
-      end
-    end
-
-    def func(name, options = {})
-      options = {
-        vdd:  [:min, :max],
-        type: :functional
-      }.merge(options)
-      vdd_loop(options) do |options|
-        test = add_test name, options
-        add_flow_entry(test, options)
-      end
-    end
-
-    def para(name, options = {})
-      options = {
-        vdd:  [:min, :max],
-        type: :parametric
-      }.merge(options)
-      vdd_loop(options) do |options|
-        test = add_test name, options
-        add_flow_entry(test, options)
-      end
-    end
-
-    def add_pattern(name, options = {})
-      options[:pattern] = pattern_name(name, options)
-      options
-    end
-
-    def add_test(name, options)
-      options = {
-      }.merge(options)
-      # Delete any keys that we don't want to assign to the instance, this keeps
-      # the attributes efficient, flow control keys will be screened by Origen
-      [:bin, :tnum, :tname, :continue
-      ].each { |k| options.delete(k) }
-      tests.add(instance_name(name, options), add_pattern(name, options))
-    end
-
-    def add_flow_entry(test, options)
-      options = {
-        number:   options[:bin] * 1000,
-        soft_bin: options[:bin]
-      }.merge(options)
-      flow.test test, options
-    end
-  end
-end