puppet-strings 1.2.1 → 2.0.0

data/lib/puppet-strings.rb

@@ -6,6 +6,8 @@ module PuppetStrings
     functions/**/*.pp
     types/**/*.pp
     lib/**/*.rb
+    tasks/*.json
+    plans/*.pp
   ).freeze
 
   # Generates documentation.
@@ -61,6 +63,10 @@ module PuppetStrings
     end
   end
 
+  def self.puppet_5?
+    Puppet::Util::Package.versioncmp(Puppet.version, "5.0.0") >= 0
+  end
+
   def self.render_json(path)
     require 'puppet-strings/json'
     PuppetStrings::Json.render(path)

data/lib/puppet-strings/json.rb

@@ -12,6 +12,8 @@ module PuppetStrings::Json
       resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash),
       providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash),
       puppet_functions: YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash),
+      puppet_tasks: YARD::Registry.all(:puppet_task).sort_by!(&:name).map!(&:to_hash),
+      puppet_plans: YARD::Registry.all(:puppet_plan).sort_by!(&:name).map!(&:to_hash)
       # TODO: Need Ruby documentation?
     }
 

data/lib/puppet-strings/markdown.rb

@@ -6,17 +6,22 @@ module PuppetStrings::Markdown
   require_relative 'markdown/functions'
   require_relative 'markdown/defined_types'
   require_relative 'markdown/resource_types'
+  require_relative 'markdown/puppet_tasks'
+  require_relative 'markdown/puppet_plans'
   require_relative 'markdown/table_of_contents'
 
   # generates markdown documentation
   # @return [String] markdown doc
   def self.generate
-    final = "# Reference\n\n"
+    final = "# Reference\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::PuppetTasks.render
+    final << PuppetStrings::Markdown::PuppetPlans.render
 
     final
   end

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

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

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

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

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

@@ -0,0 +1,24 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  class PuppetTask < Base
+    def initialize(registry)
+      @template = 'puppet_task.erb'
+      @registry = registry
+      super(registry, 'task')
+    end
+
+    def render
+      super(@template)
+    end
+
+    def supports_noop
+      @registry[:supports_noop]
+    end
+
+    def input_method
+      @registry[:input_method]
+    end
+
+  end
+end

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

@@ -0,0 +1,34 @@
+require_relative 'puppet_task'
+
+module PuppetStrings::Markdown
+  module PuppetTasks
+
+    # @return [Array] list of classes
+    def self.in_tasks
+      arr = YARD::Registry.all(:puppet_task).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::PuppetTask.new(a) }
+    end
+
+    def self.contains_private?
+      false
+    end
+
+    def self.render
+      final = in_tasks.length > 0 ? "## Tasks\n\n" : ""
+      in_tasks.each do |task|
+        final << task.render unless task.private?
+      end
+      final
+    end
+
+    def self.toc_info
+      final = ["Tasks"]
+
+      in_tasks.each do |task|
+        final.push(task.toc_info)
+      end
+
+      final
+    end
+  end
+end

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

@@ -6,7 +6,9 @@ module PuppetStrings::Markdown
       [PuppetStrings::Markdown::PuppetClasses,
       PuppetStrings::Markdown::DefinedTypes,
       PuppetStrings::Markdown::ResourceTypes,
-      PuppetStrings::Markdown::Functions].each do |r|
+      PuppetStrings::Markdown::Functions,
+      PuppetStrings::Markdown::PuppetTasks,
+      PuppetStrings::Markdown::PuppetPlans].each do |r|
         toc = r.toc_info
         group_name = toc.shift
         group = toc

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

@@ -2,14 +2,12 @@
 
 <% if text -%>
 <%= text %>
-
 <% elsif summary -%>
 <%= summary %>
-
 <% else -%>
 <%= "The #{name} class." %>
-
 <% end -%>
+
 <% if since -%>
 * **Since** <%= since %>
 
@@ -17,22 +15,28 @@
 <% 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 params %>
+<% if params -%>
 #### Parameters
 
 The following parameters are available in the `<%= name %>` <%= @type %>.
@@ -60,4 +64,3 @@ Default value: <%= value_string(defaults[param[:name]]) %>
 <% end -%>
 <% end -%>
 <% end -%>
-

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

@@ -1,16 +1,15 @@
 ### <%= name %>
+
 Type: <%= type %>
 
 <% if text -%>
 <%= text %>
-
 <% elsif summary -%>
 <%= summary %>
-
 <% else -%>
 <%= "The #{name} class." %>
-
 <% end -%>
+
 <% signatures.each do |sig| -%>
 #### `<%= sig.signature %>`
 

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

@@ -0,0 +1,28 @@
+### <%= name %>
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} task." %>
+
+<% end -%>
+**Supports noop?** <%= supports_noop %>
+
+<% if params -%>
+#### Parameters
+
+<% params.each do |param| -%>
+##### `<%= param[:name] %>`
+
+<% if param[:types] -%>
+Data type: `<%= param[:types].join(', ') -%>`
+
+<% end -%>
+<%= param[:text] %>
+
+<% end -%>
+<% end -%>

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

@@ -2,14 +2,12 @@
 
 <% if text -%>
 <%= text %>
-
 <% elsif summary -%>
 <%= summary %>
-
 <% else -%>
 <%= "The #{name} type." %>
-
 <% end -%>
+
 <% if since -%>
 * **Since** <%= since %>
 
@@ -17,21 +15,28 @@
 <% 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 properties %>
+<% if properties -%>
 #### Properties
 
 The following properties are available in the `<%= name %>` <%= @type %>.
@@ -111,4 +116,3 @@ Default value: <%= value_string(param[:default]) %>
 <% end -%>
 <% end -%>
 <% end -%>
-

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

@@ -1,13 +1,17 @@
 <% if group.length > 0 -%>
 ## <%= group_name %>
+
 <% if priv -%>
 ### Public <%= group_name %>
+
 <% group.each do |item| -%>
 <% unless item[:private] -%>
 * [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
 <% end -%>
 <% end -%>
+
 ### Private <%= group_name %>
+
 <% group.each do |item| -%>
 <% if item[:private] -%>
 * `<%= item[:name] %>`: <%= item[:desc] %>
@@ -18,4 +22,5 @@
 * [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
 <% end -%>
 <% end -%>
+
 <% end -%>

data/lib/puppet-strings/monkey_patches/display_object_command.rb

@@ -0,0 +1,11 @@
+# Monkey patch URL decoding in object displays. Usually :: is interpreted as a
+# namespace, but this is disabled in our base object, and so instead gets
+# URL-encoded.
+require 'yard/server/commands/display_object_command'
+class YARD::Server::Commands::DisplayObjectCommand
+  private
+  alias_method :object_path_yard, :object_path
+  def object_path
+    object_path_yard.gsub('_3A', ':')
+  end
+end

data/lib/puppet-strings/yard.rb

@@ -6,6 +6,7 @@ module PuppetStrings::Yard
   require 'puppet-strings/yard/handlers'
   require 'puppet-strings/yard/tags'
   require 'puppet-strings/yard/parsers'
+  require 'puppet-strings/monkey_patches/display_object_command'
 
   # Sets up YARD for use with puppet-strings.
   # @return [void]
@@ -15,10 +16,12 @@ module PuppetStrings::Yard
 
     # Register the Puppet parser
     YARD::Parser::SourceParser.register_parser_type(:puppet, PuppetStrings::Yard::Parsers::Puppet::Parser, ['pp'])
+    YARD::Parser::SourceParser.register_parser_type(:json, PuppetStrings::Yard::Parsers::JSON::Parser, ['json'])
 
     # Register our handlers
     YARD::Handlers::Processor.register_handler_namespace(:puppet, PuppetStrings::Yard::Handlers::Puppet)
     YARD::Handlers::Processor.register_handler_namespace(:puppet_ruby, PuppetStrings::Yard::Handlers::Ruby)
+    YARD::Handlers::Processor.register_handler_namespace(:json, PuppetStrings::Yard::Handlers::JSON)
 
     # Register the tag directives
     PuppetStrings::Yard::Tags::ParameterDirective.register!
@@ -46,7 +49,9 @@ class YARD::CLI::Yardoc
       :puppet_defined_type,
       :puppet_type,
       :puppet_provider,
-      :puppet_function
+      :puppet_function,
+      :puppet_task,
+      :puppet_plan
     )
   end
 end
@@ -75,6 +80,15 @@ class YARD::CLI::Stats
     output 'Puppet Functions', *type_statistics_all(:puppet_function)
   end
 
+  def stats_for_puppet_tasks
+    output 'Puppet Tasks', *type_statistics_all(:puppet_task)
+  end
+
+  def stats_for_puppet_plans
+    return unless PuppetStrings.puppet_5?
+    output 'Puppet Plans', *type_statistics_all(:puppet_plan)
+  end
+
   def output(name, data, undoc = nil)
     # Monkey patch output to accommodate our larger header widths
     @total += data if data.is_a?(Integer) && undoc

data/lib/puppet-strings/yard/code_objects.rb

@@ -5,4 +5,6 @@ module PuppetStrings::Yard::CodeObjects
   require 'puppet-strings/yard/code_objects/type'
   require 'puppet-strings/yard/code_objects/provider'
   require 'puppet-strings/yard/code_objects/function'
+  require 'puppet-strings/yard/code_objects/task'
+  require 'puppet-strings/yard/code_objects/plan'
 end

data/lib/puppet-strings/yard/code_objects/plan.rb

@@ -0,0 +1,56 @@
+require 'puppet-strings/yard/code_objects/group'
+
+class PuppetStrings::Yard::CodeObjects::Plans < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_plans)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Puppet Plans'
+  end
+end
+
+class PuppetStrings::Yard::CodeObjects::Plan < PuppetStrings::Yard::CodeObjects::Base
+  attr_reader :statement
+  attr_reader :parameters
+
+  # Initializes a Puppet plan code object.
+  # @param [PuppetStrings::Parsers::PlanStatement] statement The plan statement that was parsed.
+  # @return [void]
+  def initialize(statement)
+    @statement = statement
+    @parameters = statement.parameters.map { |p| [p.name, p.value] }
+    super(PuppetStrings::Yard::CodeObjects::Plans.instance, statement.name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_plan
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    @statement.source
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
+    hash[:defaults] = defaults unless defaults.empty?
+    hash[:source] = source unless source && source.empty?
+    hash
+  end
+end