puppet-strings 1.1.1 → 1.2.0

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

@@ -0,0 +1,14 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  class DefinedType < Base
+    def initialize(registry)
+      @template = 'classes_and_defines.erb'
+      super(registry, 'defined type')
+    end
+
+    def render
+      super(@template)
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+require_relative 'defined_type'
+
+module PuppetStrings::Markdown
+  module DefinedTypes
+
+    # @return [Array] list of defined types
+    def self.in_dtypes
+      arr = YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::DefinedType.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 ? "## Defined types\n\n" : ""
+      in_dtypes.each do |type|
+        final << type.render unless type.private?
+      end
+      final
+    end
+
+    def self.toc_info
+      final = ["Defined types"]
+
+      in_dtypes.each do |type|
+        final.push(type.toc_info)
+      end
+
+      final
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  class Function < Base
+    attr_reader :signatures
+
+    def initialize(registry)
+      @template = 'function.erb'
+      super(registry, 'function')
+      @signatures = []
+      registry[:signatures].each do |sig|
+        @signatures.push(Signature.new(sig))
+      end
+    end
+
+    def render
+      super(@template)
+    end
+
+    def type
+      t = @registry[:type]
+      if t =~ /ruby4x/
+        "Ruby 4.x API"
+      elsif t =~ /ruby3/
+        "Ruby 3.x API"
+      elsif t =~ /ruby/
+        "Ruby"
+      else
+        "Puppet Language"
+      end
+    end
+
+    def error_type(r)
+      "`#{r.split(' ')[0]}`"
+    end
+
+    def error_text(r)
+      "#{r.split(' ').drop(1).join(' ')}"
+    end
+  end
+
+  class Function::Signature < Base
+    def initialize(registry)
+      @registry = registry
+      super(@registry, 'function signature')
+    end
+
+    def signature
+      @registry[:signature]
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+require_relative 'function'
+
+module PuppetStrings::Markdown
+  module Functions
+
+    # @return [Array] list of functions
+    def self.in_functions
+      arr = YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::Function.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_functions.nil?
+        in_functions.find { |func| func.private? }.nil? ? false : true
+      end
+    end
+
+    def self.render
+      final = in_functions.length > 0 ? "## Functions\n\n" : ""
+      in_functions.each do |func|
+        final << func.render unless func.private?
+      end
+      final
+    end
+
+    def self.toc_info
+      final = ["Functions"]
+
+      in_functions.each do |func|
+        final.push(func.toc_info)
+      end
+
+      final
+    end
+  end
+end
+

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

@@ -0,0 +1,14 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  class PuppetClass < Base
+    def initialize(registry)
+      @template = 'classes_and_defines.erb'
+      super(registry, 'class')
+    end
+
+    def render
+      super(@template)
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+require_relative 'puppet_class'
+
+module PuppetStrings::Markdown
+  module PuppetClasses
+
+    # @return [Array] list of classes
+    def self.in_classes
+      arr = YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::PuppetClass.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_classes.nil?
+        in_classes.find { |klass| klass.private? }.nil? ? false : true
+      end
+    end
+
+    def self.render
+      final = in_classes.length > 0 ? "## Classes\n\n" : ""
+      in_classes.each do |klass|
+        final << klass.render unless klass.private?
+      end
+      final
+    end
+
+    def self.toc_info
+      final = ["Classes"]
+
+      in_classes.each do |klass|
+        final.push(klass.toc_info)
+      end
+
+      final
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  class ResourceType < Base
+    def initialize(registry)
+      @template = 'resource_type.erb'
+      super(registry, 'type')
+    end
+
+    def render
+      super(@template)
+    end
+
+    def properties
+      @registry[:properties]
+    end
+
+    def parameters
+      @registry[:parameters]
+    end
+
+    def regex_in_data_type?(data_type)
+      m = data_type.match(/\w+\[\/.*\/\]/)
+      m unless m.nil? || m.length.zero?
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+require_relative 'resource_type'
+
+module PuppetStrings::Markdown
+  module ResourceTypes
+
+    # @return [Array] list of resource types
+    def self.in_rtypes
+      arr = YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::ResourceType.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_rtypes.nil?
+        in_rtypes.find { |type| type.private? }.nil? ? false : true
+      end
+    end
+
+    def self.render
+      final = in_rtypes.length > 0 ? "## Resource types\n\n" : ""
+      in_rtypes.each do |type|
+        final << type.render unless type.private?
+      end
+      final
+    end
+
+    def self.toc_info
+      final = ["Resource types"]
+
+      in_rtypes.each do |type|
+        final.push(type.toc_info)
+      end
+
+      final
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module PuppetStrings::Markdown
+  module TableOfContents
+    def self.render
+      final = ""
+
+      [PuppetStrings::Markdown::PuppetClasses,
+      PuppetStrings::Markdown::DefinedTypes,
+      PuppetStrings::Markdown::ResourceTypes,
+      PuppetStrings::Markdown::Functions].each do |r|
+        toc = r.toc_info
+        group_name = toc.shift
+        group = toc
+        priv = r.contains_private?
+
+        template = File.join(File.dirname(__FILE__),"templates/table_of_contents.erb")
+        final << ERB.new(File.read(template), nil, '-').result(binding)
+      end
+      final
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+### <%= name %>
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} class." %>
+
+<% end -%>
+<% if since -%>
+* **Since** <%= since %>
+
+<% end -%>
+<% if see -%>
+* **See also**
+<% see.each do |sa| -%>
+<%= sa[:name] %>
+<%= sa[:text] %>
+<% end -%>
+
+<% end -%>
+<% if examples -%>
+#### Examples
+<% examples.each do |eg| -%>
+##### <%= eg[:name] %>
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% 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 defaults && defaults[param[:name]] -%>
+Default value: <%= value_string(defaults[param[:name]]) %>
+
+<% end -%>
+<% end -%>
+<% end -%>
+

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

@@ -0,0 +1,50 @@
+### <%= name %>
+Type: <%= type %>
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} class." %>
+
+<% end -%>
+<% signatures.each do |sig| -%>
+#### `<%= sig.signature %>`
+
+<% if sig.text -%>
+<%= sig.text %>
+
+<% end -%>
+<% if sig.return_type -%>
+Returns: `<%= sig.return_type %>`<% if sig.return_val %> <%= sig.return_val %><% end %>
+
+<% end -%>
+<% if raises -%>
+Raises:
+<% raises.each do |r| -%>
+* <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
+<% end -%>
+
+<% end -%>
+<% if sig.params -%>
+<% sig.params.each do |param| -%>
+##### `<%= param[:name]  %>`
+
+Data type: `<%= param[:types][0] %>`
+
+<%= param[:text] %>
+
+<% if sig.options_for_param(param[:name]) -%>
+Options:
+
+<% sig.options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% end -%>
+<% end -%>
+<% end -%>

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

@@ -0,0 +1,114 @@
+### <%= name %>
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} type." %>
+
+<% end -%>
+<% if since -%>
+* **Since** <%= since %>
+
+<% end -%>
+<% if see -%>
+* **See also**
+<% see.each do |sa| -%>
+<%= sa[:name] %>
+<%= sa[:text] %>
+<% end -%>
+
+<% end -%>
+<% if examples -%>
+#### Examples
+<% examples.each do |eg| -%>
+##### <%= eg[:name] %>
+```puppet
+<%= eg[:text] %>
+```
+<% end -%>
+<% end -%>
+<% if properties %>
+#### Properties
+
+The following properties are available in the `<%= name %>` <%= @type %>.
+
+<% properties.each do |prop| -%>
+##### `<%= prop[:name] %>`
+
+<% if prop[:values] -%>
+Valid values: <%= prop[:values].map { |value| value_string(value) }.join(', ') %>
+
+<% end -%>
+<% if prop[:isnamevar] -%>
+namevar
+
+<% end -%>
+<% if prop[:aliases] -%>
+Aliases: <%= prop[:aliases].to_s.delete('{').delete('}') %>
+
+<% end -%>
+<% if prop[:data_type] -%>
+Data type: `<%= prop[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(prop[:data_type]) %>
+
+<% end -%>
+<%= prop[:description] %>
+
+<% if options_for_param(prop[:name]) -%>
+Options:
+
+<% options_for_param(prop[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if prop[:default] -%>
+Default value: <%= prop[:default] %>
+
+<% end -%>
+<% end -%>
+<% end -%>
+<% if parameters -%>
+#### Parameters
+
+The following parameters are available in the `<%= name %>` <%= @type %>.
+
+<% parameters.each do |param| -%>
+##### `<%= param[:name] %>`
+
+<% if param[:values] -%>
+Valid values: <%= param[:values].map { |value| value_string(value) }.join(', ') %>
+
+<% end -%>
+<% if param[:isnamevar] -%>
+namevar
+
+<% end -%>
+<% if param[:aliases] -%>
+Aliases: <%= param[:aliases].to_s.delete('{').delete('}') %>
+
+<% end -%>
+<% if param[:data_type] -%>
+Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(param[:data_type]) %>
+
+<% end -%>
+<%= param[:description] %>
+
+<% 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 param[:default] -%>
+Default value: <%= value_string(param[:default]) %>
+
+<% end -%>
+<% end -%>
+<% end -%>
+