yard-chef 1.0.0

data/lib/yard-chef.rb

@@ -0,0 +1,74 @@
+# Copyright (c) 2012 RightScale, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'yard'
+
+require 'yard-chef/code_objects/chef_object'
+require 'yard-chef/code_objects/cookbook_object'
+require 'yard-chef/code_objects/resource_object'
+require 'yard-chef/code_objects/provider_object'
+require 'yard-chef/code_objects/recipe_object'
+require 'yard-chef/code_objects/attribute_object'
+require 'yard-chef/code_objects/action_object'
+
+require 'yard-chef/handlers/base'
+require 'yard-chef/handlers/action'
+require 'yard-chef/handlers/attribute'
+require 'yard-chef/handlers/define'
+require 'yard-chef/handlers/actions'
+require 'yard-chef/handlers/cookbook'
+require 'yard-chef/handlers/recipe'
+
+module YARD::CodeObjects::Chef
+  # Since 'recipe' files do not have a specific keyword that can be matched,
+  # iterate through the list of files to be parsed and register the recipes.
+  # Description for every recipe may be found in 'metadata.rb' which can
+  # be taken care of in the handler.
+  # TODO: Investigate if YARD handlers can be invoked if parser is in a
+  # specific directory.
+  YARD::Parser::SourceParser.before_parse_list do |files, globals|
+    files.each do |file|
+      path_arr = File.expand_path(file).to_s.split('/')
+      unless (index = path_arr.index('recipes')).nil?
+        # Cookbook name can be derived from file path
+        # cookbook/<cookbook_name>/recipes/recipe_name.rb
+        cookbook_name = path_arr[index - 1]
+        cookbook = ChefObject.register(CHEF, cookbook_name, :cookbook)
+
+        recipe_name = path_arr.last.to_s.sub('.rb','')
+        recipe = ChefObject.register(cookbook, recipe_name, :recipe)
+
+        recipe.source = IO.read(file)
+        recipe.add_file(file, 1)
+      end
+    end
+  end
+
+  # Register '@resource' tag for mapping providers with light-weight resources
+  YARD::Tags::Library.define_tag(
+    'Map Chef Providers with Chef Resources',
+    :resource
+  )
+
+  # Register template directory for the chef plugin
+  template_dir = File.expand_path('../templates', File.dirname(__FILE__))
+  YARD::Templates::Engine.register_template_path(template_dir.to_s)
+end

data/lib/yard-chef/code_objects/action_object.rb

@@ -0,0 +1,43 @@
+# Copyright (c) 2012 RightScale, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    # An ActionObject represents an action in a lightweight provider.
+    # See http://wiki.opscode.com/display/chef/Lightweight+Resources+and+Providers+%28LWRP%29#LightweightResourcesandProviders%28LWRP%29-Keyword%3Aaction
+    #
+    class ActionObject < ChefObject
+      register_element :action
+
+      # Creates a new instance of the ActionObject
+      #
+      # @param namespace [NamespaceObject] namespace to which the action belongs
+      # @param name [String] name of the action
+      #
+      # @return [ActionObject] the newly created ActionObject
+      def initialize(namespace, name)
+        super(namespace, name)
+      end
+    end
+  end
+end

data/lib/yard-chef/code_objects/attribute_object.rb

@@ -0,0 +1,45 @@
+# Copyright (c) 2012 RightScale, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    # An AttributeObject represents a cookbook or a resource attribute.
+    # See http://wiki.opscode.com/display/chef/Attributes
+    #
+    class AttributeObject < ChefObject
+      register_element :attribute
+
+      # Creates a new instance of the AttributeObject.
+      #
+      # @param namespace [NamespaceObject] namespace to which the attribute
+      # belongs
+      # @param name [String] name of the attribute
+      #
+      # @return [AttributeObject] the newly created AttribteObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+      end
+    end
+  end
+end

data/lib/yard-chef/code_objects/chef_object.rb

@@ -0,0 +1,107 @@
+# Copyright (c) 2012 RightScale, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    # A ChefObject is an abstract implementation of all chef elements
+    # (cookbooks, resources, providers, recipes, attributes and actions).
+    #
+    class ChefObject < YARD::CodeObjects::ClassObject
+      # Returns the formatting type of docstring (Example: :markdown, :rdoc).
+      #
+      # @return [Symbol, String] formatting type
+      #
+      attr_reader :docstring_type
+
+      # Creates a new ChefObject object.
+      #
+      # @param namespace [NamespaceObject] namespace to which the object belongs
+      # @param name [String] name of the ChefObject
+      #
+      # @return [ChefObject] the newly created ChefObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+        @docstring_type = :markdown
+      end
+
+      # Register a chef element class.
+      #
+      # @param element [Class] chef element class
+      #
+      def self.register_element(element)
+        @@chef_elements ||= {}
+        @@chef_elements[element] = self
+      end
+
+      # Factory for creating and registering chef element object in
+      # YARD::Registry.
+      #
+      # @param namespace [NamespaceObject] namespace to which the object must
+      # belong
+      # @param name [String] name of the chef element
+      # @param type [Symbol, String] type of the chef element
+      #
+      # @return [<type>Object] the element object
+      #
+      def self.register(namespace, name, type)
+        element = @@chef_elements[type]
+        if element
+          element_obj = YARD::Registry.resolve(:root, "#{namespace}::#{name}")
+          if element_obj.nil?
+            element_obj = element.new(namespace, name)
+            log.info "Created [#{type.to_s.capitalize}]" +
+              " #{element_obj.name} => #{element_obj.namespace}"
+          end
+          element_obj
+        else
+          raise "Invalid chef element type #{type}"
+        end
+      end
+
+      # Returns children of an object of a particular type.
+      #
+      # @param type [Symbol] type of ChefObject to be selected
+      #
+      # @return [Array<ChefObject>] list of ChefObjects
+      #
+      def children_by_type(type)
+        children = YARD::Registry.all(type)
+        children.reject { |child| child.parent != self }
+      end
+
+      # Gets all Chef cookbooks.
+      #
+      # @return [Array<CookbookObject>] list of cookbooks.
+      #
+      def cookbooks
+        children_by_type(:cookbook)
+      end
+    end
+
+    # Register 'Chef' as the root namespace
+    CHEF = ChefObject.new(:root, 'chef')
+
+    log.info "Creating [Chef] as 'root' namespace"
+  end
+end

data/lib/yard-chef/code_objects/cookbook_object.rb

@@ -0,0 +1,109 @@
+# Copyright (c) 2012 RightScale, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    # A CookbookObject represents a Chef cookbook.
+    # See http://wiki.opscode.com/display/chef/Cookbooks for more information
+    # about cookbook.
+    #
+    class CookbookObject < ChefObject
+      register_element :cookbook
+
+      # Short description for the cookbook.
+      #
+      # @param short_desc [String] short description for the cookbook
+      #
+      # @return [String] short description for the cookbook
+      #
+      attr_accessor :short_desc
+
+      # Version of the cookbook.
+      #
+      # @param version [String] version for the cookbook
+      #
+      # @return [String] version for the cookbook
+      #
+      attr_accessor :version
+
+      # Lightweight resources implemented in the cookbook.
+      #
+      # @return [Array<ResourceObject>] lightweight resources in the cookbook
+      #
+      attr_reader :resources
+
+      # Lightweight providers implemented in the cookbook.
+      #
+      # @return [Array<ProviderObject>] lightweight providers in the cookbook
+      #
+      attr_reader :providers
+
+      # Creates a new CookbookObject instance.
+      # @param namespace [NamespaceObject] namespace to which the cookbook
+      # belongs
+      # @param name [String] name of the cookbook
+      #
+      # @return [CookbookObject] the newly created CookbookObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+        @resources = []
+        @providers = []
+        @libraries = []
+      end
+
+      # Recipes implemented in the cookbook.
+      #
+      # @return [Array<RecipeObject>] recipes in the cookbook
+      #
+      def recipes
+        children_by_type(:recipe)
+      end
+
+      # Attributes implemented in the cookbook.
+      #
+      # @return [Array<AttributeObject>] attributes in the cookbook
+      #
+      def attributes
+        children_by_type(:attribute)
+      end
+
+      # Definitions implemented in the cookbook.
+      #
+      # @return [Array<MethodObject>] definitions in the cookbook
+      #
+      def definitions
+        children_by_type(:method)
+      end
+
+      # Libraries defined in the cookbook.
+      #
+      # @return [Array<ModuleObject>] libraries in the cookbook
+      #
+      def libraries
+        modules = YARD::Registry.all(:module)
+        modules.select { |lib| !lib.parent.root? && lib.file =~ /#{@name}/ }
+      end
+    end
+  end
+end

data/lib/yard-chef/code_objects/provider_object.rb

@@ -0,0 +1,89 @@
+# Copyright (c) 2012 RightScale, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    # A ProviderObject represents a lightweight provider in Chef.
+    # See http://docs.opscode.com/essentials_cookbook_lwrp.html
+    #
+    class ProviderObject < ChefObject
+      register_element :provider
+
+      # Creates a new instance of ProviderObject.
+      #
+      # @param namespace [NamespaceObject] namespace to which the lightweight
+      # provider belongs
+      # @param name [String] name of the lightweight provider
+      #
+      # @return [ProviderObject] the newly created ProviderObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+      end
+
+      # Constructs class name for the lightweight provider.
+      #
+      # @return [String] the class name for the lightweight provider
+      #
+      def long_name
+        name = ''
+        if @name.to_s =~ /_/
+          @name.to_s.split('_').each do |str|
+            name << str.to_s.capitalize
+          end
+        else
+          name = @name.to_s.capitalize
+        end
+        namespace = @namespace.to_s.split('::').map { |str| str.capitalize }
+        "#{namespace.join('::')}::#{name}"
+      end
+
+      # Maps provider with a lightweight resource.
+      #
+      # @param [String] path to the lightweight provider file.
+      #
+      def map_resource(file)
+        file_handle = File.open(File.expand_path(file), 'r')
+        file_handle.readlines.each do |line|
+          if line =~ /#\s@resource/
+            resource_name = line.split(%r{@resource })[1].strip
+            @resource = ChefObject.register(RESOURCE, resource_name, :resource)
+            @resource.providers.push(self) unless @resource.providers.include?(self)
+            break
+          end
+        end
+      end
+
+      # Actions implemented in the lightweight provider.
+      #
+      # @return [Array<ActionObject>] actions in the provider
+      #
+      def actions
+        children_by_type(:action)
+      end
+    end
+
+    # Register 'provider' as a child of 'chef' namespace
+    PROVIDER = ChefObject.register(CHEF, 'provider', :provider)
+  end
+end