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

(PDOC-17) Add support for YARD tags in puppet code 

Prior to this commit, most of the HTML created for documenting
puppet code was auto-generated by YARD, meaning that it was not
always presented in a way that was consistent or easy to read.

Now we are explicitly defining the HTML and styling that we want
to use when generating documentation for defined types and classes.
This means that we can define exactly how we want the output to look
so that is more compatible with puppet code.
This commit is contained in:
Hailee Kenney 2014-11-17 11:03:57 -08:00
parent 78ba39b08b
commit de3c1e776d
3 changed files with 114 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -0,0 +1,51 @@
<h3 class="signature first"> Class: <%= @class_details[:name] %></h3>
<div class="docstring">
<div class="discussion">
<p><%= @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>
<span class ="type">
<% if !@class_details[:return][1].nil? %>
(<tt>
<% @class_details[:return][1].each do |type| %>
<%= type %>
<% if @class_details[:return][1].last != type %>
,
<% end %>
<% end %>
</tt>) —
<% end %>
</span>
<% if !@class_details[:return][0].nil? %>
<div class="inline">
<p><%= @class_details[:return][0] %></p>
</div>
<% end %>
</li>
</ul>
<% end %>
</div>

48
lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb
View File

@ -1,18 +1,32 @@
<h2>Parameter Summary<small>(<a href="#" class="summary_toggle">collapse</a>)</small></h2>
<ul class="summary">
<% object.parameters.each do |param| %>
<li>
<a href="#">
<span class="summary_signature">
-
<strong><%= h param[0] %></strong>
<% unless param[1].nil? %>
<%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %>
=> <%= h param[1] %>
<h2>Parameter Summary</h2>
<div class="tags">
<ul class="param">
<% @param_details.each do |param| %>
<li>
<span class="name"><%= param[:name] %></span>
<% unless param[:module].nil? %>
<%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %>
<% if param[:types] %>
<span class="type">
( <% param[:types].each do |type| %>
<tt>
<%= type %>
<% if param[:types].last != type %>
,
<% end %>
</tt>
<% end %>)
</span>
<% end %>
</span>
<%# TODO: Grab onto @param tags and insert text/type. %>
</a>
</li>
<% end %>
</ul>
<tt><%= "=> #{param[:module]}" %></tt>
<% end %>
<% if param[:desc]%>
—
<div class="inline">
<p><%= param[:desc] %></p>
</div>
<% end %>
</li>
<% end %>
</ul>
</div>

33
lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
View File

@ -1,10 +1,41 @@
include T('default/module')
def init
sections :header, :box_info, :pre_docstring, T('docstring'), :parameter_details
sections :header, :box_info, :pre_docstring, :docstring, :parameter_details
end
def parameter_details
return if object.parameters.empty?
param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
params = object.parameters
@param_details = []
params.zip(param_tags).each do |param, tag|
description = tag.nil? ? nil : tag.text
param_types = tag.nil? ? nil : tag.types
@param_details.push({:name => param[0], :module => param[1], :desc => description, :types => param_types})
end
erb(:parameter_details)
end
def docstring
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
@class_details = {:name => object.name, :desc => object.docstring, :examples => examples, :since => since_text, :return => return_details}
erb(:docstring)
end