(PDOC-206) support for tasks

lib/puppet-strings.rb

@@ -6,6 +6,7 @@ module PuppetStrings
     functions/**/*.pp
     types/**/*.pp
     lib/**/*.rb
+    tasks/*.json
   ).freeze
 
   # Generates documentation.

lib/puppet-strings/json.rb

@@ -12,6 +12,7 @@ def self.render(file = nil)
       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),
       # TODO: Need Ruby documentation?
     }
 

lib/puppet-strings/markdown.rb

@@ -6,6 +6,7 @@ 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/table_of_contents'
 
   # generates markdown documentation
@@ -17,6 +18,7 @@ def self.generate
     final << PuppetStrings::Markdown::DefinedTypes.render
     final << PuppetStrings::Markdown::ResourceTypes.render
     final << PuppetStrings::Markdown::Functions.render
+    final << PuppetStrings::Markdown::PuppetTasks.render
 
     final
   end

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

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

lib/puppet-strings/markdown/table_of_contents.rb

@@ -6,7 +6,8 @@ def self.render
       [PuppetStrings::Markdown::PuppetClasses,
       PuppetStrings::Markdown::DefinedTypes,
       PuppetStrings::Markdown::ResourceTypes,
-      PuppetStrings::Markdown::Functions].each do |r|
+      PuppetStrings::Markdown::Functions,
+      PuppetStrings::Markdown::PuppetTasks].each do |r|
         toc = r.toc_info
         group_name = toc.shift
         group = toc

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 -%>

lib/puppet-strings/yard.rb

@@ -15,10 +15,12 @@ def self.setup!
 
     # 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 +48,8 @@ def all_objects
       :puppet_defined_type,
       :puppet_type,
       :puppet_provider,
-      :puppet_function
+      :puppet_function,
+      :puppet_task
     )
   end
 end
@@ -75,6 +78,10 @@ def stats_for_puppet_functions
     output 'Puppet Functions', *type_statistics_all(:puppet_function)
   end
 
+  def stats_for_puppet_tasks
+    output 'Puppet Tasks', *type_statistics_all(:puppet_task)
+  end
+
   def output(name, data, undoc = nil)
     # Monkey patch output to accommodate our larger header widths
     @total += data if data.is_a?(Integer) && undoc

lib/puppet-strings/yard/code_objects.rb

@@ -5,4 +5,5 @@ 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'
 end

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

@@ -0,0 +1,70 @@
+require 'puppet-strings/yard/code_objects/group'
+
+# Implements the group for Puppet tasks.
+class PuppetStrings::Yard::CodeObjects::Tasks < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_tasks)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Puppet Tasks'
+  end
+end
+
+# Implements the Puppet task code object.
+class PuppetStrings::Yard::CodeObjects::Task < PuppetStrings::Yard::CodeObjects::Base
+  attr_reader :statement
+
+  # Initializes a JSON task code object.
+  # @param statement TaskStatement object
+  # @return [void]
+  def initialize(statement)
+    @name = statement.name
+    @statement = statement
+    super(PuppetStrings::Yard::CodeObjects::Tasks.instance, name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_task
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    @statement.source
+  end
+
+  def parameters
+    parameters = []
+    statement.json['parameters'].each do |name,props|
+      parameters.push({ name: name.to_s,
+                        tag_name: 'param',
+                        text: props['description'] || "",
+                        types: [props['type']] || "" })
+    end
+    parameters
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    { name: name.to_s,
+      file: statement.file,
+      line: statement.line,
+      docstring: {
+        text: statement.docstring,
+        tags: parameters
+      },
+      source: statement.source,
+      supports_noop: statement.json['supports_noop'] || false,
+      input_method: statement.json['input_method']
+    }
+  end
+end

lib/puppet-strings/yard/handlers.rb

@@ -8,6 +8,11 @@ module Ruby
     require 'puppet-strings/yard/handlers/ruby/function_handler'
   end
 
+  # The module for custom JSON YARD handlers.
+  module JSON
+    require 'puppet-strings/yard/handlers/json/task_handler'
+  end
+
   # The module for custom Puppet YARD handlers.
   module Puppet
     require 'puppet-strings/yard/handlers/puppet/class_handler'

lib/puppet-strings/yard/handlers/json/base.rb

@@ -0,0 +1,5 @@
+class PuppetStrings::Yard::Handlers::JSON::Base < YARD::Handlers::Base
+  def self.handles?(statement)
+    handlers.any? {|handler| statement.is_a?(handler)}
+  end
+end

lib/puppet-strings/yard/handlers/json/task_handler.rb

@@ -0,0 +1,31 @@
+require 'puppet-strings/yard/handlers/json/base'
+require 'puppet-strings/yard/parsers'
+require 'puppet-strings/yard/parsers/json/parser'
+
+class PuppetStrings::Yard::Handlers::JSON::TaskHandler < PuppetStrings::Yard::Handlers::JSON::Base
+  handles PuppetStrings::Yard::Parsers::JSON::TaskStatement
+  namespace_only
+
+  process do
+    object = PuppetStrings::Yard::CodeObjects::Task.new(statement)
+    register object
+
+    @kind = "Puppet Task #{object.name}."
+    @statement = statement
+
+    validate_description
+    validate_params
+  end
+
+  def validate_description
+    log.warn "Missing a description for #{@kind}." if @statement.docstring.empty?
+  end
+
+  def validate_params
+    unless @statement.parameters.empty?
+      @statement.parameters.each do |param, val|
+        log.warn "Missing description for param '#{param}' in #{@kind}" if val['description'].nil?
+      end
+    end
+  end
+end

lib/puppet-strings/yard/parsers.rb

@@ -1,5 +1,9 @@
 # The module for custom YARD parsers.
 module PuppetStrings::Yard::Parsers
+  # The module for custom YARD parsers for JSON.
+  module JSON
+    require 'puppet-strings/yard/parsers/json/parser'
+  end
   # The module for custom YARD parsers for the Puppet language.
   module Puppet
     require 'puppet-strings/yard/parsers/puppet/parser'

lib/puppet-strings/yard/parsers/json/parser.rb

@@ -0,0 +1,33 @@
+require 'puppet-strings/yard/parsers/json/task_statement'
+
+class PuppetStrings::Yard::Parsers::JSON::Parser < YARD::Parser::Base
+  attr_reader :file, :source
+
+  # Initializes the parser.
+  # @param [String] source The source being parsed.
+  # @param [String] filename The file name of the file being parsed.
+  # @return [void]
+  def initialize(source, filename)
+    @file = filename
+    @source = source
+    @statements = []
+  end
+
+  def enumerator
+    @statements
+  end
+
+  # Parses the source
+  # @return [void]
+  def parse
+    begin
+      json = JSON.parse(source)
+      @statements.push(PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, @source, @file))
+    rescue
+      log.error "Failed to parse #{@file}: "
+      @statements = []
+    end
+    @statements.freeze
+    self
+  end
+end

lib/puppet-strings/yard/parsers/json/task_statement.rb

@@ -0,0 +1,35 @@
+module PuppetStrings::Yard::Parsers::JSON
+  # Represents the Puppet Task statement.
+  class TaskStatement
+    attr_reader :line, :comments, :comments_range, :json, :file, :source, :docstring
+
+    def initialize(json, source, file)
+      @file = file
+      @source = source
+      @json = json
+      @line = 0
+      @comments_range = nil
+      @docstring = YARD::Docstring.new(@json['description'])
+    end
+
+    def parameters
+      json['parameters'] || {}
+    end
+
+    def comments_hash_flag
+      false
+    end
+
+    def show
+      ""
+    end
+
+    def comments
+      docstring.all
+    end
+
+    def name
+      File.basename(@file).gsub('.json','') || ""
+    end
+  end
+end

lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_task.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb

@@ -62,3 +62,12 @@ def generate_class_list
   @list_type = 'class'
   generate_list_contents
 end
+
+# Generates the searchable Puppet Task list.
+# @return [void]
+def generate_puppet_task_list
+  @items = Registry.all(:puppet_task).sort_by {|t| t.name.to_s }
+  @list_title = 'Puppet Task List'
+  @list_type = 'puppet_task'
+  generate_list_contents
+end