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.

Multiple models can be supplied and an index page like this 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 after_web_site_compile callback handler in your application’s config/application.rb like this:

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

For very large models the model search feature may cause the model pages to load slowly. In this case it may be desirable to disable the model search feature. You can do this by adding an optional argument to the your application’s callback handler like this:

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, search_box: false
  end
end

To generate documentation for more than one model, call the page method multiple times like this:

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 Origen::TopLevel and are what is commonly referred to as $dut), then a target loop should be used like this:

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

OrigenDocHelpers.generate_model_docs

  • :layout - 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

page

  • :model - Required, supply an instance of the model
  • :group - Optional, a heading to group similar models under on the index page, e.g. “Production”, “In Development”
  • :target_as_id - Optional, causes the target name to be used for model page headings instead of the top-level model class name, e.g. “Eagle” instead of “MyApp::ModelA”. This is particularly useful if multiple targets instantiate the same top-level model with different options or attributes that lead to differentiation.

Website Integration

The model index page will be generated at path /models 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.

Comments