auser-sprinkle 0.1.5 → 0.1.6

data/Manifest.txt

@@ -2,12 +2,11 @@ CREDITS
 History.txt
 MIT-LICENSE
 Manifest.txt
-README.rdoc
+README.txt
 Rakefile
 bin/sprinkle
 config/hoe.rb
 config/requirements.rb
-examples/merb/deploy.rb
 examples/rails/README
 examples/rails/deploy.rb
 examples/rails/packages/database.rb
@@ -18,6 +17,7 @@ examples/rails/packages/server.rb
 examples/rails/rails.rb
 examples/sprinkle/sprinkle.rb
 lib/sprinkle.rb
+lib/sprinkle/actors/actors.rb
 lib/sprinkle/actors/capistrano.rb
 lib/sprinkle/actors/vlad.rb
 lib/sprinkle/configurable.rb
@@ -40,6 +40,8 @@ lib/sprinkle/script.rb
 lib/sprinkle/verifiers/directory.rb
 lib/sprinkle/verifiers/executable.rb
 lib/sprinkle/verifiers/file.rb
+lib/sprinkle/verifiers/process.rb
+lib/sprinkle/verifiers/ruby.rb
 lib/sprinkle/verifiers/symlink.rb
 lib/sprinkle/verify.rb
 lib/sprinkle/version.rb

data/config/hoe.rb

@@ -35,7 +35,7 @@ VERS = Sprinkle::VERSION::STRING + (REV ? ".#{REV}" : "")
 RDOC_OPTS = ['--quiet', '--title', 'sprinkle documentation',
     "--opname", "index.html",
     "--line-numbers", 
-    "--main", "README",
+    "--main", "README.txt",
     "--inline-source"]
 
 class Hoe
@@ -59,7 +59,7 @@ hoe = Hoe.new(GEM_NAME, VERS) do |p|
   # == Optional
   p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
   p.extra_deps = [ ['activesupport', '>= 2.0.2'], ['highline', '>= 1.4.0'], ['capistrano', '>= 2.2.0'] ]     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
-  
+
   #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
   
 end

data/lib/sprinkle.rb

@@ -18,11 +18,15 @@ module Sprinkle
   OPTIONS = { :testing => false, :verbose => false, :force => false }
 end
 
+# Object is extended to give the package, policy, and deployment methods. To
+# read about each method, see the corresponding module which is included.
+#--
 # Define a logging target and understand packages, policies and deployment DSL
+#++
 class Object
   include Sprinkle::Package, Sprinkle::Policy, Sprinkle::Deployment
 
-  def logger
+  def logger # :nodoc:
     @@__log__ ||= ActiveSupport::BufferedLogger.new($stdout, ActiveSupport::BufferedLogger::Severity::INFO)
   end
 end

data/lib/sprinkle/actors/actors.rb

@@ -0,0 +1,17 @@
+#--
+# The only point of this file is to give RDoc a definition for
+# Sprinkle::Actors. This file in production is never actually included
+# since ActiveSupport only on-demand loads classes which are needed
+# and this module is never explicitly needed.
+#++
+
+module Sprinkle
+  # An actor is a method of command delivery to a remote machine. It is the
+  # layer between sprinkle and the SSH connection to run commands. This gives
+  # you the flexibility to define custom actors, for whatever purpose you need.
+  #
+  # 99% of the time, however, the two built-in actors Sprinkle::Actors::Capistrano
+  # and Sprinkle::Actors::Vlad will be enough.
+  module Actors
+  end
+end

data/lib/sprinkle/actors/capistrano.rb

@@ -2,10 +2,26 @@ require 'capistrano/cli'
 
 module Sprinkle
   module Actors
+    # = Capistrano Delivery Method
+    #
+    # Capistrano is one of the delivery method options available out of the
+    # box with Sprinkle. If you have the capistrano gem install, you may use
+    # this delivery. The only configuration option available, and which is 
+    # mandatory to include is +recipes+. An example:
+    #
+    #   deployment do
+    #     delivery :capistrano do
+    #       recipes 'deploy'
+    #     end
+    #   end
+    #
+    # Recipes is given a list of files which capistrano will include and load.
+    # These recipes are mainly to set variables such as :user, :password, and to 
+    # set the app domain which will be sprinkled. 
     class Capistrano
-      attr_accessor :config, :loaded_recipes
+      attr_accessor :config, :loaded_recipes #:nodoc:
 
-      def initialize(&block)
+      def initialize(&block) #:nodoc:
         @config = ::Capistrano::Configuration.new
         @config.logger.level = Sprinkle::OPTIONS[:verbose] ? ::Capistrano::Logger::INFO : ::Capistrano::Logger::IMPORTANT
         @config.set(:password) { ::Capistrano::CLI.password_prompt }
@@ -16,13 +32,25 @@ module Sprinkle
         end
       end
 
+      # Defines a recipe file which will be included by capistrano. Use these
+      # recipe files to set capistrano specific configurations. Default recipe
+      # included is "deploy." But if any other recipe is specified, it will
+      # include that instead. Multiple recipes may be specified through multiple
+      # recipes calls, an example:
+      #
+      #   deployment do
+      #     delivery :capistrano do
+      #       recipes 'deploy'
+      #       recipes 'magic_beans'
+      #     end
+      #   end
       def recipes(script)
         @loaded_recipes ||= []
         @config.load script
         @loaded_recipes << script
       end
 
-      def process(name, commands, roles, suppress_and_return_failures = false)
+      def process(name, commands, roles, suppress_and_return_failures = false) #:nodoc:
         define_task(name, roles) do
           via = fetch(:run_method, :sudo)
           commands.each do |command|

data/lib/sprinkle/actors/vlad.rb

@@ -1,20 +1,46 @@
 module Sprinkle
   module Actors
+    # = Vlad Delivery Method
+    #
+    # Vlad is one of the delivery method options available out of the
+    # box with Sprinkle. If you have the vlad the deployer gem install, you 
+    # may use this delivery. The only configuration option available, and 
+    # which is mandatory to include is +script+. An example:
+    #
+    #   deployment do
+    #     delivery :vlad do
+    #       script 'deploy'
+    #     end
+    #   end
+    #
+    # script is given a list of files which capistrano will include and load.
+    # These recipes are mainly to set variables such as :user, :password, and to 
+    # set the app domain which will be sprinkled.
     class Vlad
       require 'vlad'
-      attr_accessor :loaded_recipes
+      attr_accessor :loaded_recipes #:nodoc:
 
-      def initialize(&block)
+      def initialize(&block) #:nodoc:
         self.instance_eval &block if block
       end
 
+      # Defines a script file which will be included by vlad. Use these
+      # script files to set vlad specific configurations. Multiple scripts
+      # may be specified through multiple script calls, an example:
+      #
+      #   deployment do
+      #     delivery :vlad do
+      #       script 'deploy'
+      #       script 'magic_beans'
+      #     end
+      #   end
       def script(name)
         @loaded_recipes ||= []
         self.load name
         @loaded_recipes << script
       end
 
-      def process(name, commands, roles, suppress_and_return_failures = false)
+      def process(name, commands, roles, suppress_and_return_failures = false) #:nodoc:
         commands = commands.join ' && ' if commands.is_a? Array
         t = remote_task(task_sym(name), :roles => roles) { run commands }
         

data/lib/sprinkle/configurable.rb

@@ -1,5 +1,8 @@
 module Sprinkle
-  module Configurable
+  #--
+  # TODO: Possible documentation?
+  #++
+  module Configurable #:nodoc:
     attr_accessor :delivery
     
     def defaults(deployment)

data/lib/sprinkle/deployment.rb

@@ -1,29 +1,69 @@
 module Sprinkle
+  # Deployment blocks specify deployment specific information about a 
+  # sprinkle script. An example:
+  #
+  #   deployment do
+  #     # mechanism for deployment
+  #     delivery :capistrano do
+  #       recipes 'deploy'
+  #     end
+  # 
+  #     # source based package installer defaults
+  #     source do
+  #       prefix   '/usr/local'
+  #       archives '/usr/local/sources'
+  #       builds   '/usr/local/build'
+  #     end
+  #   end
+  #
+  # What the above example does is tell sprinkle that we will be using
+  # *capistrano* (Sprinkle::Actors::Capistrano) for deployment and
+  # everything within the block is capistrano specific configuration.
+  # For more information on what options are available, check the corresponding
+  # Sprinkle::Actors doc page.
+  #
+  # In addition to what delivery mechanism we're using, we specify some
+  # configuration options for the "source" command. The only things
+  # configurable, at this time, in the deployment block other than
+  # the delivery method are installers. If installers are configurable,
+  # they will say so on their corresponding documentation page. See
+  # Sprinkle::Installers
+  #
+  # <b>Only one deployment block is on any given sprinkle script</b>
   module Deployment
+    # The method outlined above which specifies deployment specific information
+    # for a sprinkle script. For more information, read the header of this module.
     def deployment(&block)
       @deployment = Deployment.new(&block)
     end
 
     class Deployment
-      attr_accessor :style, :defaults
+      attr_accessor :style, :defaults #:nodoc:
 
-      def initialize(&block)
+      def initialize(&block) #:nodoc:
         @defaults = {}
         self.instance_eval(&block)
         raise 'No delivery mechanism defined' unless @style
       end
 
-      def delivery(type, &block)
+      # Specifies which Sprinkle::Actors to use for delivery. Although all
+      # actors jobs are the same: to run remote commands on a server, you
+      # may have a personal preference. The block you pass is used to configure
+      # the actor. For more information on what configuration options are
+      # available, view the corresponding Sprinkle::Actors page.
+      def delivery(type, &block) #:doc:
         @style = Actors.const_get(type.to_s.titleize).new &block
       end
 
-      def method_missing(sym, *args, &block)
+      def method_missing(sym, *args, &block) #:nodoc:
         @defaults[sym] = block
       end
 
-      def respond_to?(sym); !!@defaults[sym]; end
+      def respond_to?(sym) #:nodoc:
+        !!@defaults[sym]
+      end
 
-      def process
+      def process #:nodoc:
         POLICIES.each do |policy|
           policy.process(self)
         end

data/lib/sprinkle/extensions/arbitrary_options.rb

@@ -1,4 +1,4 @@
-module ArbitraryOptions
+module ArbitraryOptions #:nodoc:
   def self.included(base)
     base.alias_method_chain :method_missing, :arbitrary_options
   end

data/lib/sprinkle/extensions/array.rb

@@ -1,7 +1,5 @@
-class Array
-  
+class Array #:nodoc:
   def to_task_name
     collect(&:to_task_name).join('_')
   end
-  
 end

data/lib/sprinkle/extensions/blank_slate.rb

@@ -1,4 +1,4 @@
-class BlankSlate
+class BlankSlate #:nodoc:
   instance_methods.each do |m| 
     undef_method(m) unless %w( __send__ __id__ send class inspect instance_eval instance_variables ).include?(m)
   end

data/lib/sprinkle/extensions/dsl_accessor.rb

@@ -1,4 +1,4 @@
-class Module
+class Module #:nodoc:
   def dsl_accessor(*symbols)
     symbols.each do |sym|
       class_eval %{

data/lib/sprinkle/extensions/string.rb

@@ -1,4 +1,4 @@
-class String
+class String #:nodoc:
   
   # REVISIT: what chars shall we allow in task names?
   def to_task_name

data/lib/sprinkle/extensions/symbol.rb

@@ -1,4 +1,4 @@
-class Symbol
+class Symbol #:nodoc:
   
   def to_task_name
     to_s.to_task_name

data/lib/sprinkle/installers/apt.rb

@@ -1,9 +1,35 @@
 module Sprinkle
   module Installers
+    # = Apt Package Installer
+    #
+    # The Apt package installer uses the +apt-get+ command to install
+    # packages. The apt installer has only one option which can be
+    # modified which is the +dependencies_only+ option. When this is
+    # set to true, the installer uses +build-dep+ instead of +install+
+    # to only build the dependencies.
+    # 
+    # == Example Usage
+    #
+    # First, a simple installation of the magic_beans package:
+    #
+    #   package :magic_beans do
+    #     description "Beans beans they're good for your heart..."
+    #     apt 'magic_beans_package'
+    #   end
+    #
+    # Second, only build the magic_beans dependencies:
+    #
+    #   package :magic_beans_depends do
+    #     apt 'magic_beans_package' { dependencies_only true }
+    #   end
+    #
+    # As you can see, setting options is as simple as creating a
+    # block and calling the option as a method with the value as 
+    # its parameter.
     class Apt < Installer
-      attr_accessor :packages
+      attr_accessor :packages #:nodoc:
 
-      def initialize(parent, *packages, &block)
+      def initialize(parent, *packages, &block) #:nodoc:
         super parent, &block
         packages.flatten!
         
@@ -16,7 +42,7 @@ module Sprinkle
 
       protected
 
-        def install_commands
+        def install_commands #:nodoc:
           "DEBCONF_TERSE='yes' DEBIAN_PRIORITY='critical' DEBIAN_FRONTEND=noninteractive apt-get -qyu #{@command} #{@packages.join(' ')}"
         end
 

data/lib/sprinkle/installers/gem.rb

@@ -1,14 +1,42 @@
 module Sprinkle
   module Installers
+    # = Ruby Gem Package Installer
+    #
+    # The gem package installer installs ruby gems.
+    #
+    # The installer has a single optional configuration: source.
+    # By changing source you can specify a given ruby gems
+    # repository from which to install.
+    # 
+    # == Example Usage
+    #
+    # First, a simple installation of the magic_beans gem:
+    #
+    #   package :magic_beans do
+    #     description "Beans beans they're good for your heart..."
+    #     gem 'magic_beans'
+    #   end
+    #
+    # Second, install magic_beans gem from github:
+    #
+    #   package :magic_beans do
+    #     gem 'magic_beans_package' do
+    #       source 'http://gems.github.com'
+    #     end
+    #   end
+    #
+    # As you can see, setting options is as simple as creating a
+    # block and calling the option as a method with the value as 
+    # its parameter.
     class Gem < Installer
-      attr_accessor :gem
+      attr_accessor :gem #:nodoc:
 
-      def initialize(parent, gem, options = {}, &block)
+      def initialize(parent, gem, options = {}, &block) #:nodoc:
         super parent, options, &block
         @gem = gem
       end
 
-      def source(location = nil)
+      def source(location = nil) #:nodoc:
         # package defines an installer called source so here we specify a method directly
         # rather than rely on the automatic options processing since packages' method missing
         # won't be run
@@ -20,7 +48,7 @@ module Sprinkle
 
         # rubygems 0.9.5+ installs dependencies by default, and does platform selection
 
-        def install_commands
+        def install_commands #:nodoc:
           cmd = "gem install #{gem}"
           cmd << " --version '#{version}'" if version
           cmd << " --source #{source}" if source

data/lib/sprinkle/installers/installer.rb

@@ -1,10 +1,49 @@
 module Sprinkle
   module Installers
+    # The base class which all installers must subclass, this class makes
+    # sure all installers share some general features, which are outlined
+    # below. 
+    #
+    # = Pre/Post Installation Hooks
+    # 
+    # With all intallation methods you have the ability to specify multiple
+    # pre/post installation hooks. This gives you the ability to specify
+    # commands to run before and after an installation takes place. All 
+    # commands by default are sudo'd so there is no need to include "sudo"
+    # in the command itself. There are three ways to specify a pre/post hook.
+    # 
+    # First, a single command:
+    #
+    #   pre :install, 'echo "Hello, World!"'
+    #   post :install, 'rm -rf /'
+    #
+    # Second, an array of commands:
+    #
+    #   commands = ['echo "First"', 'echo "Then Another"']
+    #   pre :install, commands
+    #   post :install, commands
+    #
+    # Third, a block which returns either a single or multiple commands:
+    #
+    #   pre :install do
+    #     amount = 7 * 3
+    #     "echo 'Before we install, lets plant #{amount} magic beans...'"
+    #   end
+    #   post :install do
+    #     ['echo "Now... let's hope they sprout!", 'echo "Indeed they have!"']
+    #   end
+    #
+    # = Other Pre/Post Hooks
+    #
+    # Some installation methods actually grant you more fine grained
+    # control of when commands are run rather than a blanket pre :install
+    # or post :install. If this is the case, it will be documented on
+    # the installation method's corresponding documentation page. 
     class Installer
       include Sprinkle::Configurable
-      attr_accessor :delivery, :package, :options, :pre, :post
+      attr_accessor :delivery, :package, :options, :pre, :post #:nodoc:
 
-      def initialize(package, options = {}, &block)
+      def initialize(package, options = {}, &block) #:nodoc:
         @package = package
         @options = options
         @pre = {}; @post = {}
@@ -23,7 +62,7 @@ module Sprinkle
         @post[stage] += [yield] if block_given?
       end
 
-      def process(roles)
+      def process(roles) #:nodoc:
         assert_delivery
 
         if logger.debug?
@@ -38,35 +77,42 @@ module Sprinkle
       end
 
       protected
-
-        # Installation is separated into two styles that concrete derivative installer classes
-        # can implement.
-        #
-        # Simple installers that issue a single or set of commands can overwride
-        # install_commands (eg. apt, gem, rpm). Pre/post install commands are included in this
-        # style for free.
-        #
         # More complicated installers that have different stages, and require pre/post commands
         # within stages can override install_sequence and take complete control of the install
         # command sequence construction (eg. source based installer).
-
         def install_sequence
           commands = pre_commands(:install) + [ install_commands ] + post_commands(:install)
           commands.flatten
         end
 
+        # A concrete installer (subclass of this virtual class) must override this method
+        # and return the commands it needs to run as either a string or an array. 
+        #
+        # <b>Overriding this method is required.</b>
         def install_commands
           raise 'Concrete installers implement this to specify commands to run to install their respective packages'
         end
 
-        def pre_commands(stage)
+        def pre_commands(stage) #:nodoc:
           dress @pre[stage] || [], :pre
         end
 
-        def post_commands(stage)
+        def post_commands(stage) #:nodoc:
           dress @post[stage] || [], :post
         end
 
+        # Concrete installers (subclasses of this virtual class) can override this method to
+        # specify stage-specific (pre-installation, post-installation, etc.) modifications
+        # of commands. 
+        #
+        # An example usage of overriding this would be to prefix all commands for a 
+        # certain stage to change to a certain directory. An example is given below:
+        #
+        #   def dress(commands, stage)
+        #     commands.collect { |x| "cd #{magic_beans_path} && #{x}" }
+        #   end
+        #
+        # By default, no modifications are made to the commands.
         def dress(commands, stage); commands; end
 
     end