From 5f60c99bfdfdf237d9b3076858d9d7ff6d231f69 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Thu, 8 Jan 2015 14:58:21 -0800 Subject: [PATCH] (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. --- .../default/puppetnamespace/html/box_info.erb | 11 ++ .../puppetnamespace/html/docstring.erb | 95 ++++++++++++++ .../default/puppetnamespace/html/header.erb | 5 + .../puppetnamespace/html/method_summary.erb | 28 +++++ .../default/puppetnamespace/setup.rb | 119 +++++++++++++++++- 5 files changed, 257 insertions(+), 1 deletion(-) create mode 100644 lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/box_info.erb create mode 100644 lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb create mode 100644 lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/header.erb create mode 100644 lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/box_info.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/box_info.erb new file mode 100644 index 0000000..1780c32 --- /dev/null +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/box_info.erb @@ -0,0 +1,11 @@ +
+
Defined in:
+
+ <% @source_files.each do |file| %> + <%= file[0] %>: + <%= file[1] %> +
+ <% end %> +
+
+
diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb new file mode 100644 index 0000000..cb5110a --- /dev/null +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb @@ -0,0 +1,95 @@ +<% @class_details.each do |func| %> +

> + <%= func[:name] %> +

+
+
+

<%= htmlify(func[:desc]) %>

+
+
+
+ <% if func[:examples] != {}%> +
+

Examples:

+ <% func[:examples].each do |title, text| %> +

<%= title %>

+ 
<%= text %>
+ <% end %> +
+ <% end %> + <% if func[:since] %> +

Since:

+ + <% end %> + <% if func[:return] %> +

Returns:

+ + <% end %> + <% if func[:params] != nil %> +

Parameters:

+
+
    + <% func[:params].each do |param| %> +
  • + <% if !param[:exists?] %> + + <% end %> + <%= param[:name] %> + <%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %> + + <% if param[:types] %> + (<% param[:types].each do |type| %> + + <% if param[:types].last != type %> + <%= type %>, + <% else %> + <%= type %> + <% end %> + + <% end %>) + <% else %> + (TBD) + <% end %> + + <% if param[:desc]%> + — +
    +

    <%= param[:desc] %>

    +
    + <% end %> + <% if !param[:exists] %> +     + <% end %> +
    • + <% end %> +
+
+ <% end %> +
+<% end %> diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/header.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/header.erb new file mode 100644 index 0000000..74b3dba --- /dev/null +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/header.erb @@ -0,0 +1,5 @@ +
+

+ <%= @header_text %> +

+
diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb new file mode 100644 index 0000000..6d61392 --- /dev/null +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb @@ -0,0 +1,28 @@ +

Available Functions

+ diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb index cf37b36..a310566 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb +++ b/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