kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

(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.
This commit is contained in:
Hailee Kenney 2015-01-08 14:58:21 -08:00
parent 345d72b2d7
commit 5f60c99bfd
5 changed files with 257 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/box_info.erb Normal file
View File

@ -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>

95
lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb Normal file
View File

@ -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 %>

5
lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/header.erb Normal file
View File

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

28
lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb Normal file
View File

@ -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>

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

@ -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