0
@@ -1,4 +1,96 @@
0
 module Sprinkle
0
+  # = Packages
0
+  #
0
+  # A package defines one or more things to provision onto the server.
0
+  # There is a lot of flexibility in a way a package is defined but
0
+  # let me give you a basic example:
0
+  #
0
+  #   package :ruby do
0
+  #     description 'Ruby MRI'
0
+  #     version '1.8.6'
0
+  #     apt 'ruby'
0
+  #
0
+  #     verify { has_executable 'ruby' }
0
+  #   end
0
+  #
0
+  # The above would define a package named 'ruby' and give it a description
0
+  # and explicitly say its version. It is installed via apt and to verify
0
+  # the installation was successful sprinkle will check for the executable
0
+  # 'ruby' being availble. Pretty simple, right?
0
+  #
0
+  # <b>Note:</b> Defining a package does not INSTALL it. To install a
0
+  # package, you must require it in a Sprinkle::Policy block. 
0
+  #
0
+  # == Pre-Requirements
0
+  #
0
+  # Most packages have some sort of pre-requisites in order to be installed.
0
+  # Sprinkle allows you to define the requirements of the package, which
0
+  # will be installed before the package itself. An example below:
0
+  #
0
+  #   package :rubygems do
0
+  #     source 'http://rubyforge.org/rubygems.tgz'
0
+  #     requires :ruby
0
+  #   end
0
+  #
0
+  # In this case, when rubygems is being installed, Sprinkle will first
0
+  # provision the server with Ruby to make sure the requirements are met.
0
+  # In turn, if ruby has requirements, it installs those first, and so on.
0
+  #
0
+  # == Verifications
0
+  #
0
+  # Most of the time its important to know whether the software you're 
0
+  # attempting to install was installed successfully or not. For this,
0
+  # Sprinkle provides verifications. Verifications are one or more blocks
0
+  # which define rules with which Sprinkle can check if it installed
0
+  # the package successfully. If these verification blocks fail, then 
0
+  # Sprinkle will gracefully stop the entire process. An example below:
0
+  #
0
+  #   package :rubygems do
0
+  #     source 'http://rubyforge.org/rubygems.tgz'
0
+  #     requires :ruby
0
+  #
0
+  #     verify { has_executable 'gem' }
0
+  #   end
0
+  #
0
+  # In addition to verifying an installation was successfully, by default
0
+  # Sprinkle runs these verifications <em>before</em> the installation to
0
+  # check if the package is already installed. If the verifications pass
0
+  # before installing the package, it skips the package. To override this
0
+  # behavior, set the -f flag on the sprinkle script or set the
0
+  # :force option to true in Sprinkle::OPTIONS
0
+  #
0
+  # For more information on verifications and to see all the available
0
+  # verifications, see Sprinkle::Verify
0
+  #
0
+  # == Virtual Packages
0
+  #
0
+  # Sometimes, there are multiple packages available for a single task. An
0
+  # example is a database package. It can contain mySQL, postgres, or sqlite!
0
+  # This is where virtual packages come in handy. They are defined as follows:
0
+  #
0
+  #   package :sqlite3, :provides => :database do
0
+  #     apt 'sqlite3'
0
+  #   end
0
+  #
0
+  # The :provides option allows you to reference this package either by :sqlite3
0
+  # or by :database. But whereas the package name is unique, multiple packages may
0
+  # share the same provision. If this is the case, when running Sprinkle, the 
0
+  # script will ask you which provision you want to install. At this time, you
0
+  # can only install one. 
0
+  #
0
+  # == Meta-Packages
0
+  #
0
+  # A package doesn't require an installer. If you want to define a package which
0
+  # merely encompasses other packages, that is fine too. Example:
0
+  #
0
+  #   package :meta do
0
+  #     requires :magic_beans
0
+  #     requires :magic_sauce
0
+  #   end
0
+  #
0
+  #--
0
+  # FIXME: Should probably document recommendations.
0
+  #++
0
   module Package
0
     PACKAGES = {}
0
 
0
@@ -13,7 +105,7 @@ module Sprinkle
0
       package
0
     end
0
 
0
-    class Package
0
+    class Package #:nodoc:
0
       include ArbitraryOptions
0
       attr_accessor :name, :provides, :installer, :dependencies, :recommends, :verifications
0
 

0
@@ -1,16 +1,56 @@
0
 require 'highline/import'
0
 
0
 module Sprinkle
0
+  # = Policies
0
+  #
0
+  # A policy defines a set of packages which are required for a certain
0
+  # role (app, database, etc.). All policies defined will be run and all
0
+  # packages required by the policy will be installed. So whereas defining
0
+  # a Sprinkle::Package merely defines it, defining a Sprinkle::Policy 
0
+  # actually causes those packages to install. 
0
+  #
0
+  # == A Basic Example
0
+  #
0
+  #   policy :blog, :roles => :app do
0
+  #     require :webserver
0
+  #     require :database
0
+  #     require :rails
0
+  #   end
0
+  #
0
+  # This says that for the blog on the app role, it requires certain 
0
+  # packages. The :roles option is <em>exactly</em> the same as a capistrano
0
+  # or vlad role. A role merely defines what server the commands are run
0
+  # on. This way, a single Sprinkle script can provision an entire group
0
+  # of servers. 
0
+  #
0
+  # To define a role, put in your actor specific configuration file (recipe or
0
+  # script file):
0
+  #
0
+  #   role :app, "208.28.38.44"
0
+  #
0
+  # The capistrano and vlad syntax is the same for that. If you're using a
0
+  # custom actor, you may have to do it differently.
0
+  #
0
+  # == Multiple Policies
0
+  #
0
+  # You may specify as many policies as you'd like. If the packages you're
0
+  # requiring are properly defined with verification blocks, then
0
+  # no software will be installed twice, so you may require a webserver on
0
+  # multiple packages within the same role without having to wait for
0
+  # that package to install repeatedly.
0
   module Policy
0
-    POLICIES = []
0
+    POLICIES = [] #:nodoc:
0
 
0
+    # Defines a single policy. Currently the only option, which is also
0
+    # required, is :roles, which defines which servers a policy is
0
+    # used on.
0
     def policy(name, options = {}, &block)
0
       p = Policy.new(name, options, &block)
0
       POLICIES << p
0
       p
0
     end
0
 
0
-    class Policy
0
+    class Policy #:nodoc:
0
       attr_reader :name, :packages
0
 
0
       def initialize(name, metadata = {}, &block)

0
@@ -1,8 +1,13 @@
0
 module Sprinkle
0
   module Verifiers
0
+    # = Directory Verifier
0
+    #
0
+    # Defines a verify which can be used to test the existence of a 
0
+    # directory.
0
     module Directory
0
       Sprinkle::Verify.register(Sprinkle::Verifiers::Directory)
0
       
0
+      # Tests that the directory <tt>dir</tt> exists.
0
       def has_directory(dir)
0
         @commands << "test -d #{dir}"
0
       end

0
@@ -1,8 +1,27 @@
0
 module Sprinkle
0
   module Verifiers
0
+    # = Executable Verifier
0
+    #
0
+    # Contains a verifier to check the existance of an executable
0
+    # script on your server.
0
+    # 
0
+    # == Example Usage
0
+    #
0
+    # First, absolute path to an executable:
0
+    #
0
+    #   verify { has_executable '/usr/special/secret/bin/scipt' }
0
+    #
0
+    # Second, a global executable which would be available anywhere on the
0
+    # command line:
0
+    #
0
+    #   verify { has_executable 'grep' }
0
     module Executable
0
       Sprinkle::Verify.register(Sprinkle::Verifiers::Executable)
0
       
0
+      # Checks if <tt>path</tt> is an executable script. This verifier is "smart" because
0
+      # if the path contains a forward slash '/' then it assumes you're checking an 
0
+      # absolute path to an executable. If no '/' is in the path, it assumes you're
0
+      # checking for a global executable that would be available anywhere on the command line.
0
       def has_executable(path)
0
         # Be smart: If the path includes a forward slash, we're checking
0
         # an absolute path. Otherwise, we're checking a global executable

0
@@ -1,8 +1,17 @@
0
 module Sprinkle
0
   module Verifiers
0
+    # = File Verifier
0
+    #
0
+    # Contains a verifier to check the existance of a file.
0
+    # 
0
+    # == Example Usage
0
+    #
0
+    #   verify { has_file '/etc/apache2/apache2.conf' }
0
+    #
0
     module File
0
       Sprinkle::Verify.register(Sprinkle::Verifiers::File)
0
       
0
+      # Checks to make sure <tt>path</tt> is a file on the remote server.
0
       def has_file(path)
0
         @commands << "test -f #{path}"
0
       end

0
@@ -1,8 +1,23 @@
0
 module Sprinkle
0
   module Verifiers
0
+    # = Symlink Verifier
0
+    #
0
+    # Contains a verifier to check the existance of a symbolic link.
0
+    # 
0
+    # == Example Usage
0
+    #
0
+    # First, checking for the existence of a symlink:
0
+    #
0
+    #   verify { has_symlink '/usr/special/secret/pointer' }
0
+    #
0
+    # Second, checking that the symlink points to a specific place:
0
+    #
0
+    #   verify { has_symlink '/usr/special/secret/pointer', '/usr/local/realfile' }
0
     module Symlink
0
       Sprinkle::Verify.register(Sprinkle::Verifiers::Symlink)
0
       
0
+      # Checks that <tt>symlink</tt> is a symbolic link. If <tt>file</tt> is 
0
+      # given, it checks that <tt>symlink</tt> points to <tt>file</tt>
0
       def has_symlink(symlink, file = nil)
0
         if file.nil?
0
           @commands << "test -L #{symlink}"

0
@@ -1,7 +1,66 @@
0
 module Sprinkle
0
+  # = Verification Methods
0
+  #
0
+  # As documented in Sprinkle::Package, you may define a block on a package
0
+  # which verifies that a package was installed correctly. If this verification
0
+  # block fails, Sprinkle will stop the script gracefully, raising the error.
0
+  # 
0
+  # In addition to checking post install if it was successfully, verification
0
+  # blocks are also ran before an install to see if a package is <em>already</em>
0
+  # installed. If this is the case, the package is skipped and Sprinkle continues
0
+  # with the next package. This behavior can be overriden by setting the -f flag on
0
+  # the sprinkle script or setting Sprinkle::OPTIONS[:force] to true if you're
0
+  # using sprinkle programmatically. 
0
+  #
0
+  # == An Example
0
+  #
0
+  # The following verifies that rails was installed correctly be checking to see
0
+  # if the 'rails' command is available on the command line:
0
+  #
0
+  #   package :rails do
0
+  #     gem 'rails'
0
+  #     
0
+  #     verify do
0
+  #       has_executable 'rails'
0
+  #     end
0
+  #   end
0
+  #
0
+  # == Available Verifiers
0
+  #
0
+  # There are a variety of available methods for use in the verification block.
0
+  # The standard methods are defined in the Sprinkle::Verifiers module, so see
0
+  # their corresponding documentation.
0
+  #
0
+  # == Custom Verifiers
0
+  # 
0
+  # If you feel that the built-in verifiers do not offer a certain aspect of
0
+  # verification which you need, you may create your own verifier! Simply wrap
0
+  # any method in a module which you want to use:
0
+  #
0
+  #   module MagicBeansVerifier
0
+  #     def has_magic_beans(sauce)
0
+  #       @commands << '[ -z "`echo $' + sauce + '`"]'
0
+  #     end
0
+  #   end
0
+  #
0
+  # The method can append as many commands as it wishes to the @commands array. 
0
+  # These commands will be run on the remote server and <b>MUST</b> give an
0
+  # exit status of 0 if successful or other if unsuccessful.
0
+  #
0
+  # To register your verifier, call the register method on Sprinkle::Verify:
0
+  #
0
+  #   Sprinle::Verify.register(MagicBeansVerifier)
0
+  #
0
+  # And now you may use it like any other verifier:
0
+  #
0
+  #   package :magic_beans do
0
+  #     gem 'magic_beans'
0
+  #     
0
+  #     verify { has_magic_beans('ranch') }
0
+  #   end
0
   class Verify
0
     include Sprinkle::Configurable
0
-    attr_accessor :package, :description, :commands
0
+    attr_accessor :package, :description, :commands #:nodoc:
0
     
0
     class <<self
0
       # Register a verification module
0
@@ -10,7 +69,7 @@ module Sprinkle
0
       end
0
     end
0
     
0
-    def initialize(package, description = '', &block)
0
+    def initialize(package, description = '', &block) #:nodoc:
0
       raise 'Verify requires a block.' unless block
0
       
0
       @package = package
0
@@ -22,7 +81,7 @@ module Sprinkle
0
       self.instance_eval(&block)
0
     end
0
     
0
-    def process(roles, pre = false)
0
+    def process(roles, pre = false) #:nodoc:
0
       assert_delivery
0
       
0
       description = @description.empty? ? @package.name : @description
0
@@ -42,7 +101,7 @@ module Sprinkle
0
     end
0
   end
0
   
0
-  class VerificationFailed < Exception
0
+  class VerificationFailed < Exception #:nodoc:
0
     attr_accessor :package, :description
0
     
0
     def initialize(package, description)