puppet-strings 0.4.0 → 0.99.0

data/lib/puppet-strings/yard/tags/parameter_directive.rb

@@ -0,0 +1,24 @@
+require 'puppet-strings/yard/code_objects'
+
+# Implements a parameter directive (e.g. #@!puppet.type.param) for documenting Puppet resource types.
+class PuppetStrings::Yard::Tags::ParameterDirective < YARD::Tags::Directive
+  # Called to invoke the directive.
+  # @return [void]
+  def call
+    return unless object && object.respond_to?(:add_parameter)
+    # Add a parameter to the resource
+    parameter = PuppetStrings::Yard::CodeObjects::Type::Parameter.new(tag.name, tag.text)
+    if tag.types
+      tag.types.each do |value|
+        parameter.add(value)
+      end
+    end
+    object.add_parameter parameter
+  end
+
+  # Registers the directive with YARD.
+  # @return [void]
+  def self.register!
+    YARD::Tags::Library.define_directive('puppet.type.param', :with_types_and_name, self)
+  end
+end

data/lib/puppet-strings/yard/tags/property_directive.rb

@@ -0,0 +1,24 @@
+require 'puppet-strings/yard/code_objects'
+
+# Implements a parameter directive (e.g. #@!puppet.type.property) for documenting Puppet resource types.
+class PuppetStrings::Yard::Tags::PropertyDirective < YARD::Tags::Directive
+  # Called to invoke the directive.
+  # @return [void]
+  def call
+    return unless object && object.respond_to?(:add_property)
+    # Add a property to the resource
+    property = PuppetStrings::Yard::CodeObjects::Type::Property.new(tag.name, tag.text)
+    if tag.types
+      tag.types.each do |value|
+        property.add(value)
+      end
+    end
+    object.add_property property
+  end
+
+  # Registers the directive with YARD.
+  # @return [void]
+  def self.register!
+    YARD::Tags::Library.define_directive('puppet.type.property', :with_types_and_name, self)
+  end
+end

data/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_class.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_defined_type.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_function.erb

@@ -0,0 +1,10 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(false)) %>
+        <small><%= item.function_type %></small>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_provider.erb

@@ -0,0 +1,10 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+        <small>Resource type: <em><%=item.type_name%></em></small>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_type.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb

@@ -0,0 +1,64 @@
+# Generates the searchable Puppet class list.
+# @return [void]
+def generate_puppet_class_list
+  @items = Registry.all(:puppet_class).sort_by { |c| c.name.to_s }
+  @list_title = 'Puppet Class List'
+  @list_type = 'puppet_class'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet defined type list.
+# @return [void]
+def generate_puppet_defined_type_list
+  @items = Registry.all(:puppet_defined_type).sort_by {|dt| dt.name.to_s }
+  @list_title = 'Defined Type List'
+  @list_type = 'puppet_defined_type'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet resource type list.
+# @return [void]
+def generate_puppet_type_list
+  @items = Registry.all(:puppet_type).sort_by {|t| t.name.to_s }
+  @list_title = 'Resource Type List'
+  @list_type = 'puppet_type'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet provider list.
+# @return [void]
+def generate_puppet_provider_list
+  @items = Registry.all(:puppet_provider).sort_by {|p| p.name.to_s }
+  @list_title = 'Provider List'
+  @list_type = 'puppet_provider'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet function list.
+# @return [void]
+def generate_puppet_function_list
+  @items = Registry.all(:puppet_function).sort_by {|f| f.name.to_s }
+  @list_title = 'Puppet Function List'
+  @list_type = 'puppet_function'
+  generate_list_contents
+end
+
+# Generates the searchable Ruby method list.
+# @return [void]
+def generate_method_list
+  @items = prune_method_listing(Registry.all(:method), false)
+  @items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? }
+  @items = @items.sort_by {|m| m.name.to_s }
+  @list_title = 'Ruby Method List'
+  @list_type = 'method'
+  generate_list_contents
+end
+
+# Generate a searchable Ruby class list in the output.
+# @return [void]
+def generate_class_list
+  @items = options.objects if options.objects
+  @list_title = 'Ruby Class List'
+  @list_type = 'class'
+  generate_list_contents
+end

data/lib/puppet-strings/yard/templates/default/layout/html/objects.erb

@@ -0,0 +1,35 @@
+<% unless @objects_by_letter.empty? %>
+<h2><%= @title %></h2>
+
+  <% i = 0 %>
+<table>
+  <tr>
+    <td valign='top' width="33%">
+  <% @objects_by_letter.sort_by {|l,o| l.to_s }.each do |letter, objects| %>
+    <% if (i += 1) % 8 == 0 %>
+    </td>
+    <td valign='top' width="33%">
+      <% i = 0 %>
+    <% end %>
+      <ul id="alpha_<%= letter %>" class="alpha">
+        <li class="letter"><%= letter %></li>
+          <ul>
+    <% objects.each do |obj| %>
+            <li>
+      <%= linkify obj, obj.name %>
+      <% if (obj.type == :module || obj.type == :class) && !obj.namespace.root? %>
+              <small>(<%= obj.namespace.path %>)</small>
+      <% elsif obj.type == :puppet_provider %>
+              <small>(Resource type: <%= obj.type_name %>)</small>
+      <% elsif obj.type == :puppet_function %>
+              <small>(<%= obj.function_type %>)</small>
+      <% end %>
+            </li>
+    <% end %>
+      </ul>
+    </ul>
+  <% end %>
+    </td>
+  </tr>
+</table>
+<% end %>

data/lib/puppet-strings/yard/templates/default/layout/html/setup.rb

@@ -0,0 +1,172 @@
+# Initializes the template.
+# @return [void]
+def init
+  case object
+  when '_index.html'
+    @page_title = options.title
+    sections :layout, [:index, [:listing, [:classes, :defined_types, :types, :providers, :functions, :files, :objects]]]
+  else
+    super
+  end
+end
+
+# Renders the layout section.
+# @return [String] Returns the rendered section.
+def layout
+  @nav_url = url_for_list(!@file || options.index ? menu_lists.first[:type] : 'file')
+
+  case object
+  when nil, String
+    @path = nil
+  when @file
+    @path = @file.path
+  when !object.is_a?(YARD::CodeObjects::NamespaceObject)
+    @path = object.parent.path
+    @nav_url = url_for_list('class')
+  when YARD::CodeObjects::ClassObject
+    @path = object.path
+    @nav_url = url_for_list('class')
+  when PuppetStrings::Yard::CodeObjects::Class
+    @nav_url = url_for_list('puppet_class')
+    @page_title = "Puppet Class: #{object.name}"
+    @path = object.path
+  when PuppetStrings::Yard::CodeObjects::DefinedType
+    @nav_url = url_for_list('puppet_defined_type')
+    @page_title = "Defined Type: #{object.name}"
+    @path = object.path
+  when PuppetStrings::Yard::CodeObjects::Type
+    @nav_url = url_for_list('puppet_type')
+    @page_title = "Resource Type: #{object.name}"
+    @path = object.path
+  when PuppetStrings::Yard::CodeObjects::Provider
+    @nav_url = url_for_list('puppet_provider')
+    @page_title = "Provider: #{object.name}"
+    @path = object.path
+  when PuppetStrings::Yard::CodeObjects::Function
+    @nav_url = url_for_list('puppet_function')
+    @page_title = "Puppet Function: #{object.name} (#{object.function_type})"
+    @path = object.path
+  else
+    @path = object.path
+  end
+
+  erb(:layout)
+end
+
+# Creates the dynamic menu lists.
+# @return [Array<Hash>] Returns the dynamic menu list.
+def create_menu_lists
+  menu_lists = [
+    {
+      type: 'puppet_class',
+      title: 'Puppet Classes',
+      search_title: 'Puppet Classes'
+    },
+    {
+      type: 'puppet_defined_type',
+      title: 'Defined Types',
+      search_title: 'Defined Types',
+    },
+    {
+      type: 'puppet_type',
+      title: 'Resource Types',
+      search_title: 'Resource Types'
+    },
+    {
+      type: 'puppet_provider',
+      title: 'Providers',
+      search_title: 'Providers'
+    },
+    {
+      type: 'puppet_function',
+      title: 'Puppet Functions',
+      search_title: 'Puppet Functions'
+    },
+    {
+      type: 'class',
+      title: 'Ruby Classes',
+      search_title: 'Class List'
+    },
+    {
+      type: 'method',
+      title: 'Ruby Methods',
+      search_title: 'Method List'
+    },
+  ]
+
+  menu_lists.delete_if { |e| YARD::Registry.all(e[:type].intern).empty? }
+
+  # We must always return at least one group, so always keep the files list
+  menu_lists << {
+    type: 'file',
+    title: 'Files',
+    search_title: 'File List'
+  } if menu_lists.empty? || !YARD::Registry.all(:file).empty?
+
+  menu_lists
+end
+
+# Gets the menu lists to use.
+# @return [Array<Hash] Returns the menu lists to use.
+def menu_lists
+  @@lists ||= create_menu_lists.freeze
+end
+
+# Builds a list of objects by letter.
+# @param [Array] types The types of objects to find.
+# @return [Hash] Returns a hash of first letter of the object name to list of objects.
+def objects_by_letter(*types)
+  hash = {}
+  objects = Registry.all(*types).sort_by {|o| o.name.to_s }
+  objects = run_verifier(objects)
+  objects.each {|o| (hash[o.name.to_s[0,1].upcase] ||= []) << o }
+  hash
+end
+
+# Renders the classes section.
+# @return [String] Returns the rendered section.
+def classes
+  @title = 'Puppet Class Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_class)
+  erb(:objects)
+end
+
+# Renders the defined types section.
+# @return [String] Returns the rendered section.
+def defined_types
+  @title = 'Defined Type Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_defined_type)
+  erb(:objects)
+end
+
+# Renders the types section.
+# @return [String] Returns the rendered section.
+def types
+  @title = 'Resource Type Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_type)
+  erb(:objects)
+end
+
+# Renders the providers section.
+# @return [String] Returns the rendered section.
+def providers
+  @title = 'Puppet Provider Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_provider)
+  erb(:objects)
+end
+
+# Renders the functions section.
+# @return [String] Returns the rendered section.
+def functions
+  @title = 'Puppet Function Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_function)
+  erb(:objects)
+end
+
+# Renders the objects section.
+# @return [String] Returns the rendered section.
+def objects
+  @title = 'Ruby Namespace Listing A-Z'
+  @objects_by_letter = objects_by_letter(:class, :module)
+  erb(:objects)
+end

data/lib/puppet-strings/yard/templates/default/puppet_class/html/box_info.erb

@@ -0,0 +1,26 @@
+<div class="box_info">
+  <% if object.statement.parent_class %>
+  <dl>
+    <dt>Inherits:</dt>
+    <dd><%= linkify(Registry["puppet_classes::#{object.statement.parent_class}"], object.statement.parent_class.dup) %></dd>
+  </dl>
+  <% end %>
+  <% if @subclasses && !@subclasses.empty? %>
+  <dl>
+    <dt>Inherited by:</dt>
+    <dd>
+      <% @subclasses.each do |subclass| %>
+      <%= linkify(subclass, subclass.name.to_s) %><br/>
+      <% end %>
+    </dd>
+  </dl>
+  <% end %>
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= 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>

data/lib/puppet-strings/yard/templates/default/puppet_class/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Class: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_class/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_class/html/setup.rb

@@ -0,0 +1,14 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :overview, T('tags'), :source
+end
+
+# Renders the box_info section.
+# @return [String] Returns the rendered section.
+def box_info
+  @subclasses = Registry.all(:puppet_class).find_all { |c|
+    c.statement.parent_class == object.name.to_s
+  }
+  erb(:box_info)
+end

data/lib/puppet-strings/yard/templates/default/puppet_class/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>