yard-gherkin-turnip 1.0.0

data/lib/templates/default/fulldoc/html/setup.rb

@@ -0,0 +1,208 @@
+include YARD::Templates::Helpers::HtmlHelper
+
+def init
+  super
+
+  # Additional javascript that power the additional menus, collapsing, etc.
+  asset "js/cucumber.js", file("js/cucumber.js",true)
+
+  serialize_object_type :feature
+
+  serialize_object_type :tag
+
+  # Generates the requirements splash page with the 'requirements' template
+  serialize(YARD::CodeObjects::Cucumber::CUCUMBER_NAMESPACE)
+
+  # Generates a page for step definitions and step placeholders with the 'steptransformers' template
+  serialize(YARD::CodeObjects::Cucumber::CUCUMBER_STEPTRANSFORM_NAMESPACE)
+
+  # Generates the tags page with the 'featuretags' template
+  serialize(YARD::CodeObjects::Cucumber::CUCUMBER_TAG_NAMESPACE)
+
+  serialize_feature_directories
+end
+
+#
+# The top-level feature directories. This is affected by the directories that YARD is told to parse.
+# All other features in sub-directories are contained under each of these top-level directories.
+#
+# @example Generating one feature directory
+#
+#     `yardoc 'example/**/*'`
+#
+# @example Generating two feature directories
+#
+#     `yardoc 'example/**/*' 'example2/**/*'`
+#
+# @return the feature directories at the root of the Cucumber Namespace.
+#
+def root_feature_directories
+  @root_feature_directories ||= YARD::CodeObjects::Cucumber::CUCUMBER_NAMESPACE.children.find_all {|child| child.is_a?(YARD::CodeObjects::Cucumber::FeatureDirectory)}
+end
+
+#
+# Generate pages for the objects if there are objects of this type contained
+# within the Registry.
+#
+def serialize_object_type(type)
+  objects = Registry.all(type.to_sym)
+  Array(objects).each {|object| serialize(object) }
+end
+
+#
+# Generates pages for the feature directories found. Starting with all root-level feature
+# directories and then recursively finding all child feature directories.
+#
+def serialize_feature_directories
+  serialize_feature_directories_recursively(root_feature_directories)
+  root_feature_directories.each {|directory| serialize(directory) }
+end
+
+#
+# Generate a page for each Feature Directory. This is called recursively to
+# ensure that all feature directories contained as children are rendered to
+# pages.
+#
+def serialize_feature_directories_recursively(namespaces)
+  namespaces.each do |namespace|
+    Templates::Engine.with_serializer(namespace, options[:serializer]) do
+      options[:object] = namespace
+      T('layout').run(options)
+    end
+    serialize_feature_directories_recursively(namespace.children.find_all {|child| child.is_a?(YARD::CodeObjects::Cucumber::FeatureDirectory)})
+  end
+end
+
+# Generate feature list
+# @note this method is called automatically by YARD based on the menus defined in the layout
+def generate_feature_list
+  features = Registry.all(:feature)
+  features_ordered_by_name = features.sort {|x,y| x.value.to_s <=> y.value.to_s }
+  generate_full_list features_ordered_by_name, :features
+end
+
+# Count scenarios for features
+def record_feature_scenarios(features)
+  count_with_examples = 0
+  features.each do |f|
+    count_with_examples += f.total_scenarios
+  end
+  return count_with_examples
+end
+
+# Count scenarios for tags
+def record_tagged_scenarios(tags)
+  scenario_count = 0
+  count_with_examples = 0
+  tags.each do |t|
+    scenario_count += t.all_scenarios.size
+    count_with_examples += t.total_scenarios
+  end
+end
+
+# Generate tag list
+# @note this method is called automatically by YARD based on the menus defined in the layout
+def generate_tag_list
+  tags = Registry.all(:tag)
+  tags_ordered_by_use = Array(tags).sort {|x,y| y.total_scenarios <=> x.total_scenarios }
+
+  record_tagged_scenarios(tags)
+
+  generate_full_list tags_ordered_by_use, :tags
+end
+
+# Generate a step definition list
+# @note this menu is not automatically added until yard configuration has this menu added
+# See the layout template method that loads the menus
+def generate_stepdefinition_list
+  generate_full_list YARD::Registry.all(:stepdefinition), :stepdefinitions,
+    :list_title => "Step Definitions List"
+end
+
+# Generate a step list
+# @note this menu is not automatically added until yard configuration has this menu added
+# See the layout template method that loads the menus
+def generate_step_list
+  generate_full_list YARD::Registry.all(:step), :steps
+end
+
+# Generate feature list
+# @note this menu is not automatically added until yard configuration has this menu added
+# See the layout template method that loads the menus
+def generate_featuredirectories_list
+  directories_ordered_by_name = root_feature_directories.sort {|x,y| x.value.to_s <=> y.value.to_s }
+  generate_full_list directories_ordered_by_name, :featuredirectories,
+    :list_title => "Features by Directory",
+    :list_filename => "featuredirectories_list.html"
+end
+
+
+# Helpler method to generate a full_list page of the specified objects with the
+# specified type.
+def generate_full_list(objects,type,options = {})
+  defaults = { :list_title => "#{type.to_s.capitalize} List",
+    :css_class => "class",
+    :list_filename => "#{type.to_s.gsub(/s$/,'')}_list.html" }
+
+  options = defaults.merge(options)
+
+  @items = objects
+  @list_type = type
+  @list_title = options[:list_title]
+  @list_class = options[:css_class]
+  asset options[:list_filename], erb(:full_list)
+end
+
+#
+# @note This method overrides YARD's default template class_list method.
+#
+# The existing YARD 'Class List' search field contains all the YARD namespace objects.
+# We, however, do not want the Cucumber Namespace YARD Object (which holds the features,
+# tags, etc.) as it is a meta-object.
+#
+# This method removes the namespace from the root node, generates the class list,
+# and then adds it back into the root node.
+#
+def class_list(root = Registry.root, tree = TreeContext.new)
+  return super unless root == Registry.root
+
+  cucumber_namespace = YARD::CodeObjects::Cucumber::CUCUMBER_NAMESPACE
+  root.instance_eval { children.delete cucumber_namespace }
+  out = super(root)
+  root.instance_eval { children.push cucumber_namespace }
+  out
+end
+
+#
+# Generate a link to the 'All Features' in the features_list.html
+#
+# When there are no feature directories or multiple top-level feature directories
+# then we want to link to the 'Requirements' page
+#
+# When there are is just one feature directory then we want to link to that directory
+#
+def all_features_link
+  features = Registry.all(:feature)
+  count_with_examples = record_feature_scenarios(features)
+  if root_feature_directories.length == 0 || root_feature_directories.length > 1
+    linkify YARD::CodeObjects::Cucumber::CUCUMBER_NAMESPACE, "All Features (#{count_with_examples})"
+  else
+    linkify root_feature_directories.first, "All Features (#{count_with_examples})"
+  end
+end
+
+#
+# This method is used to generate a feature directory. This template may call
+# this method as well to generate any child feature directories as well.
+#
+# @param directory [FeatureDirectory] this is the FeatureDirectory to display
+# @param padding [Fixnum] this is the pixel value to ident as we want to keep
+#    pushing in the padding to show the parent relationship
+# @param row [String] 'odd' or 'even' to correctly color the row
+#
+def directory_node(directory,padding,row)
+  @directory = directory
+  @padding = padding
+  @row = row
+  erb(:directories)
+end

data/lib/templates/default/layout/html/setup.rb

@@ -0,0 +1,131 @@
+def init
+  super
+end
+
+#
+# Append yard-gherkin-turnip stylesheet to yard core stylesheets
+#
+def stylesheets
+  super + %w(css/cucumber.css)
+end
+
+#
+# Append yard-gherkin-turnip javascript to yard core javascripts
+#
+def javascripts
+  super + %w(js/cucumber.js)
+end
+
+#
+# Append yard-gherkin-turnip specific menus 'features' and 'tags'
+#
+# 'features' and 'tags' are enabled by default.
+#
+# 'step definitions' and 'steps' may be enabled by setting up a value in
+# yard configuration file '~/.yard/config'
+#
+# @example `~/.yard/config`
+#
+#     yard-gherkin-turnip:
+#       menus: [ 'features', 'directories', 'tags', 'step definitions', 'steps' ]
+#
+def menu_lists
+  current_menu_lists.map {|menu_name| yard_turnip_menus[menu_name] }.compact + super
+end
+
+#
+# By default we want to display the 'features' and 'tags' menu but we will allow
+# the YARD configuration to override that functionality.
+#
+def current_menu_lists
+  @current_menu_lists ||= begin
+    menus = [ "features", "tags" ]
+
+    if YARD::Config.options["yard-gherkin-turnip"] and YARD::Config.options["yard-gherkin-turnip"]["menus"]
+      menus = YARD::Config.options["yard-gherkin-turnip"]["menus"]
+    end
+
+    menus
+  end
+end
+
+#
+# When a menu is specified in the yard configuration file, this hash contains
+# the details about the menu necessary for it to be displayed.
+#
+# @see #menu_lists
+#
+def yard_turnip_menus
+  { "features" => { :type => 'feature', :title => 'Features', :search_title => 'Features' },
+    "directories" => { :type => 'featuredirectories', :title => 'Features by Directory', :search_title => 'Features by Directory' },
+    "tags" => { :type => 'tag', :title => 'Tags', :search_title => 'Tags' },
+    "step definitions" => { :type => 'stepdefinition', :title => 'Step Definitions', :search_title => 'Step Defs' },
+    "steps" => { :type => 'step', :title => 'Steps', :search_title => 'Steps' } }
+end
+
+#
+# @note This method overrides YARD's default layout template's layout method.
+#
+# The existing YARD layout method generates the url for the nav menu on the left
+# side. For YARD-Gherkin-Turnip objects this will default to the class_list.html.
+# which is not what we want for features, tags, etc.
+#
+# So we override this method and put in some additional logic to figure out the
+# correct list to appear in the search. This can be particularly tricky because
+#
+# This method removes the namespace from the root node, generates the class list,
+# and then adds it back into the root node.
+#
+def layout
+  @nav_url = url_for_list(!@file || options.index ? 'class' : 'file')
+
+
+  if is_yard_cucumber_object?(object)
+    @nav_url = rewrite_nav_url(@nav_url)
+  end
+
+  if !object || object.is_a?(String)
+    @path = nil
+  elsif @file
+    @path = @file.path
+  elsif !object.is_a?(YARD::CodeObjects::NamespaceObject)
+    @path = object.parent.path
+  else
+    @path = object.path
+  end
+
+  erb(:layout)
+end
+
+#
+# Determine if the object happens to be a CodeObject defined in this gem.
+#
+# @note quite a few of the classes/modules defined here are not object that we
+#   would never want to display but it's alright if we match on them.
+#
+# @return [Boolean] true if the object's class name is one of the CodeObjects
+#
+def is_yard_cucumber_object?(object)
+  YARD::CodeObjects::Cucumber.constants.any? {|constant| object.class.name == "YARD::CodeObjects::Cucumber::#{constant}" }
+end
+
+#
+# The re-write rules will only change the nav link to a new menu if it is a
+# a Cucumber CodeObject that we care about and that we have also generated a
+# menu for that item.
+#
+def rewrite_nav_url(nav_url)
+  if object.is_a?(YARD::CodeObjects::Cucumber::Feature) && current_menu_lists.include?('features')
+    nav_url.gsub('class_list.html','feature_list.html')
+  elsif object.is_a?(YARD::CodeObjects::Cucumber::FeatureDirectory) && current_menu_lists.include?('directories')
+    nav_url.gsub('class_list.html','featuredirectories_list.html')
+  elsif object.is_a?(YARD::CodeObjects::Cucumber::Tag) && current_menu_lists.include?('tags')
+    nav_url.gsub('class_list.html','tag_list.html')
+  elsif object.is_a?(YARD::CodeObjects::Cucumber::Step) && current_menu_lists.include?('steps')
+    nav_url.gsub('class_list.html','step_list.html')
+  elsif object.is_a?(YARD::CodeObjects::Cucumber::StepTransformer) && current_menu_lists.include?('step definitions')
+    nav_url.gsub('class_list.html','stepdefinition_list.html')
+  else
+    nav_url
+  end
+end

data/lib/templates/default/requirements/html/alpha_table.erb

@@ -0,0 +1,26 @@
+<% if @elements && !@elements.empty? %>
+  <% i = (@elements.length % 2 == 0 ? 1 : 0) %>
+  <table style="margin-left: 10px; width: 100%;">
+    <tr>
+      <td valign='top' width="50%">
+        <% @elements.each do |letter, objects| %>
+          <% if (i += 1) > (@elements.length / 2 + 1) %>
+          </td><td valign='top' width="50%">
+            <% i = 0 %>
+          <% end %>
+          <ul id="alpha_<%= letter %>" class="alpha">
+            <li class="letter"><%= letter %></li>
+            <ul>
+              <% objects.each do |obj| %>
+                <li>
+                  <%= linkify obj, obj.value %>
+                  <small>(<%= obj.file %>)</small>
+                </li>
+              <% end %>
+            </ul>
+          </ul>
+        <% end %>
+      </td>
+    </tr>
+  </table>
+<% end %>

data/lib/templates/default/requirements/html/requirements.erb

@@ -0,0 +1,50 @@
+<% if @namespace %>
+  <div id="cukes_logo">&nbsp;</div>
+  <div id="cukes_links">
+    <a href="http://cukes.info/">Cucumber</a> |
+    <a href="http://github.com/cucumber/cucumber/wiki/Gherkin">Gherkin</a> |
+    <a href="http://yardoc.org/">YARD</a> |
+    <a href="https://github.com/angelatodd/yard-gherkin-turnip">YARD-Gherkin-Turnip</a>
+  </div>
+
+  <div class="requirements">
+
+    <% if features && !features.empty? %>
+      <%= alpha_table(features) %>
+    <% else %>
+      <!-- No Features Defined -->
+      <div class="none">No Features Defined</div>
+    <% end %>
+
+    <div id="directory" style="margin-left: 40px;">
+      <div class="title"><span class="name">Tags</span></div>
+    </div>
+    <div class="tags">
+      <%= tags.collect {|tag| linkify(tag,tag.value) }.join(",\n") %>
+    </div>
+
+    <% if feature_subdirectories && !feature_subdirectories.empty? %>
+      <div id="directory" style="margin-left: 40px;">
+        <div class="title"><span class="name">Subdirectories</span></div>
+      </div>
+      <%= alpha_table(feature_subdirectories) %>
+    <% else %>
+      <!-- No Feature Directories -->
+    <% end %>
+    
+    <div id="directory" style="margin-left: 40px;">
+      <div class="title"><span class="name">Step Definitions &amp; Placeholders</span></div>
+    </div>
+    <div class="steptransformers">
+      <%= step_definitions.length %> 
+      <a href="<%= url_for step_transformers, "step_definitions" %>">Step Definitions</a>
+      <%= placeholders.length %>
+      <a href="<%= url_for step_transformers, "placeholders" %>">Placeholders</a>
+      and <%= undefined_steps.length %>
+      <a href="<%= url_for step_transformers, "undefined_steps" %>">Undefined Steps</a>
+    </div>
+    
+  </div>
+<% end %>
+
+

data/lib/templates/default/requirements/html/setup.rb

@@ -0,0 +1,51 @@
+def init
+  super
+  sections.push :requirements
+  @namespace = object
+
+end
+
+def features
+  @features ||= Registry.all(:feature)
+end
+
+def tags
+  @tags ||= Registry.all(:tag).sort_by {|l| l.value.to_s }
+end
+
+def feature_directories
+  @feature_directories ||= YARD::CodeObjects::Cucumber::CUCUMBER_NAMESPACE.children.find_all {|child| child.is_a?(YARD::CodeObjects::Cucumber::FeatureDirectory)}
+end
+
+def feature_subdirectories
+  @feature_subdirectories ||= Registry.all(:featuredirectory) - feature_directories
+end
+
+def step_transformers
+  YARD::CodeObjects::Cucumber::CUCUMBER_STEPTRANSFORM_NAMESPACE
+end
+
+def step_definitions
+  @step_definitions ||= YARD::Registry.all(:stepdefinition)
+end
+
+def placeholders
+  @placeholders ||= YARD::Registry.all(:placeholder)
+end
+
+def undefined_steps
+  @undefined_steps ||= Registry.all(:step).reject {|s| s.definition || s.scenario.outline? }
+end
+
+
+def alpha_table(objects)
+  @elements = Hash.new
+
+  objects = run_verifier(objects)
+  objects.each {|o| (@elements[o.value.to_s[0,1].upcase] ||= []) << o }
+  @elements.values.each {|v| v.sort! {|a,b| b.value.to_s <=> a.value.to_s } }
+  @elements = @elements.sort_by {|l,o| l.to_s }
+
+  @elements.each {|letter,objects| objects.sort! {|a,b| b.value.to_s <=> a.value.to_s }}
+  erb(:alpha_table)
+end