puppet-strings 2.2.0 → 2.6.0

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+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,43 @@
+# frozen_string_literal: true
+
+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/defined_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'defined_type'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_dtypes.length > 0 ? "## Defined types\n\n" : ""
       in_dtypes.each do |type|
-        final << type.render unless type.private?
+        final += type.render unless type.private?
       end
       final
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
@@ -19,23 +21,23 @@ module PuppetStrings::Markdown
 
     def type
       t = @registry[:type]
-      if t =~ /ruby4x/
+      if /ruby4x/.match?(t)
         "Ruby 4.x API"
-      elsif t =~ /ruby3/
+      elsif /ruby3/.match?(t)
         "Ruby 3.x API"
-      elsif t =~ /ruby/
+      elsif /ruby/.match?(t)
         "Ruby"
       else
         "Puppet Language"
       end
     end
 
-    def error_type(r)
-      "`#{r.split(' ')[0]}`"
+    def error_type(type)
+      "`#{type.split(' ')[0]}`"
     end
 
-    def error_text(r)
-      "#{r.split(' ').drop(1).join(' ')}"
+    def error_text(text)
+      "#{text.split(' ').drop(1).join(' ')}"
     end
   end
 

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'function'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_functions.length > 0 ? "## Functions\n\n" : ""
       in_functions.each do |func|
-        final << func.render unless func.private?
+        final += func.render unless func.private?
       end
       final
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'puppet_class'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_classes.length > 0 ? "## Classes\n\n" : ""
       in_classes.each do |klass|
-        final << klass.render unless klass.private?
+        final += klass.render unless klass.private?
       end
       final
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'puppet_plan'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_plans.length > 0 ? "## Plans\n\n" : ""
       in_plans.each do |plan|
-        final << plan.render unless plan.private?
+        final += plan.render unless plan.private?
       end
       final
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'puppet_task'
 
 module PuppetStrings::Markdown
@@ -16,7 +18,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_tasks.length > 0 ? "## Tasks\n\n" : ""
       in_tasks.each do |task|
-        final << task.render unless task.private?
+        final += task.render unless task.private?
       end
       final
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
@@ -12,11 +14,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/resource_types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'resource_type'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_rtypes.length > 0 ? "## Resource types\n\n" : ""
       in_rtypes.each do |type|
-        final << type.render unless type.private?
+        final += type.render unless type.private?
       end
       final
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PuppetStrings::Markdown
   module TableOfContents
     def self.render
@@ -7,6 +9,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
@@ -15,7 +18,7 @@ module PuppetStrings::Markdown
         priv = r.contains_private?
 
         template = File.join(File.dirname(__FILE__),"templates/table_of_contents.erb")
-        final << ERB.new(File.read(template), nil, '-').result(binding)
+        final += ERB.new(File.read(template), nil, '-').result(binding)
       end
       final
     end

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

@@ -1,4 +1,4 @@
-### <%= name %>
+### <a name="<%= link %>"></a>`<%= 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 -%>
 
@@ -47,10 +47,14 @@
 <% if params -%>
 #### Parameters
 
-The following parameters are available in the `<%= name %>` <%= @type %>.
+The following parameters are available in the `<%= name %>` <%= @type %>:
 
 <% params.each do |param| -%>
-##### `<%= param[:name] %>`
+* [`<%= param[:name] %>`](#<%= param[:name] %>)
+<% end -%>
+
+<% params.each do |param| -%>
+##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
 Data type: `<%= param[:types].join(', ') -%>`
@@ -65,9 +69,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,101 @@
+### <a name="<%= link %>"></a>`<%= 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
+
+```puppet
+<%= alias_of %>
+```
+
+<% end -%>
+<% if params -%>
+#### Parameters
+
+The following parameters are available in the `<%= name %>` <%= @type %>:
+
+<% params.each do |param| -%>
+* [`<%= param[:name] %>`](#<%= param[:name] %>)
+<% end -%>
+
+<% params.each do |param| -%>
+##### <a name="<%= param[:name] %>"></a>`<%= 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 -%>