puppet-strings 0.4.0

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/hostclass/setup.rb

@@ -0,0 +1,21 @@
+include T('default/definedtype')
+
+def init
+  super
+  sections.push :subclasses
+end
+
+def subclasses
+  # The naming is a bit weird because Ruby classes use `globals.subclasses`.
+  unless globals.hostsubclasses
+    globals.hostsubclasses = {}
+    list = run_verifier Registry.all(:hostclass)
+    list.each {|o| (globals.hostsubclasses[o.parent_class.path] ||= []) << o if o.parent_class }
+  end
+
+  @subclasses = globals.hostsubclasses[object.path]
+
+  return if @subclasses.nil? || @subclasses.empty?
+  erb(:subclasses)
+end
+

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/html_helper.rb

@@ -0,0 +1,139 @@
+# A class containing helper methods to aid the generation of HTML
+# given formatted data
+class HTMLHelper
+
+  # Generates the HTML to format the relevant data about return values
+  def generate_return_types(types, desc = nil)
+    result = []
+
+    result << "(<span class=\"type\"><tt>" << types.join(", ") << "</tt></span>)"
+
+    if !desc.nil?
+      result << "- <div class=\"inline\"><p>#{desc}</p></div>"
+    end
+
+    result.join
+  end
+
+  def generate_features features, object
+    result = []
+
+    if features
+      features.each do |feat|
+        result << "<li>"
+        result << "<span class=\"name\">#{feat[:name]} </span>"
+        if feat[:desc]
+          result << "- <br/><div class=\"inline\"><p> #{feat[:desc]} </p></div>"
+        end
+        if feat[:methods]
+          result << "<h3> Methods </h3>"
+          result << "<ul>"
+          feat[:methods].each do |method|
+            result << "<li> <tt>" << method << "</tt> </li>"
+          end
+          result << "</ul>"
+        end
+        result << "</li>"
+      end
+    end
+    result.join
+  end
+
+  # Generates the HTML to format the relevant data about parameters
+  def generate_parameters(params, object)
+    result = []
+
+    params.each do |param|
+      result << "<li>"
+
+      # Parameters which are documented in the comments but not
+      # present in the code itself are given the strike through
+      # styling in order to show the reader that they do not actually
+      # exist
+      if !param[:exists?]
+        result << "<strike>"
+      end
+
+      result << "<span class=\"name\">#{param[:name]} </span>"
+      result << "<span class=\"type\">"
+
+      # If the docstring specifies types, use those
+      if param[:types]
+        result << "(" << "<tt>" << param[:types].join(", ") << "</tt>" << ")"
+      # Otherwise, if typing information could be extracted from the object
+      # itself, use that
+      elsif object.type_info
+        # If the parameter name includes the default value, scrub that.
+        if param[:name].match(/([^=]*)=/)
+          param_name = $1
+        else
+          param_name = param[:name]
+        end
+        # Collect all the possible types from the object. If no such type
+        # exists for this parameter name don't do anything.
+        possible_types = object.type_info.map {
+          |sig| sig[param_name] or nil
+        }.compact
+
+        # If no possible types could be determined, put the type down as
+        # Unknown
+        if possible_types == []
+          result << "(" << "<tt>Unknown</tt>" << ")"
+        else
+          result << "(" << "<tt>" << possible_types.join(", ") << "</tt>" << ")"
+        end
+      # Give up. It can probably be anything.
+      elsif not (param[:puppet_3_func] or param[:puppet_type])
+        result << "(<tt>Unknown</tt>)"
+      end
+      if param[:puppet_type] and param[:parameter]
+        result << "(Parameter) "
+      elsif param[:puppet_type] and param[:property]
+        result << "(Property) "
+      end
+
+      if param[:namevar]
+        result << "(Namevar) "
+      end
+      if param[:default]
+        result << " Default value: <tt>" << param[:default] << "</tt> "
+      end
+
+      result << "</span>"
+
+      # This is only relevant for manifests, not puppet functions
+      # This is due to the fact that the scope of a parameter (as illustrated by
+      # by it's fully qualified name) is not relevant for the parameters in puppet
+      # functions, but may be for components of a manifest (i.e. classes)
+      unless param[:fq_name].nil?
+        result << "<tt> => #{param[:fq_name]}</tt>"
+      end
+
+      if param[:desc]
+        result << " - <div class=\"inline\"><p> #{param[:desc]} </p></div>"
+      end
+
+      if !param[:exists?]
+        result << "</strike>"
+      end
+
+      if param[:allowed_values] and param[:allowed_values] != []
+        result << "\n<b> Allowed Values: </b>"
+        result << "<ul>"
+        param[:allowed_values].each do |value_thing|
+          result << "<li>"
+          result << "<tt>" << value_thing.first << "</tt>"
+          if value_thing[1]
+            result <<  " only available if " << "<tt>" << value_thing[1] << "</tt>"
+          end
+          result << "</li>"
+        end
+        result << "</ul>\n"
+      end
+
+      result << "</li>"
+    end
+
+    result.join
+  end
+end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/layout/html/setup.rb

@@ -0,0 +1,18 @@
+# TODO: This should be extendable. However, the re-assignment of
+# @objects_by_letter prevents that. Submit a pull request.
+def index
+  @objects_by_letter = {}
+  objects = Registry.all(:class, :module, :type, :puppetnamespace, :hostclass, :definedtype, :provider).sort_by {|o| o.name.to_s }
+  objects = run_verifier(objects)
+  objects.each {|o| (@objects_by_letter[o.name.to_s[0,1].upcase] ||= []) << o }
+  erb(:index)
+end
+
+def menu_lists
+  [
+    {:type => 'puppet_manifest', :title => 'Puppet Manifests', :search_title => "Puppet Manifest List"},
+    {:type => 'puppet_plugin', :title => 'Puppet Plugins', :search_title => "Puppet Plugin List"},
+    {:type => 'puppet_type', :title => 'Puppet Types', :search_title => "Puppet Type List"},
+    {:type => 'puppet_provider', :title => 'Puppet Providers', :search_title => "Puppet Provider List"},
+  ] + super
+end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/method_details/html/header.erb

@@ -0,0 +1,17 @@
+<h1>Method: <%= object.path %></h1>
+<div class="box_info">
+  <dl>
+    <dt class="">Defined in:</dt>
+    <dd class="">
+    <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+    <% end %>
+    </dd>
+  </dl>
+</div>
+
+<div class="method_details_list">
+  <div id="method_details">
+    <%= yieldall :index => 0 %>
+  </div>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/method_details/setup.rb

@@ -0,0 +1,21 @@
+include T('default/module')
+require File.join(File.dirname(__FILE__),'../html_helper')
+require File.join(File.dirname(__FILE__),'../template_helper')
+
+def init
+  sections :header, [:method_signature, T('docstring'), :source]
+  parents = YARD::Registry.all(:method).reject do |item|
+    item.name == object.name and item.namespace === PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject
+  end
+  if parents.length == 0
+    @template_helper = TemplateHelper.new
+    @template_helper.check_parameters_match_docs object
+  end
+end
+
+def source
+  return if owner != object.namespace
+  return if Tags::OverloadTag === object
+  return if object.source.nil?
+  erb(:source)
+end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/method_details/text/header.erb

@@ -0,0 +1,2 @@
+<%= yieldall %>
+

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/command_details.erb

@@ -0,0 +1,8 @@
+<h2>Commands Summary</h2>
+<div class="tags">
+  <ul class="command">
+    <% @command_details.each do |command| %>
+         <li><tt><%= command %></tt></li>
+    <% end %>
+  </ul>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/confine_details.erb

@@ -0,0 +1,10 @@
+<h2>Confines</h2>
+<% if @confine_details  != {} %>
+<div class="tags">
+  <ul class="command">
+    <% @confine_details.each_pair do |key, value| %>
+         <li><tt><%= key %> - <%= value %></tt></li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/default_details.erb

@@ -0,0 +1,10 @@
+<h2>Defaults</h2>
+<% if @default_details  != {} %>
+<div class="tags">
+  <ul class="command">
+    <% @default_details.each_pair do |key, value| %>
+         <li><tt><%= key %> - <%= value %></tt></li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/docstring.erb

@@ -0,0 +1,34 @@
+<div class="docstring">
+  <div class="discussion">
+    <p><%= htmlify(Puppet::Util::Docs::scrub(@class_details[:desc])) %></p>
+  </div>
+</div>
+<div class="tags">
+  <% if @class_details[:examples] != {}%>
+    <div class="examples">
+    <p class="tag_title">Examples:</p>
+    <% @class_details[:examples].each do |title, text| %>
+      <div class="inline"><p><%= title %></p></div>
+      <pre class="example code"><code><span><%= text %></span></code></pre>
+    <% end %>
+    </div>
+  <% end %>
+  <% if @class_details[:since] %>
+    <p class="tag_title">Since:</p>
+    <ul class="since">
+      <li>
+        <div class="inline">
+          <p><%= @class_details[:since] %></p>
+        </div>
+      </li>
+    </ul>
+  <% end %>
+  <% if @class_details[:return] %>
+    <p class="tag_title">Return:</p>
+    <ul class="return">
+      <li>
+        <%= @html_helper.generate_return_types(@class_details[:return][1], @class_details[:return][0]) %>
+      </li>
+    </ul>
+  <% end %>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/feature_details.erb

@@ -0,0 +1,10 @@
+<h2>Features</h2>
+<% if @feature_details  != [] %>
+<div class="tags">
+  <ul class="command">
+    <% @feature_details.each do |feature| %>
+         <li><tt><%= feature %></tt></li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/header.erb

@@ -0,0 +1,5 @@
+<div class='module_header'>
+  <h1>
+    <%= @header_text %>
+  </h1>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/setup.rb

@@ -0,0 +1 @@
+include T('default/module/html')

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/setup.rb

@@ -0,0 +1,50 @@
+include T('default/module')
+
+require File.join(File.dirname(__FILE__),'../html_helper')
+require File.join(File.dirname(__FILE__),'../template_helper')
+
+def init
+  sections :header, :box_info, :pre_docstring, :docstring, :command_details, :confine_details, :default_details, :feature_details
+
+  @template_helper = TemplateHelper.new
+  @html_helper = HTMLHelper.new
+end
+
+def header
+  @header_text = object.header_name
+
+  erb(:header)
+end
+
+def command_details
+  @command_details = object.commands
+  erb(:command_details)
+end
+
+def confine_details
+  @confine_details = object.confines
+  erb(:confine_details)
+end
+
+def default_details
+  @default_details = object.defaults
+  erb(:default_details)
+end
+
+def feature_details
+  @feature_details = object.features
+  erb(:feature_details)
+end
+
+def header
+  @header_text = "Puppet Provider: #{object.name}"
+
+  erb(:header)
+end
+
+def docstring
+
+  @class_details = @template_helper.extract_tag_data(object)
+
+  erb(:docstring)
+end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/box_info.erb

@@ -0,0 +1,11 @@
+<dl class="box">
+  <dt class="r1 last" style="height: 16px;">Defined in:</dt>
+  <dd class="r1 last">
+  <% @source_files.each do |file| %>
+    <em><%= file[0] %></em>:
+    <%= file[1] %>
+    <br/>
+  <% end %>
+  </dd>
+</dl>
+<div class ="clear"></div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/header.erb

@@ -0,0 +1,5 @@
+<div class='module_header'>
+  <h1>
+    <%= @header_text %>
+  </h1>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_details_list.erb

@@ -0,0 +1,53 @@
+<h2>Function Details</h2>
+<% @class_details.each do |func| %>
+  <h3 class="signature" id = <%= "#{func[:name]}-instance_method" %>>
+    <strong>
+      <% if func[:return] %>
+        <%= @html_helper.generate_return_types(func[:return][1]) %>
+      <% end %>
+      <%= func[:name] %>
+    </strong>
+  </h3>
+  <div class="docstring">
+    <div class="discussion">
+      <p><%= htmlify(func[:desc]) %></p>
+    </div>
+  </div>
+  <div class="tags">
+    <% if func[:examples] != {}%>
+      <div class="examples">
+        <p class="tag_title">Examples:</p>
+        <% func[:examples].each do |title, text| %>
+          <div class="inline"><p><%= title %></p></div>
+          <pre class="example code"><code><span><%= text %></span></code></pre>
+        <% end %>
+      </div>
+    <% end %>
+    <% if func[:since] %>
+      <p class="tag_title">Since:</p>
+      <ul class="since">
+        <li>
+          <div class="inline">
+            <p><%= func[:since] %></p>
+          </div>
+        </li>
+      </ul>
+    <% end %>
+    <% if func[:return] %>
+      <p class="tag_title">Returns:</p>
+      <ul class="return">
+        <li>
+          <%= @html_helper.generate_return_types(func[:return][1], func[:return][0]) %>
+        </li>
+      </ul>
+    <% end %>
+    <% if func[:params] != nil %>
+      <p class="tag_title">Parameters:</p>
+      <div class="tags">
+        <ul class="param">
+          <%= @html_helper.generate_parameters(func[:params], object.child) %>
+        </ul>
+      </div>
+    <% end %>
+  </div>
+<% end %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb

@@ -0,0 +1,20 @@
+<h2>Available Functions</h2>
+<ul class="summary">
+  <% @method_details.each do |method| %>
+    <li class = "private">
+      <span class = "summary_signature">
+      <a href =<%= "##{method[:name]}-instance_method"%>>
+          <% if ! method[:return_types].nil? %>
+            <%= @html_helper.generate_return_types(method[:return_types]) %>
+          <% end %>
+        -
+       <strong><%= method[:name] %></strong>
+      </span>
+    </li></a>
+    <span class = "summary_desc">
+      <div class = "inline">
+        <p><%= method[:short_desc] %></p>
+      </div>
+    </span>
+  <% end %>
+</ul>