(PDOC-24) Add custom header for puppet functions

Prior to this commit, all the HTML for puppet functions was just
generated by YARD as if it were a regular method. Since we ultimately
want to have our own custom templates, lay out the groundwork for customizing
the templates for functions and update the page headers to be more
readable.

At the moment the code is functional but contains a lot of duplication which
needs to be cleaned up.

lib/puppetx/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>

lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb

@@ -0,0 +1,95 @@
+<% @class_details.each do |func| %>
+  <h3 class="signature" id = <%= "#{func[:name]}-instance_method" %>>
+    <strong><%= 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>
+          <span class ="type">
+            <% if !func[:return][1].nil? %>
+              (<tt>
+                <% func[:return][1].each do |type| %>
+                  <%= type %>
+                  <% if func[:return][1].last != type %>
+                    ,
+                  <% end %>
+                <% end %>
+              </tt>) —
+            <% end %>
+          </span>
+          <% if !func[:return][0].nil? %>
+            <div class="inline">
+              <p><%= func[:return][0] %></p>
+            </div>
+          <% end %>
+        </li>
+      </ul>
+    <% end %>
+    <% if func[:params] != nil %>
+      <p class="tag_title">Parameters:</p>
+      <div class="tags">
+        <ul class="param">
+          <% func[:params].each do |param| %>
+            <li>
+              <% if !param[:exists?] %>
+                <strike>
+              <% end %>
+              <span class="name"><%= param[:name] %></span>
+              <%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %>
+              <span class="type">
+                <% if param[:types] %>
+                  (<%  param[:types].each do |type| %>
+                    <tt>
+                      <% if param[:types].last != type %>
+                        <%= type %>,
+                      <% else %>
+                        <%= type %>
+                      <% end %>
+                    </tt>
+                  <% end %>)
+                <% else %>
+                  <tt>(TBD)</tt>
+                <% end %>
+              </span>
+              <% if param[:desc]%>
+                —
+                <div class="inline">
+                  <p><%=  param[:desc] %></p>
+                </div>
+              <% end %>
+              <% if !param[:exists] %>
+                </strike>
+              <% end %>
+            </li>
+          <% end %>
+        </ul>
+      </div>
+    <% end %>
+  </div>
+<% end %>

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

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

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

@@ -0,0 +1,28 @@
+<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"%>>
+        <span class ="type">
+          <% if ! method[:return_types].nil? %>
+            (<tt>
+              <% method[:return_types].each do |type| %>
+                <%= type %>
+                <% if method[:return_types].last != type %>
+                  ,
+                <% end %>
+              <% end %>
+            </tt>) —
+          <% end %>
+        </span>
+       <strong><%= method[:name] %></strong>
+      </span>
+    </li></a>
+    <span class = "summary_desc">
+      <div class = "inline">
+        <p><%= method[:short_desc] %></p>
+      </div>
+    </span>
+  <% end %>
+</ul>

lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb

@@ -3,5 +3,122 @@ include T('default/module')
 def init
   sections :header, :box_info, :pre_docstring, T('docstring'),
     :method_summary, [:item_summary],
-    :method_details_list, [T('method_details')]
+    :method_details_list, :method_details
+
+  @methods = object.children
+end
+
+def header
+  if @methods[0]['puppet_4x_function']
+    @header_text = "Puppet 4 Functions"
+  else
+    @header_text = "Puppet 3 Functions"
+  end
+
+  erb(:header)
+end
+
+def box_info
+  @source_files = []
+
+  @methods.each do |method|
+   # extract the file name and line number for each method
+    file_name = method.files[0][0]
+    line_number = method.files[0][1]
+
+    @source_files.push([method.name, "#{file_name} (#{line_number})"])
+  end
+
+  erb(:box_info)
+end
+
+def method_summary
+  @method_details = []
+
+  @methods.each do |method|
+    # If there are multiple sentences in the method description, only
+    # use the first one for the summary. If the author did not include
+    # any periods in their summary, include the whole thing
+    first_sentence = method.docstring.match(/^(.*?)\./)
+    brief_summary = first_sentence ? first_sentence : method.docstring
+
+    return_tag = method.tags.find { |tag| tag.tag_name == "return"}
+    return_types = return_tag.nil? ? nil : return_tag.types
+
+    @method_details.push({:name => method.name, :short_desc => brief_summary, :return_types => return_types})
+  end
+
+  erb(:method_summary)
+end
+
+def method_details
+  @class_details = []
+
+  @methods.each do |object|
+    examples = Hash.new
+    example_tags = object.tags.find_all { |tag| tag.tag_name == "example" }
+    example_tags.each do |example|
+      examples["#{example.name}"] = example.text
+    end
+
+    return_tag = object.tags.find { |tag| tag.tag_name == "return"}
+    return_text = return_tag.nil? ? nil : return_tag.text
+    return_types = return_tag.nil? ? nil : return_tag.types
+    return_details = (return_text.nil? && return_types.nil?) ? nil : [return_text, return_types]
+
+    since_tag = object.tags.find { |tag| tag.tag_name == "since"}
+    since_text = since_tag.nil? ? nil : since_tag.text
+
+    param_details = nil
+
+    if object['puppet_4x_function']
+      param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
+
+      # Extract the source code
+      source_code = object.source
+      # Extract the parameters for the source code
+      parameters = source_code.match(/(?:def .*)\((.*?)\)/)
+      # Convert the matched string into an array of strings
+      params = parameters.nil? ? nil :  parameters[1].split(/\s*,\s*/)
+
+      param_details = extract_param_details(params, param_tags)
+    end
+
+    @class_details.push({:name => object.name, :desc => object.docstring, :examples => examples, :since => since_text, :return => return_details, :params => param_details})
+  end
+
+  erb(:docstring)
+end
+
+def extract_param_details(params_array, tags_hash)
+  if params_array.nil?
+    return
+  end
+
+  parameter_info = []
+
+  # Extract the information for parameters that actually exist
+  params_array.each do |param|
+    param_tag = tags_hash.find { |tag| tag.name == param }
+
+    description = param_tag.nil? ? nil : param_tag.text
+    param_types = param_tag.nil? ? nil : param_tag.types
+
+    parameter_info.push({:name => param, :desc => description, :types => param_types, :exists? => true})
+  end
+
+  # Check if there were any comments for parameters that do not exist
+  tags_hash.each do |tag|
+    param_exists = false
+    parameter_info.each do |parameter|
+      if parameter[:name] == tag.name
+        param_exists = true
+      end
+    end
+    if !param_exists
+      parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => false})
+    end
+  end
+
+  parameter_info
 end