yard-chef 1.0.0

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

@@ -0,0 +1,52 @@
+# 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 RecipeObject represents a recipe in a chef cookbook.
+    # See http://docs.opscode.com/essentials_cookbook_recipes.html
+    #
+    class RecipeObject < ChefObject
+      register_element :recipe
+
+      # Creates a new instance of RecipeObject.
+      #
+      # @param namespace [NamespaceObject] namespace to which the recipe belongs
+      # @param name [String] name of the recipe
+      #
+      # @return [RecipeObject] the newly created RecipeObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+      end
+
+      # Prefixes recipe name with the name of the cookbook.
+      #
+      # @return [String] recipe name
+      #
+      def name
+        self.parent.name.to_s << '::' << @name.to_s
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# 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 ResourceObject represents a lightweight resource in chef.
+    # See http://docs.opscode.com/essentials_cookbook_lwrp.html
+    #
+    class ResourceObject < ChefObject
+      register_element :resource
+
+      # Creates a new instance of ResourceObject.
+      #
+      # @param namespace [NamespaceObject] namespace to which the lightweight
+      # resource belongs
+      # @param name [String] name of the lightweight resource
+      #
+      # @return [ResourceObject] the newly created ResourceObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+        @providers = []
+      end
+
+      # Constructs class name for the lightweight resource.
+      #
+      # @return [String] class name for the lightweight resource
+      #
+      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
+
+      # Attributes defined in the lightweight resource.
+      #
+      # @return [Array<AttributeObject>] attributes in the lightweight resource
+      #
+      def attributes
+        children_by_type(:attribute)
+      end
+
+      # Actions supported by the lightweight resource.
+      #
+      # @return [Array<ActionObject>] actions in the lightweight resource
+      #
+      def actions
+        children_by_type(:action)
+      end
+    end
+
+    # Register 'resource' as a child of 'chef' namespace
+    RESOURCE = ChefObject.register(CHEF, 'resource', :resource)
+  end
+end

data/lib/yard-chef/handlers/action.rb

@@ -0,0 +1,52 @@
+# 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::Handlers
+  module Chef
+    # Handles "action" in a provider.
+    #
+    class ActionHandler < Base
+      handles method_call(:action)
+
+      def process
+        # Register the provider object
+        provider_obj = lwrp
+        provider_obj.map_resource(statement.file)
+        provider_obj.add_file(statement.file)
+
+        # Add provider to the cookbook to which it belongs
+        cookbook_obj = cookbook
+        unless cookbook_obj.providers.include?(provider_obj)
+          cookbook_obj.providers.push(provider_obj)
+        end
+        provider_obj.cookbook = cookbook_obj
+
+        # Register the action in the provider
+        action_obj = ChefObject.register(provider_obj, name, :action)
+        action_obj.source = statement.source
+        action_obj.docstring = statement.docstring
+        action_obj.add_file(statement.file, statement.line)
+      end
+    end
+  end
+end

data/lib/yard-chef/handlers/actions.rb

@@ -0,0 +1,57 @@
+# 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::Handlers
+  module Chef
+    # Handles list of actions in a lightweight resource.
+    #
+    class ActionsHandler < Base
+      handles method_call(:actions)
+
+      def process
+        # Register the lightweight resource
+        resource_obj = lwrp
+        resource_obj.add_file(statement.file)
+
+        # Add the lightweight resource to the cookbook in which it is defined
+        cookbook_obj = cookbook
+        unless cookbook_obj.resources.include?(resource_obj)
+          cookbook_obj.resources.push(resource_obj)
+        end
+
+        # if multiple actions listed in same line, split the actions and
+        # register them
+        if statement.first_line =~ /,/
+          statement.first_line.split(%r{,?\s*:}).each do |action|
+            action = ChefObject.register(resource_obj, name, :action)
+          end
+        else
+          action = ChefObject.register(resource_obj, name, :action)
+          action.docstring = statement.docstring
+        end
+
+        log.info "Found [Actions] in #{parser.file.to_s}"
+      end
+    end
+  end
+end

data/lib/yard-chef/handlers/attribute.rb

@@ -0,0 +1,81 @@
+# 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::Handlers
+  module Chef
+    # Handles "attributes" in cookbook metadata and lightweight resource.
+    #
+    class AttributeHandler < Base
+      handles method_call(:attribute)
+
+      # Process "attribute" keyword.
+      #
+      def process
+        # If file path includes metadata then handle cookbook attributes
+        # else handle resource attributes
+        if parser.file =~ /metadata\.rb/
+          namespace = cookbook
+        else
+          namespace = lwrp
+          namespace.add_file(statement.file)
+
+          cookbook_obj = cookbook
+          unless cookbook_obj.resources.include?(namespace)
+            cookbook_obj.resources.push(namespace)
+          end
+        end
+
+        # Register attribute if not already registered
+        attrib_obj = ChefObject.register(namespace, name, :attribute)
+        attrib_obj.source = statement.source
+        attrib_obj.docstring = docstring
+        attrib_obj.add_file(statement.file, statement.line)
+      end
+
+      # Get the docstring related to the attributes. The docstring is obtained
+      # from the ":description" field in the attribute.
+      #
+      # @return [YARD::Docstring] docstring for the attribute
+      #
+      def docstring
+        description = ""
+        path_array = parser.file.to_s.split('/')
+        if path_array.include?('metadata.rb')
+          # Suppose :description string have concatenation operator '+' then
+          # YARD builds an abstract syntax tree (AST). We need to traverse the
+          # tree to get the whole description string
+          statement.parameters[1].children.each do |ast_node|
+            if ast_node.jump(:ident).source == "description"
+              ast_node.traverse do |child|
+                description << child.jump(:string_content).source if child.type == :string_content
+              end
+            end
+          end
+        else
+          description = statement.comments
+        end
+        YARD::DocstringParser.new.parse(description).to_docstring
+      end
+    end
+  end
+end

data/lib/yard-chef/handlers/base.rb

@@ -0,0 +1,81 @@
+# 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::Handlers
+  module Chef
+    # Base handler for chef elements.
+    #
+    class Base < YARD::Handlers::Ruby::Base
+      include YARD::CodeObjects::Chef
+
+      # Gets the name of the handled object.
+      #
+      def name
+        statement.parameters.first.jump(:string_content, :ident).source
+      end
+
+      # Registers the cookbook in {YARD::Registry} and returns the same.
+      #
+      # @return [CookbookObject] the CookbookObject
+      #
+      def cookbook
+        cookbook_name = ""
+        path_array = File.expand_path(statement.file).to_s.split('/')
+        if path_array.include?('metadata.rb')
+          cookbook_name = path_array[path_array.index('metadata.rb') - 1]
+        else
+          cookbook_name = path_array[path_array.length - 3]
+        end
+        ChefObject.register(CHEF, cookbook_name, :cookbook)
+      end
+
+      # Registers the lightweight resource and provider in YARD::Registry and
+      # returns the same.
+      #
+      # @return [ResourceObject or ProviderObject] the lightweight resource or
+      # provider
+      #
+      def lwrp
+        path_array = File.expand_path(statement.file).to_s.split('/')
+        if path_array.include?("resources")
+          type = RESOURCE
+          type_sym = :resource
+        elsif path_array.include?("providers")
+          type = PROVIDER
+          type_sym = :provider
+        else
+          raise "Invalid LWRP type #{@path_array.join(',')}"
+        end
+        file_name = path_array.last.to_s.sub('.rb','')
+
+        cookbook_obj = cookbook
+        if file_name == "default"
+          lwrp_name = cookbook_obj.name
+        else
+          lwrp_name = "#{cookbook_obj.name}_#{file_name}"
+        end
+        ChefObject.register(type, lwrp_name, type_sym)
+      end
+    end
+  end
+end

data/lib/yard-chef/handlers/cookbook.rb

@@ -0,0 +1,94 @@
+# 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::Handlers
+  module Chef
+    # Handles specific cookbook information like README, description and version.
+    #
+    class CookbookHandler < Base
+      handles method_call(:description)
+      handles method_call(:version)
+
+      def process
+        return unless statement.file.to_s =~ /metadata.rb/
+
+        # Register the cookbook
+        cookbook_obj = cookbook
+        cookbook_obj.add_file(statement.file)
+        case statement.first.source
+        when 'description'
+          cookbook_obj.short_desc = name
+        when 'version'
+          cookbook_obj.version = name
+        end
+
+        # Get the README file for the cookbook
+        base_dir = File.dirname(statement.file)
+        if cookbook_obj.docstring == ''
+          cookbook_obj.docstring, cookbook_obj.docstring_type = docstring(base_dir)
+        end
+
+        # Get the top-level README for the cookbook repository if it exists
+        if CHEF.docstring == ''
+          readme_dir = File.expand_path('../..', base_dir)
+          CHEF.docstring, CHEF.docstring_type = docstring(readme_dir)
+        end
+      end
+
+      # Get the name of the method being handled.
+      #
+      # @return [String] the method name
+      #
+      def name
+        string = ""
+        # YARD builds an abstract syntax tree (AST) which we need to traverse
+        # to obtain the complete docstring
+        statement.parameters.first.traverse do |child|
+          string << child.jump(:string_content).source if child.type == :string_content
+        end
+        string
+      end
+
+      # Generates docstring from the README file.
+      #
+      # @return [YARD::Docstring] the docstring
+      #
+      def docstring(base_dir)
+        type = ''
+        string = ''
+        readme_path = base_dir + '/README.md'
+        if File.exists?(readme_path)
+          type = :markdown
+          string = IO.read(readme_path)
+        else
+          readme_path = base_dir + '/README.rdoc'
+          if File.exists?(readme_path)
+            type = :rdoc
+            string = IO.read(readme_path)
+          end
+        end
+        return YARD::DocstringParser.new.parse(string).to_docstring, type
+      end
+    end
+  end
+end