puppet-strings 2.1.0 → 2.5.0

data/lib/puppet-strings/markdown.rb

@@ -5,6 +5,7 @@ module PuppetStrings::Markdown
   require_relative 'markdown/puppet_classes'
   require_relative 'markdown/functions'
   require_relative 'markdown/defined_types'
+  require_relative 'markdown/data_types'
   require_relative 'markdown/resource_types'
   require_relative 'markdown/puppet_tasks'
   require_relative 'markdown/puppet_plans'
@@ -13,13 +14,14 @@ module PuppetStrings::Markdown
   # generates markdown documentation
   # @return [String] markdown doc
   def self.generate
-    final = "# Reference\n"
+    final = "# Reference\n\n"
     final << "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n"
     final << PuppetStrings::Markdown::TableOfContents.render
     final << PuppetStrings::Markdown::PuppetClasses.render
     final << PuppetStrings::Markdown::DefinedTypes.render
     final << PuppetStrings::Markdown::ResourceTypes.render
     final << PuppetStrings::Markdown::Functions.render
+    final << PuppetStrings::Markdown::DataTypes.render
     final << PuppetStrings::Markdown::PuppetTasks.render
     final << PuppetStrings::Markdown::PuppetPlans.render
 

data/lib/puppet-strings/markdown/base.rb

@@ -60,9 +60,9 @@ module PuppetStrings::Markdown
       :summary => 'summary',
       :note => 'note',
       :todo => 'todo' }.each do |method_name, tag_name|
-      # @return [String] unless the tag is nil or the string.length == 0
+      # @return [String] unless the tag is nil or the string.empty?
       define_method method_name do
-        @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text] unless @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0].nil? || @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text].length.zero?
+        @tags.find { |tag| tag[:tag_name] == tag_name && !tag[:text].empty? }[:text] if @tags.any? { |tag| tag[:tag_name] == tag_name && !tag[:text].empty? }
       end
     end
 
@@ -78,37 +78,42 @@ module PuppetStrings::Markdown
 
     # @return [String] data type of return value
     def return_type
-      @tags.select { |tag| tag[:tag_name] == 'return' }[0][:types][0] unless @tags.select { |tag| tag[:tag_name] == 'return' }[0].nil?
+      @tags.find { |tag| tag[:tag_name] == 'return' }[:types][0] if @tags.any? { |tag| tag[:tag_name] == 'return' }
     end
 
     # @return [String] text from @since tag
     def since
-      @tags.select { |tag| tag[:tag_name] == 'since' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'since' }[0].nil?
+      @tags.find { |tag| tag[:tag_name] == 'since' }[:text] if @tags.any? { |tag| tag[:tag_name] == 'since' }
     end
 
     # @return [Array] @see tag hashes
     def see
-      @tags.select { |tag| tag[:tag_name] == 'see' } unless @tags.select { |tag| tag[:tag_name] == 'see' }[0].nil?
+      select_tags('see')
     end
 
     # @return [Array] parameter tag hashes
     def params
-      @tags.select { |tag| tag[:tag_name] == 'param' } unless @tags.select { |tag| tag[:tag_name] == 'param' }[0].nil?
+      select_tags('param')
     end
 
     # @return [Array] example tag hashes
     def examples
-      @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil?
+      select_tags('example')
     end
 
     # @return [Array] raise tag hashes
     def raises
-      @tags.select { |tag| tag[:tag_name] == 'raise' } unless @tags.select { |tag| tag[:tag_name] == 'raise' }[0].nil?
+      select_tags('raise')
     end
 
     # @return [Array] option tag hashes
     def options
-      @tags.select { |tag| tag[:tag_name] == 'option' } unless @tags.select { |tag| tag[:tag_name] == 'option' }[0].nil?
+      select_tags('option')
+    end
+
+    # @return [Array] enum tag hashes
+    def enums
+      select_tags('enum')
     end
 
     # @param parameter_name
@@ -119,7 +124,15 @@ module PuppetStrings::Markdown
       opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
     end
 
-    # @return [Array] any defaults found for the component
+    # @param parameter_name
+    #   parameter name to match to enum tags
+    # @return [Array] enum tag hashes that have a parent parameter_name
+    def enums_for_param(parameter_name)
+      enums_for_p = enums.select { |e| e[:parent] == parameter_name } unless enums.nil?
+      enums_for_p unless enums_for_p.nil? || enums_for_p.length.zero?
+    end
+
+    # @return [Hash] any defaults found for the component
     def defaults
       @registry[:defaults] unless @registry[:defaults].nil?
     end
@@ -153,12 +166,13 @@ module PuppetStrings::Markdown
     end
 
     def private?
-      result = false
-      api = @tags.find { |tag| tag[:tag_name] == 'api' }
-      unless api.nil?
-        result = api[:text] == 'private' ? true : false
-      end
-      result
+      @tags.any? { |tag| tag[:tag_name] == 'api' && tag[:text] == 'private' }
+    end
+
+    def word_wrap(text, line_width: 120, break_sequence: "\n")
+      text.split("\n").collect! do |line|
+        line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
+      end * break_sequence
     end
 
     # @return [String] full markdown rendering of a component
@@ -166,5 +180,12 @@ module PuppetStrings::Markdown
       file = File.join(File.dirname(__FILE__),"templates/#{template}")
       ERB.new(File.read(file), nil, '-').result(binding)
     end
+
+    private
+
+    def select_tags(name)
+      tags = @tags.select { |tag| tag[:tag_name] == name }
+      tags.empty? ? nil : tags
+    end
   end
 end

data/lib/puppet-strings/markdown/data_type.rb

@@ -0,0 +1,34 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  # This class encapsualtes ruby data types and puppet type aliases
+  class DataType < Base
+    attr_reader :alias_of
+    attr_reader :functions
+
+    def initialize(registry)
+      @template = 'data_type.erb'
+      super(registry, 'data type')
+      @alias_of = registry[:alias_of] unless registry[:alias_of].nil?
+      @functions = @registry[:functions].nil? ? nil : @registry[:functions].map { |func| DataType::Function.new(func) }
+    end
+
+    def render
+      super(@template)
+    end
+  end
+
+  class DataType::Function < Base
+    def initialize(registry)
+      super(registry, 'data_type_function')
+    end
+
+    def render
+      super('data_type_function.erb')
+    end
+
+    def signature
+      @registry[:signature]
+    end
+  end
+end

data/lib/puppet-strings/markdown/data_types.rb

@@ -0,0 +1,41 @@
+require_relative 'data_type'
+
+module PuppetStrings::Markdown
+  module DataTypes
+
+    # @return [Array] list of data types
+    def self.in_dtypes
+      arr = YARD::Registry.all(:puppet_data_type).map!(&:to_hash)
+      arr.concat(YARD::Registry.all(:puppet_data_type_alias).map!(&:to_hash))
+
+      arr.sort! { |a,b| a[:name] <=> b[:name] }
+      arr.map! { |a| PuppetStrings::Markdown::DataType.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_dtypes.nil?
+        in_dtypes.find { |type| type.private? }.nil? ? false : true
+      end
+    end
+
+    def self.render
+      final = in_dtypes.length > 0 ? "## Data types\n\n" : ""
+      in_dtypes.each do |type|
+        final << type.render unless type.private?
+      end
+      final
+    end
+
+
+    def self.toc_info
+      final = ["Data types"]
+
+      in_dtypes.each do |type|
+        final.push(type.toc_info)
+      end
+
+      final
+    end
+  end
+end

data/lib/puppet-strings/markdown/function.rb

@@ -30,11 +30,11 @@ module PuppetStrings::Markdown
       end
     end
 
-    def error_type(r)
+    def error_type(r) # rubocop:disable Naming/UncommunicativeMethodParamName
       "`#{r.split(' ')[0]}`"
     end
 
-    def error_text(r)
+    def error_text(r) # rubocop:disable Naming/UncommunicativeMethodParamName
       "#{r.split(' ').drop(1).join(' ')}"
     end
   end

data/lib/puppet-strings/markdown/resource_type.rb

@@ -12,11 +12,28 @@ module PuppetStrings::Markdown
     end
 
     def properties
-      @registry[:properties]
+      return nil unless @registry[:properties]
+
+      @registry[:properties].sort_by { |p| p[:name] }
+    end
+
+    def checks
+      return nil unless @registry[:checks]
+
+      @registry[:checks].sort_by { |p| p[:name] }
+    end
+
+    # "checks" (such as "onlyif" or "creates") are another type of property
+    def properties_and_checks
+      return nil if properties.nil? && checks.nil?
+
+      ((properties || []) + (checks || [])).sort_by { |p| p[:name] }
     end
 
     def parameters
-      @registry[:parameters]
+      return nil unless @registry[:parameters]
+
+      @registry[:parameters].sort_by { |p| p[:name] }
     end
 
     def regex_in_data_type?(data_type)

data/lib/puppet-strings/markdown/table_of_contents.rb

@@ -7,6 +7,7 @@ module PuppetStrings::Markdown
       PuppetStrings::Markdown::DefinedTypes,
       PuppetStrings::Markdown::ResourceTypes,
       PuppetStrings::Markdown::Functions,
+      PuppetStrings::Markdown::DataTypes,
       PuppetStrings::Markdown::PuppetTasks,
       PuppetStrings::Markdown::PuppetPlans].each do |r|
         toc = r.toc_info

data/lib/puppet-strings/markdown/templates/classes_and_defines.erb

@@ -1,4 +1,4 @@
-### <%= name %>
+### `<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+  <%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
@@ -65,9 +65,17 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
-Default value: <%= value_string(defaults[param[:name]]) %>
+Default value: `<%= value_string(defaults[param[:name]]) %>`
 
 <% end -%>
 <% end -%>

data/lib/puppet-strings/markdown/templates/data_type.erb

@@ -0,0 +1,93 @@
+### `<%= name %>`
+
+<% if text -%>
+<%= text %>
+<% elsif summary -%>
+<%= summary %>
+<% else -%>
+<%= "The #{name} data type." %>
+<% end -%>
+
+<% if todo -%>
+* **TODO** <%= todo %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if since -%>
+* **Since** <%= since %>
+
+<% end -%>
+<% if see -%>
+* **See also**
+<% see.each do |sa| -%>
+<% if sa[:name] -%>
+<%= "  * #{sa[:name]}" %>
+<% end -%>
+<% if sa[:text] -%>
+<%= "  * #{sa[:text]}" %>
+<% end -%>
+<% end -%>
+
+<% end -%>
+<% if examples -%>
+#### Examples
+
+<% examples.each do |eg| -%>
+##### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
+<% if alias_of -%>
+Alias of `<%= alias_of %>`
+
+<% end -%>
+<% if params -%>
+#### Parameters
+
+The following parameters are available in the `<%= name %>` <%= @type %>.
+
+<% params.each do |param| -%>
+##### `<%= param[:name] %>`
+
+<% if param[:types] -%>
+Data type: `<%= param[:types].join(', ') -%>`
+
+<% end -%>
+<%= param[:text] %>
+
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if defaults && defaults[param[:name]] -%>
+Default value: `<%= value_string(defaults[param[:name]]) %>`
+
+<% end -%>
+<% end -%>
+<% end -%>
+<% if functions -%>
+#### Functions
+
+The following functions are available in the `<%= name %>` <%= @type %>.
+
+<% functions.each do |func| -%><%= func.render -%><% end -%>
+<% end -%>

data/lib/puppet-strings/markdown/templates/data_type_function.erb

@@ -0,0 +1,67 @@
+### `<%= name %>`
+
+#### `<%= signature %>`
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} function." %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if return_type -%>
+Returns: `<%= return_type %>`<% if return_val %> <%= return_val %><% end %>
+
+<% end -%>
+<% if raises -%>
+Raises:
+<% raises.each do |r| -%>
+* <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
+<% end -%>
+
+<% end -%>
+<% if examples -%>
+##### Examples
+
+<% examples.each do |eg| -%>
+###### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
+<% if params -%>
+<% params.each do |param| -%>
+##### `<%= param[:name]  %>`
+
+Data type: `<%= param[:types][0] %>`
+
+<%= param[:text] %>
+
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% end -%>
+<% end -%>