origen_doc_helpers 0.1.0

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

@@ -0,0 +1,128 @@
+% render "templates/web/layouts/doc.html", heading: "Creating Searchable Documents" do
+
+This helper provides a layout that will create a nested collection of
+documents like this one and which are searchable via the box on the 
+top left.
+
+%#It can also build a PDF representation of the document collection.
+
+### The Document Index
+
+The application must supply a hash to describe the page index that has been built
+on the the left of the page.
+Here is the index used for this page:
+
+~~~ruby
+index = {}
+index[nil] = {
+  intro: "Introduction",
+  page2: "Page 2",
+}
+index["Topic 1"] = {
+  topic1_item1: "First Item",
+  topic1_item2: "Second Item",
+}
+~~~
+
+The sub-hash keys describe where each document lives and what its title is, for example
+the document with title "Second Item" should live in <code>_documents_root_/topic1/item2.md.erb</code>.
+
+By default the root is <code>"#{Origen.root}/templates/web/docs"</code> but this can be overridden
+by supplying a <code>:root</code> option which should describe the relative path from <code>"#{Origen.root}/templates/web"</code>.
+
+### The Layout Helper
+
+A layout helper is provided to include a document in the search and wrap it
+with the indexed layout:
+
+~~~eruby
+<%= "%" %> render "doc_helpers/searchable.html", index: index do
+
+Blah blah blah
+
+<%= "%" %> end
+~~~
+
+The <code>:index</code> option is mandatory, but the following are optional:
+
+~~~text
+%#:pdf_title - PDF creation is enabled by providing a title via this option, e.g. "My Application Guides"
+:heading   - Each wrapped document will have the heading (e.g. "First Item") inserted at the top of the page,
+             to override it supply this option. A common example would be if the topic is long and
+             so an abbreviated version has been used in the index. e.g. "First Item and Other Stuff"
+:topic     - Each wrapped document will have the topic (e.g. "Topic 1") inserted at the top of the page,
+             to override it supply this option. A common example would be if the topic is long and
+             so an abbreviated version has been used in the index. e.g. "Topic 1 and Other Stuff"
+:root      - override the top-level folder containing your documents, e.g. "tutorials/guides"
+:tab       - the helper should automatically work out what tab to select for each document, however
+             if it is struggling for some reason you can force it by supplying the hash key from the
+             index that the given document should be associated with, e.g. :topic1_item1
+~~~
+
+### Incorporating in Your Own Layout
+
+Normally the searchable layout will be wrapped in your own application specific layout
+to insert your custom navigation bar, etc.
+
+As an example here is the actual layout that has been used to generate this page:
+
+
+~~~eruby
+---
+title: <%= options[:title] || Origen.config.name %>
+---
+<%= "<" + "%= render \"partials/navbar.html\", tab: :examples %" + ">" %>
+
+<%= "%" %> index = {}
+<%= "%" %> index[nil] = {
+<%= "%" %>   intro: "Introduction",
+<%= "%" %>   page2: "Page 2",
+<%= "%" %> }
+<%= "%" %> index["Topic 1"] = {
+<%= "%" %>   topic1_item1: "First Item",
+<%= "%" %>   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")
+<%= "%" %> render "doc_helpers/searchable.html", options.merge(opts) do
+
+<%= "<" + "%= yield %" + ">" %>
+
+<%= "%" %> end
+~~~
+
+%#### Enabling PDF Generation
+%#
+%#PDF generation is enabled by supplying the <code>:pdf_title</code> option when calling
+%#the <code>searchable.html</code> template as shown above.
+%#No other application-level configuration or setup is required.
+%#
+%#This will generate the PDF at web site deploy time and add the download link to
+%#the searchable document menu.
+%#
+%#PDF generation is currently only supported on Linux/CDE, the same restriction that applies
+%#to deploying a web site.
+
+### Writing Your Documents
+
+With the layout setup, writing documents is very simple; these should normally
+be regular markdown that is wrapped in your layout.
+
+The top-level header size in your document should be <code>h3</code> or <code>###</code> in markdown.
+
+<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" %>)
+page (where the layout being rendered is the one above):
+
+
+~~~eruby
+<%= "%" %> render "templates/web/layouts/doc.html" do
+
+Hello I'm item 1
+
+<%= "%" %> end
+~~~
+
+% end

data/templates/web/examples/searchable/page2.md.erb

@@ -0,0 +1,5 @@
+% render "templates/web/layouts/doc.html" do
+
+Hello I'm page 2 of the searchable content!
+
+% end

data/templates/web/examples/searchable/topic1/item1.md.erb

@@ -0,0 +1,5 @@
+% render "templates/web/layouts/doc.html" do
+
+Hello I'm item 1
+
+% end

data/templates/web/examples/searchable/topic1/item2.html.erb

@@ -0,0 +1,7 @@
+% render "templates/web/layouts/doc.html" do
+
+<p>
+Hello I'm item 2, blah blah blah
+</p>
+
+% end

data/templates/web/examples/spec.md.erb_NOT_WORKING

@@ -0,0 +1,42 @@
+% render "../layouts/examples.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:
+
+~~~ruby
+spec :soc_vdd do
+  symbol "Vdd"
+  description "Soc Core Power Supply"
+  min "#{vdd_nom} - 50.mV"
+  max "#{vdd_nom} + 50.mV"
+  audience :external
+end
+~~~
+
+### Specification Table
+
+<%= render "templates/shared/spec", spec: $dut.specs %>
+
+Users can pass the following objects as arguments to the spec option:
+
+1. An object that contains specs (e.g. $dut)
+2. An object's spec hash (e.g. $dut.specs)
+3. An individual spec (e.g. $dut.specs(:soc_vdd))
+
+Here is an example of how to insert a specification table in
+a document using method #3 from above:
+
+~~~eruby
+## Specification Table
+
+<%= "%" %> $dut.specs.each do |name, spec|
+
+<%= "<" + "%= render \"doc_helpers/spec.html\", spec: spec %" + ">" %>
+
+<%= "%" %> end
+~~~
+
+% end

data/templates/web/examples/test/flow.md.erb

@@ -0,0 +1,35 @@
+% render "../../layouts/examples.html" do
+
+# Test Flow
+
+Documentation of an Origen-generated test program can be created as follows (requires a
+documentation interface to be setup):
+
+~~~eruby
+<%= "%" %> prog = Origen::Tester::Doc.generate_program_model("program/probe_1.rb", :target => "default")
+
+<%= "<" + "%= render \"doc_helpers/test/flow.md\", :heading => \"Probe 1\", :program => prog, :flow => :probe_1_flow %" + ">" %>
+~~~
+
+The test flow helper takes the following required options:
+
+* **heading** - The page heading, generally the name of the flow
+* **program** - Supply a pre-generated program model
+* **flow(s)** - The name of the flow(s) to document, supply multiple in an array
+
+Additionally these options are available to customize the output:
+
+* **link_to_pattern_docs** - Set this to <code>true</code> to generate links to documentation of the patterns
+  in place of the pattern name. Pattern docs should be placed in <code>templates/web/patterns</code> and the
+  files should be called \<pattern_name\>.md
+* **context** - Supply an execution context to document only the test where the context is true. For example to
+  document the tests that will run when job is "P1"is set
+  supply <code>{ :job => "P1" }</code>
+
+Here is a live example:
+
+% prog = Origen::Tester::Doc.generate_program_model("program/probe_1.rb", :target => "debug")
+
+<%= render "templates/shared/test/flow.md", :heading => "Probe 1", :program => prog, :flow => :probe_1_flow %>
+
+% end

data/templates/web/examples/yammer.md.erb

@@ -0,0 +1,28 @@
+% render "../layouts/examples.html" do
+
+# Yammer Widgets
+
+These helpers wrap the [Yammer Embed API](https://developer.yammer.com/connect/)
+which allows Yammer feeds to be embedded in any web page.
+
+The most useful application of this is to provide a comment stream which will be
+unique to each page, like the one you see below!
+
+To include comments simply add this to the bottom of any given page, or your
+layout file to add comments to every page:
+
+~~~eruby
+<%= "<" + "%= yammer_comments %" + ">" %>
+~~~
+
+The following options are available:
+
+~~~text
+:prompt   - Set what the prompt for new comments should be, 'Comment on this page' is the default
+:group_id - Specify a specific Yammer group ID, defaults to config.yammer_group in the application config, and if not defined falls back to the
+            Origen User's Group
+~~~
+
+<%= yammer_comments %>
+
+% end

data/templates/web/index.md.erb

@@ -0,0 +1,40 @@
+% render "layouts/basic.html" do
+
+%# HTML tags can be embedded in mark down files if you want to do specific custom
+%# formatting like this, but in most cases that is not required.
+<h1><%= Origen.config.name %> <span style="font-size: 14px">(<%= Origen.app.version %>)</span></h1>
+
+### Purpose
+
+This plugin contains a collection of pre-written documentation layouts and helpers for use in
+many typical Origen documentation scenarios.
+
+Additional contributions are welcome, see below for how to setup a development environment,
+please add examples for any new features.
+
+### How To Import
+
+In your Gemfile add:
+
+~~~ruby
+gem "origen_doc_helpers", ">= <%= Origen.app.version %>"
+~~~
+
+or if your application is a plugin add this to your <code>.gemspec</code>
+
+~~~ruby
+spec.add_development_dependency "origen_doc_helpers", ">= <%= Origen.app.version %>"
+~~~
+
+### How To Use
+
+See the [Examples](<%= path "examples" %>) to see what is available
+and how to use them.
+
+### How To Setup a Development Environment
+
+[Clone the repository from Github](https://github.com/Origen-SDK/origen_doc_helpers).
+
+All templates can be found in <code>templates/shared</code>.
+
+% end

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

@@ -0,0 +1,13 @@
+---
+title: <%= options[:title] || Origen.config.name %>
+---
+<%= render "templates/web/partials/navbar.html", :tab => options[:tab] %>
+
+<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
+  <div class="span12" markdown="1">
+<%= yield %>    
+
+</div>
+</div>

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

@@ -0,0 +1,22 @@
+---
+title: <%= options[:title] || Origen.config.name %>
+---
+<%= render "partials/navbar.html", :tab => :examples %>
+
+%# 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",
+% }
+
+% render "templates/shared/searchable.html", options.merge(:index => s, :root => "examples/searchable") do
+
+<%= yield %>    
+
+% end

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

@@ -0,0 +1,5 @@
+% render "basic.html", :tab => :examples do
+
+<%= yield %>
+
+% end

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

@@ -0,0 +1,21 @@
+<nav class="navbar navbar-inverse navbar-fixed-top">
+  <div class="container">
+    <div class="navbar-header">
+      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
+        <span class="sr-only">Toggle navigation</span>
+        <span class="icon-bar"></span>
+        <span class="icon-bar"></span>
+        <span class="icon-bar"></span>
+      </button>
+      <a class="navbar-brand" href="<%= path "/" %>">Home</a>
+    </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] == :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>
+      <%= import "origen/web/logo.html" %>
+    </div><!--/.nav-collapse -->
+  </div>
+</nav>

data/templates/web/release_notes.md.erb

@@ -0,0 +1,5 @@
+% render "layouts/basic.html", :tab => :release do
+
+<%= render "#{Origen.root}/doc/history" %>
+
+% end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: origen_doc_helpers
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stephen McGinty
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: origen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.5
+description: 
+email:
+- stephen.f.mcginty@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- config/application.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/pdf.rb
+- program/_func.rb
+- program/_hvst.rb
+- program/_para.rb
+- program/probe_1.rb
+- 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/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/index.md.erb
+- templates/web/layouts/_basic.html.erb
+- templates/web/layouts/_doc.html.erb
+- templates/web/layouts/_examples.html.erb
+- templates/web/partials/_navbar.html.erb
+- templates/web/release_notes.md.erb
+homepage: http://origen-sdk.org/doc_helpers
+licenses:
+- LGPL-3
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.8.11
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Snippets and helpers for creating Origen web documents
+test_files: []
+has_rdoc: