marionetta 0.4.1 → 0.4.2

data/README.md

@@ -1,7 +1,7 @@
 # Marionetta
 
-Marionetta is a ruby library for executing commands on one
-or more remote machines via SSH.
+[Marionetta][marionetta] is a ruby library for executing
+commands on one or more remote machines via SSH.
 
 It provides puppet provisioning without the need for a puppet
 master and can also deploy your application code (with
@@ -22,6 +22,21 @@ source 'http://rubygems.org'
 gem 'marionetta'
 ```
 
+[marionetta]: http://drpheltright.github.com/marionetta/
+
+## Documentation
+
+Marionetta has [annotated source][docs] that provides the
+bulk of documentation for Marionetta. Hopefully you'll find
+the annotations informative on *how to use* this library. If
+you feel they could be improved please create an issue on
+GitHub.
+
+If you prefer looking at the code, check it out on [github][github].
+
+[docs]: http://drpheltright.github.com/marionetta/docs/marionetta.html
+[github]: http://github.com/DrPheltRight/marionetta/
+
 ## Using Marionetta in your Rakefile
 
 Marionetta provides an easy mechanism to generate rake tasks
@@ -153,6 +168,12 @@ staging.manipulate_each_server(:deployer, :rollback)
 
 Luke Morton a.k.a. DrPheltRight
 
+## Collaborating
+
+Create an issue and send a pull request if you get any bright
+ideas or have a fix. Feel free to create an issue and not send
+one too, feedback is always welcome.
+
 ## License
 
-MIT
+Licensed under MIT by Luke Morton, 2012.

data/lib/marionetta/command_runner.rb

@@ -27,9 +27,15 @@ module Marionetta
     
     ### Local execution
 
-    # Local commands are executed with `.system()`. You can
-    # optionally pass in a block which receives `stdout` and
-    # `stderr` as arguments:
+    # Local commands are executed with `.system()`. We use
+    # `Open4::popen4` to capture the output of the command run
+    # neatly.
+    # 
+    # The command run is logged as info, output as debug and
+    # any exceptions thrown are sent as fatal.
+    # 
+    # You can optionally pass in a block which receives
+    # `stdout` and `stderr` as arguments:
     # 
     #     cmd.system('ls ~') do |out, err|
     #       puts out
@@ -57,6 +63,28 @@ module Marionetta
       return status.exitstatus == 0
     end
 
+    # Create an archive of a local directory, optionally
+    # saving it to a directory or file path.
+    # 
+    def archive(directory, save_to = nil)
+      if save_to.nil?
+        save_to = "#{directory}.#{server[:archive][:ext]}"
+      elsif File.directory?(save_to)
+        dirname = File.basename(directory)
+        save_to = "#{save_to}/#{dirname}.#{server[:archive][:ext]}"
+      end
+
+      archive_cmd = [
+        server[:archive][:command],
+        server[:archive][:flags],
+        ['-f', save_to],
+        ['-C', File.dirname(directory)],
+        File.basename(directory),
+      ]
+
+      system(*archive_cmd.flatten)
+    end
+
     # The last command run by `.system()` is accessible via
     # the `.last` attribute.
     # 
@@ -72,7 +100,7 @@ module Marionetta
     # A block can be called against this method just like
     # `.system()` in order to get `stdout` and `stderr`.
     # 
-    # An example:
+    # Example:
     # 
     #     server = Marionetta.default_server
     #     server[:hostname] = 'example.com'
@@ -96,25 +124,9 @@ module Marionetta
       system(*ssh_cmd.flatten, &block)
     end
 
-    def archive(directory, save_to = nil)
-      if save_to.nil?
-        save_to = "#{directory}.#{server[:archive][:ext]}"
-      elsif File.directory?(save_to)
-        dirname = File.basename(directory)
-        save_to = "#{save_to}/#{dirname}.#{server[:archive][:ext]}"
-      end
-
-      archive_cmd = [
-        server[:archive][:command],
-        server[:archive][:flags],
-        ['-f', save_to],
-        ['-C', File.dirname(directory)],
-        File.basename(directory),
-      ]
-
-      system(*archive_cmd.flatten)
-    end
-
+    # Extract an archive, optionally to a specified directory
+    # on a remote machine.
+    # 
     def ssh_extract(archive_path, save_to = File.dirname(archive_path))
       cmds = [
         "mkdir -p #{save_to}",
@@ -132,6 +144,15 @@ module Marionetta
       ssh(cmds.join(' && '))
     end
 
+    # Using the rsync command copy one file system location to
+    # another. These may be both local or remote, or a mixture
+    # of the two.
+    # 
+    # Example:
+    # 
+    #     rsync('/var/www/logs', '/var/backups/www/logs')
+    #     rsync('/var/www/logs', 'ubuntu@example.com:/var/backups/www/logs')
+    # 
     def rsync(from, to)
       rsync_cmd = [server[:rsync][:command]]
 
@@ -144,10 +165,18 @@ module Marionetta
       system(*rsync_cmd.flatten)
     end
 
+    # Short hand for grabbing a file from `:hostname` saving
+    # to the same location on the local machine unless a path
+    # is specified. 
+    # 
     def get(file_path, save_to = File.dirname(file_path))
       rsync("#{server[:hostname]}:#{file_path}", save_to)
     end
 
+    # Short hand for putting a file to `:hostname` from the
+    # local machine to the same location on the remote
+    # machine unless a path is specified.
+    # 
     def put(file_path, save_to = File.dirname(file_path))
       rsync(file_path, "#{server[:hostname]}:#{save_to}")
     end

data/lib/marionetta/group.rb

@@ -1,21 +1,40 @@
+# `Group` represents a collection of `server` hashes and
+# provides `.each_server()` and `.manipulate_each_server` as
+# isolated interation methods.
+# 
+# You can also nest groups within other groups so that
+# multiple groups can be operated on at once.
+# 
+# The external requirement for this file is `celluloid` so we
+# can iterate over `@servers` in parallel.
+# 
 require 'marionetta'
 require 'marionetta/manipulators'
 require 'celluloid'
 
 module Marionetta
   class Group
-    attr_reader :name
 
+    # Group name is currently optional.
+    # 
     def initialize(name = nil)
       @name = name
       @groups = []
       @servers = []
     end
 
+    # The name of the group.
+    # 
+    attr_reader :name
+
+    # Nest a group using `.add_group()`.
+    # 
     def add_group(group)
       @groups << group
     end
 
+    # Get all descending groups contained within this group.
+    # 
     def groups()
       groups = @groups
 
@@ -26,12 +45,25 @@ module Marionetta
       return groups
     end
 
+    # Add a `server` hash or build on the default server in a
+    # block.
+    # 
+    # Example:
+    # 
+    #     staging = Marionetta::Group.new(:staging)
+    #     staging.add_server(:hostname => 'ubuntu@example.com')
+    #     staging.add_server do |s|
+    #       s[:hostname] = 'ubuntu@example.com'
+    #     end
+    # 
     def add_server(server = nil)
       server ||= Marionetta.default_server
       yield server if block_given?
       @servers << server
     end
 
+    # Get servers in this group and all descendant groups.
+    # 
     def servers()
       servers = @servers
 
@@ -42,6 +74,16 @@ module Marionetta
       return servers
     end
 
+    # Iterate over each `server` definition (including nested
+    # servers) in parallel by passing a block.
+    # 
+    #     each_server do |s|
+    #       cmd = Marionetta::CommandRunner.new(s)
+    #       cmd.ssh('whoami') do |out|
+    #         puts out.read
+    #       end
+    #     end
+    # 
     def each_server()
       futures = []
 
@@ -62,6 +104,15 @@ module Marionetta
       return return_values
     end
 
+    # Manipulate each server by passing a manipulator key as
+    # registered with `Manipulators` and a method name.
+    # 
+    # If manipulator cannot be run on a server definition then
+    # a warn message will be logged.
+    # 
+    # If block passed in then the server and return value for
+    # each server will be passed in when complete.
+    # 
     def manipulate_each_server(manipulator_name, method_name)
       each_server do |s|
         manipulator = Manipulators[manipulator_name].new(s)

data/lib/marionetta/manipulators/puppet_manipulator.rb

@@ -144,7 +144,7 @@ module Marionetta
         puppet_cmd = ['sudo puppet apply']
 
         if server[:puppet].has_key?(:modules)
-          puppet_cmd << '--modulepath=/tmp/puppet/modules'
+          puppet_cmd << "--modulepath=#{puppet_tmp}/modules"
         end
 
         puppet_cmd << 'manifest.pp'

data/lib/marionetta/manipulators.rb

@@ -1,9 +1,25 @@
+# `Manipulators` is a container for registering manipulators.
+# 
+# The interface of a manipulator is:
+# 
+#     self.tasks()        an array of methods to expose via
+#                         RakeHelpers *optional*
+# 
+#     initialize(server)  *required*
+#     can?()              *required*
+#     
 module Marionetta
   module Manipulators
+
+    # We automatically require the manipulators packaged with
+    # this library. *Is this a good idea?*
+    # 
     require_relative 'manipulators/deployer'
     require_relative 'manipulators/debloyer'
     require_relative 'manipulators/puppet_manipulator'
 
+    # A hash of all the manipulators.
+    # 
     def self.all()
       {
         :deployer => Deployer,
@@ -12,6 +28,8 @@ module Marionetta
       }
     end
 
+    # Get a manipulator.
+    # 
     def self.[](key)
       all[key]
     end

data/lib/marionetta/rake_helper.rb

@@ -1,3 +1,9 @@
+# `RakeHelper` is provided for those of you who wish to use
+# Marionetta in your `Rakefile`.
+# 
+# One method is provided to expose tasks of a specified group,
+# `.install_group_tasks(group)`.
+# 
 require 'marionetta'
 require 'marionetta/manipulators'
 require 'rake'

data/lib/marionetta.rb

@@ -1,5 +1,5 @@
-# Marionetta is a ruby library for executing commands on one
-# or more remote machines via SSH.
+# [Marionetta][homepage] is a ruby library for executing
+# commands on one or more remote machines via SSH.
 # 
 # It provides puppet provisioning without the need for a
 # puppet master and can also deploy your application code
@@ -21,12 +21,13 @@
 # where you can report issues and send your well thought out
 # pull requests.
 # 
+# [homepage]: http://drpheltright.github.com/marionetta/
+# [github]: https://github.com/DrPheltRight/marionetta/
 # [author]: http://lukemorton.co.uk
-# [github]: https://github.com/DrPheltRight/marionetta
 # 
 module Marionetta
 
-  VERSION = '0.4.1'
+  VERSION = '0.4.2'
 
   ### Defining Servers
 

data/marionetta.gemspec

@@ -3,10 +3,14 @@ require File.dirname(__FILE__)+'/lib/marionetta'
 Gem::Specification.new do |s|
   s.name        = "marionetta"
   s.version     = Marionetta::VERSION
+  
   s.homepage    = 'https://github.com/DrPheltRight/marionetta'
+
   s.authors     = ["Luke Morton"]
   s.email       = ["lukemorton.dev@gmail.com"]
+
   s.summary     = "Provision using puppet and deploy your servers over SSH."
+
   s.description = "Marionetta is a ruby library for executing commands on one
                    or more remote machines via SSH. It provides puppet
                    provisioning without the need for a puppet master and can

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: marionetta
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-21 00:00:00.000000000 Z
+date: 2012-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: open4