openvox-strings 5.0.0

data/lib/openvox-strings/yard/templates/default/puppet_function/html/setup.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, [:note, :todo, :deprecated, T('tags'), :source]
+end

data/lib/openvox-strings/yard/templates/default/puppet_function/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>

data/lib/openvox-strings/yard/templates/default/puppet_function/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_function/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_plan/html/box_info.erb

@@ -0,0 +1,10 @@
+<div class="box_info">
+  <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/openvox-strings/yard/templates/default/puppet_plan/html/deprecated.erb

@@ -0,0 +1,6 @@
+<% object.tags(:deprecated).each do |tag| %>
+  <div class="note deprecated">
+    <strong>DEPRECATED:</strong>
+    <%= htmlify_line deprecated.text %>
+  </div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_plan/html/header.erb

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

data/lib/openvox-strings/yard/templates/default/puppet_plan/html/note.erb

@@ -0,0 +1,6 @@
+<% object.tags(:note).each do |tag| %>
+  <div class="note notetag">
+    <strong>Note:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_plan/html/overview.erb

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

data/lib/openvox-strings/yard/templates/default/puppet_plan/html/setup.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, :note, :todo, :deprecated, T('tags'), :source
+end
+
+# Renders the box_info section.
+# @return [String] Returns the rendered section.
+def box_info
+  erb(:box_info)
+end

data/lib/openvox-strings/yard/templates/default/puppet_plan/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>

data/lib/openvox-strings/yard/templates/default/puppet_plan/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_plan/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_provider/html/box_info.erb

@@ -0,0 +1,14 @@
+<div class="box_info">
+  <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>
+  <dl>
+    <dt>Resource type:</dt>
+    <dd><%= linkify(Registry["puppet_types::#{object.type_name}"], object.type_name) %></dd>
+  </dl>
+</div>

data/lib/openvox-strings/yard/templates/default/puppet_provider/html/collection.erb

@@ -0,0 +1,17 @@
+<% if @collection && !@collection.empty? %>
+<div class="tags">
+  <p class="tag_title"><%= @title %></p>
+  <ul>
+
+  <% if @collection.is_a?(Hash) %>
+    <% @collection.each do |key, value| %>
+      <li><tt><%= key %> &mdash; <%= value %></tt></li>
+    <% end %>
+  <% elsif @collection.is_a?(Array) %>
+    <% @collection.each do |kvps| %>
+      <li><tt><%=  kvps.map{|k,v| "#{k} &mdash; #{v}"}.join(', ') %></tt></li>
+    <% end %>
+  <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_provider/html/features.erb

@@ -0,0 +1,12 @@
+<% if object.features && !object.features.empty? %>
+<div class="tags">
+  <p class="tag_title">Features</p>
+  <ul>
+    <% object.features.each do |feature| %>
+    <li>
+      <span class="name"><%= feature %></span>
+    </li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_provider/html/header.erb

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

data/lib/openvox-strings/yard/templates/default/puppet_provider/html/overview.erb

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

data/lib/openvox-strings/yard/templates/default/puppet_provider/html/setup.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, T('tags'), :features, :confines, :defaults, :commands
+end
+
+# Renders the confines section.
+# @return [String] Returns the rendered section.
+def confines
+  @title = 'Confines'
+  @collection = object.confines
+  erb(:collection)
+end
+
+# Renders the defaults section.
+# @return [String] Returns the rendered section.
+def defaults
+  @title = 'Default Provider For'
+  @collection = object.defaults
+  erb(:collection)
+end
+
+# Renders the commands section.
+# @return [String] Returns the rendered section.
+def commands
+  @title = 'Commands'
+  @collection = object.commands
+  erb(:collection)
+end

data/lib/openvox-strings/yard/templates/default/puppet_provider/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_task/html/box_info.erb

@@ -0,0 +1,9 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %>,<br />
+      <%= object.file.gsub('json','rb') %><br/></div>
+    </dd>
+  </dl>
+</div>

data/lib/openvox-strings/yard/templates/default/puppet_task/html/header.erb

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

data/lib/openvox-strings/yard/templates/default/puppet_task/html/input.erb

@@ -0,0 +1,5 @@
+<% if json['input_method'] || json['supports_noop'] %>
+<div class="tags">
+    <p><strong>Supports noop?</strong> <%= json['supports_noop'] ? "true" : "false" %></p>
+</div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_task/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= description %>
+  </div>
+</div>

data/lib/openvox-strings/yard/templates/default/puppet_task/html/parameters.erb

@@ -0,0 +1,16 @@
+<% if @parameters && !@parameters.empty? %>
+<div class="tags">
+  <p class="tag_title"><%= @tag_title %></p>
+  <ul>
+    <% @parameters.each do |parameter, values| %>
+    <li>
+        <span class="name"><%= parameter %></span>
+        <span class="type">
+            <tt>(<%= values['type'] %>)</tt>
+        </span>
+        <% if values['description'] %> &mdash; <%= values['description'] %><% end %>
+    </li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_task/html/setup.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, T('tags'), :overview, :input, :parameters
+end
+
+def json
+  object.statement.json
+end
+
+def description
+  json['description']
+end
+
+# Renders the parameters section.
+# @return [String] Returns the rendered section.
+def parameters
+  @parameters = json['parameters'] || []
+  @parameters.to_a.sort!
+  @tag_title = 'Parameters'
+  erb(:parameters)
+end

data/lib/openvox-strings/yard/templates/default/puppet_task/html/supports_noop.erb

@@ -0,0 +1,3 @@
+<% if json['supports_noop'] %>
+<strong>Supports noop?</strong> <%= json['supports_noop'] %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_type/html/box_info.erb

@@ -0,0 +1,20 @@
+<div class="box_info">
+  <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>
+  <% if @providers && !@providers.empty? %>
+  <dl>
+    <dt>Providers:</dt>
+    <dd>
+      <% @providers.each do |provider| %>
+        <%= linkify(provider, provider.name.to_s) %><br/>
+      <% end %>
+    </dd>
+  </dl>
+  <% end %>
+</div>

data/lib/openvox-strings/yard/templates/default/puppet_type/html/deprecated.erb

@@ -0,0 +1,6 @@
+<% object.tags(:deprecated).each do |tag| %>
+  <div class="note deprecated">
+    <strong>DEPRECATED:</strong>
+    <%= htmlify_line deprecated.text %>
+  </div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_type/html/features.erb

@@ -0,0 +1,13 @@
+<% if object.features && !object.features.empty? %>
+<div class="tags">
+  <p class="tag_title">Features</p>
+  <ul>
+    <% object.features.each do |feature| %>
+    <li>
+      <span class="name"><%= feature.name %></span>
+      <% unless feature.docstring.empty? %> &mdash; <%= htmlify_line(feature.docstring) %><% end %>
+    </li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_type/html/header.erb

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

data/lib/openvox-strings/yard/templates/default/puppet_type/html/note.erb

@@ -0,0 +1,6 @@
+<% object.tags(:note).each do |tag| %>
+  <div class="note notetag">
+    <strong>Note:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_type/html/overview.erb

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

data/lib/openvox-strings/yard/templates/default/puppet_type/html/parameters.erb

@@ -0,0 +1,35 @@
+<% if @parameters && !@parameters.empty? %>
+<div class="tags">
+  <p class="tag_title"><%= @tag_title %></p>
+  <ul>
+    <% @parameters.each do |parameter| %>
+    <li>
+      <span class="name"><%= parameter.name + (parameter.isnamevar ? ' (namevar)' : '') %></span>
+      <% if parameter.default %>
+      <span class="default"> (defaults to: <em><%= parameter.default %></em>)</span>
+      <% end %>
+      <% unless parameter.docstring.empty? %>
+      <div class="docstring">
+        <div class="discussion">
+          <%= htmlify(parameter.docstring) %>
+        </div>
+      </div>
+      <% end %>
+      <% unless parameter.values.empty? %>
+      <div>
+        Supported values:
+        <ul>
+          <% parameter.values.each do |value| %>
+          <li>
+            <% other = parameter.aliases[value] %>
+            <%= value %><% if other %> (alias for: <em><%= other %></em>)<% end %>
+          </li>
+          <% end %>
+        </ul>
+      </div>
+      <% end %>
+    </li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_type/html/setup.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, :note, :todo, :deprecated, T('tags'), :properties, :parameters, :features
+end
+
+# Renders the box_info section.
+# @return [String] Returns the rendered section.
+def box_info
+  @providers = OpenvoxStrings::Yard::CodeObjects::Providers.instance(object.name).children
+  erb(:box_info)
+end
+
+# Renders the properties section.
+# @return [String] Returns the rendered section.
+def properties
+  # Properties are the same thing as parameters (from the documentation standpoint),
+  # so reuse the same template but with a different title and data source.
+  #
+  # "checks" such as "creates" and "onlyif" are another type of property
+  @parameters = (object.properties || []) + (object.checks || [])
+  @parameters.sort_by!(&:name)
+  @tag_title = 'Properties'
+  erb(:parameters)
+end
+
+# Renders the parameters section.
+# @return [String] Returns the rendered section.
+def parameters
+  @parameters = object.parameters || []
+  @parameters.sort_by!(&:name)
+  @tag_title = 'Parameters'
+  erb(:parameters)
+end

data/lib/openvox-strings/yard/templates/default/puppet_type/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/puppet_type/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/openvox-strings/yard/templates/default/tags/html/enum.erb

@@ -0,0 +1,17 @@
+<% if object.has_tag?(:enum) %>
+  <% object.parameters.each do |param, default| %>
+    <% tags = object.tags(:enum).select {|x| x.name.to_s == param.to_s.sub(/^\*+|:$/, '') } %>
+    <% next if tags.empty? %>
+    <p class="tag_title">Enum Options (<tt><%= param %></tt>):</p>
+    <ul class="option">
+      <% for tag in tags %>
+        <li>
+          <span class="name"><%= tag.pair.name %></span>
+          <% if tag.pair.text && tag.pair.text =~ /\S/ %>
+            &mdash; <%= htmlify_line(tag.pair.text) %>
+          <% end %>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/tags/html/puppet_overload.erb

@@ -0,0 +1,12 @@
+<% if object.has_tag?(:overload) && object.tags(:overload).any? {|o| !o.docstring.blank? } %>
+  <p class="tag_title">Signatures:</p>
+  <ul class="overload">
+    <% object.tags(:overload).each_with_index do |overload, index| %>
+      <% next if overload.docstring.blank? %>
+      <li class="overload_item">
+        <span class="signature"><%= "<strong>#{h(overload.signature)}</strong> &#x21d2; #{signature_types(overload, false)}" %></span>
+        <%= yieldall :object => overload %>
+      </li>
+    <% end %>
+  </ul>
+<% end %>

data/lib/openvox-strings/yard/templates/default/tags/setup.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Called to return parameter tags.
+# @return [Array<YARD::Tag>] Returns the parameter tags if the object should have parameters.
+def param
+  tag(:param) if
+    %i[method puppet_class puppet_data_type puppet_defined_type puppet_function puppet_task puppet_plan].include?(object.type)
+end
+
+# Renders the overload section.
+# @return [String] Returns the rendered section.
+def overload
+  erb(object.type == :puppet_function ? :puppet_overload : :overload)
+end
+
+# Renders the enum section.
+# @return [String] Returns the rendered section.
+def enum
+  erb(:enum)
+end

data/lib/openvox-strings/yard/util.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'puppet/util'
+
+# The module for various openvox-strings utility helpers.
+module OpenvoxStrings::Yard::Util
+  # Trims indentation from trailing whitespace and removes ruby literal quotation
+  # syntax `%Q{}` and `%{q}` from parsed strings.
+  # @param [String] str The string to scrub.
+  # @return [String] A scrubbed string.
+  def self.scrub_string(str)
+    match = str.match(/^%[Qq]{(.*)}$/m)
+    return Puppet::Util::Docs.scrub(match[1]) if match
+
+    Puppet::Util::Docs.scrub(str)
+  end
+
+  # hacksville, usa
+  # YARD creates ids in the html with with the style of "label-Module+description", where the markdown
+  # we use in the README involves the GitHub-style, which is #module-description. This takes our GitHub-style
+  # links and converts them to reference the YARD-style ids.
+  # @see https://github.com/octokit/octokit.rb/blob/0f13944e8dbb0210d1e266addd3335c6dc9fe36a/yard/default/layout/html/setup.rb#L5-L14
+  # @param [String] data HTML document to convert
+  # @return [String] HTML document with links converted
+  def self.github_to_yard_links(data)
+    data.scan(/href="\#(.+)"/).each do |bad_link|
+      data = data.gsub("=\"##{bad_link.first}\"", "=\"#label-#{bad_link.first.capitalize.tr('-', '+')}\"")
+    end
+
+    data
+  end
+
+  # Converts a list of tags into an array of hashes.
+  # @param [Array] tags List of tags to be converted into an array of hashes.
+  # @return [Array] Returns an array of tag hashes.
+  def self.tags_to_hashes(tags)
+    # Skip over the API tags that are public
+    tags.select { |t| t.tag_name != 'api' || t.text != 'public' }.map do |t|
+      next t.to_hash if t.respond_to?(:to_hash)
+
+      tag = { tag_name: t.tag_name }
+      # grab nested information for @option and @enum tags
+      if %w[option enum].include?(tag[:tag_name])
+        tag[:opt_name] = t.pair.name
+        tag[:opt_text] = t.pair.text
+        tag[:opt_types] = t.pair.types if t.pair.types
+        tag[:parent] = t.name
+      end
+      tag[:text] = t.text if t.text
+      tag[:types] = t.types if t.types
+      tag[:name] = t.name if t.name
+      tag
+    end
+  end
+
+  # Converts a YARD::Docstring (or String) to a docstring hash for JSON output.
+  # @param [YARD::Docstring, String] docstring The docstring to convert to a hash.
+  # @param [Array] select_tags List of tags to select. Other tags will be filtered out.
+  # @return [Hash] Returns a hash representation of the given docstring.
+  def self.docstring_to_hash(docstring, select_tags = nil)
+    hash = {}
+    hash[:text] = docstring
+
+    if docstring.is_a? YARD::Docstring
+      tags = tags_to_hashes(docstring.tags.select { |t| select_tags.nil? || select_tags.include?(t.tag_name.to_sym) })
+
+      unless tags.empty?
+        hash[:tags] = tags
+        #   .sort_by do |tag|
+        #   sort_key = tag[:tag_name].dup
+        #   sort_key << "-#{tag[:name]}" if tag[:name]
+        #   sort_key << "-#{tag[:opt_name]}" if tag[:opt_name]
+        #   sort_key
+        # end
+      end
+    end
+
+    hash
+  end
+
+  # Convert Puppet AST to text.
+  # @param [Puppet::Pops::Model::PopsObject] ast The Puppet AST to convert to text.
+  # @return [String] Returns a string of Puppet code.
+  def self.ast_to_text(ast)
+    ast.locator.extract_tree_text(ast)
+  end
+end