LICENSE README @@ -21,7 +21,7 @@ Rake::TestTask.new(:test) do |t| end Rake::RDocTask.new do |rd| - rd.main = "README.rdoc" - rd.rdoc_files.include("README.rdoc", "lib/**/*.rb") + rd.main = "README" + rd.rdoc_files.include("README", "LICENSE", "lib/**/*.rb") rd.rdoc_dir = "doc" end Rakefile @@ -9,35 +9,42 @@ require "bob/scm/git" require "bob/background_engines" module Bob - # Builds the specified +buildable+. This object must understand the following API: + # Builds the specified <tt>buildable</tt>. This object must understand the following API: # - # * buildable.repo_kind - # Should return a Symbol with whatever kind of repository the buildable's code is - # in (:git, :svn, etc). - # * buildable.repo_uri - # Returns a string like "git://github.com/integrity/bob.git", pointing to the code - # repository. - # * buildable.repo_branch - # What branch of the repository should we build? - # * buildable.build_script - # Returns a string containing the command to be run when "building". - # * buildable.start_building(commit_id) - # `commit_id` is a String that contains whatever is appropriate for the repo type, - # so it would be a SHA1 hash for git repos, or a numeric id for svn, etc. This is a - # callback so the buildable can determine how long it takes to build. It doesn't - # need to return anything. - # * buildable.add_successful_build(commit_id, build_output) - # Called when the build finishes and is successful. It doesn't need to return - # anything. - # * buildable.add_failed_build(commit_id, build_output) - # Called when the build finishes and it failed. It doesn't need to return anything. + # * <tt>buildable.repo_kind</tt> + # + # Should return a Symbol with whatever kind of repository the buildable's code is + # in (:git, :svn, etc). + # * <tt>buildable.repo_uri</tt> + # + # Returns a string like "git://github.com/integrity/bob.git", pointing to the code + # repository. + # * <tt>buildable.repo_branch</tt> + # + # What branch of the repository should we build? + # * <tt>buildable.build_script</tt> + # + # Returns a string containing the command to be run when "building". + # * <tt>buildable.start_building(commit_id)</tt> + # + # `commit_id` is a String that contains whatever is appropriate for the repo type, + # so it would be a SHA1 hash for git repos, or a numeric id for svn, etc. This is a + # callback so the buildable can determine how long it takes to build. It doesn't + # need to return anything. + # * <tt>buildable.add_successful_build(commit_id, build_output)</tt> + # + # Called when the build finishes and is successful. It doesn't need to return + # anything. + # * <tt>buildable.add_failed_build(commit_id, build_output)</tt> + # + # Called when the build finishes and it failed. It doesn't need to return anything. # # The build process is to fetch the code from the repository (determined by - # +buildable.repo_kind+ and +buildable.repo_uri+), then checkout the specified - # +commid_ids+, and finally run +buildable.build_script+ on each. + # <tt>buildable.repo_kind</tt> and <tt>buildable.repo_uri</tt>), then checkout the specified + # <tt>commid_ids</tt>, and finally run <tt>buildable.build_script</tt> on each. # - # If the script returns successfully then +buildable.add_successful_build+ will be - # called. If not, +buildable.add_failed_build+ is called instead. A successful build + # If the script returns successfully then <tt>buildable.add_successful_build</tt> will be + # called. If not, <tt>buildable.add_failed_build</tt> is called instead. A successful build # is one where the build script returns a zero status code. def self.build(buildable, *commit_ids) raise ArgumentError, "at least one commit_id must be specified" if commit_ids.empty? @@ -46,8 +53,8 @@ module Bob end end - # Dir where the code for the different buildables will be checked out. Make sure - # the user running bob has writing permission on this directory. + # Directory where the code for the different buildables will be checked out. Make sure + # the user running Bob is allowed to write to this directory. def self.base_dir @base_dir || "/tmp" end @@ -58,7 +65,7 @@ module Bob @logger || Logger.new(STDOUT) end - # What will you use to build in background. Must respond to #call and take a block + # What will you use to build in background. Must respond to <tt>call</tt> and take a block # which will be run "in background". The default is to run in foreground. def self.background_engine @background_engine || BackgroundEngines::Foreground lib/bob.rb @@ -8,9 +8,11 @@ module Bob @build_output = nil end - # This is where the magic happens: check out the repo to the - # appropriate commit and then run the build script on it, and - # finally reports the build. + # This is where the magic happens: + # + # 1. Check out the repo to the appropriate commit. + # 2. Run the build script on it in the background. + # 3. Reports the build back to the buildable. def build Bob.logger.info "Building #{commit_id} of the #{buildable.repo_kind} repo at #{buildable.repo_uri}" in_background do lib/bob/builder.rb @@ -8,7 +8,7 @@ module Bob @branch = branch end - # Checkout the code into +working_dir+ at the specified revision and + # Checkout the code into <tt>working_dir</tt> at the specified revision and # call the passed block def with_commit(commit_id) update_code @@ -17,16 +17,17 @@ module Bob end # Get some information about the specified commit. Returns a hash with: - # :author => Author name and email - # :message => Commit message - # :committed_at => Commit date + # + # [<tt>:author</tt>] Commit author's name and email + # [<tt>:message</tt>] Commit message + # [<tt>:committed_at</tt>] Commit date (as a string) def info(commit_id) format = %Q(---%n:author: %an <%ae>%n:message: >-%n %s%n:committed_at: %ci%n) YAML.load(`cd #{working_dir} && git show -s --pretty=format:"#{format}" #{commit_id}`) end - # Directory where the code will be checked out. Make sure the user running - # Bob is allowed to write to this directory (or you'll get a Errno::EACCESS) + # Directory where the code will be checked out. Make sure the user running Bob is + # allowed to write to this directory (or you'll get a <tt>Errno::EACCESS</tt>) def working_dir @working_dir ||= "#{Bob.base_dir}/#{path_from_uri}".tap do |path| FileUtils.mkdir_p path lib/bob/scm/git.rb README.rdoc 4e72c9cbe4aabad4bbc4a11b4070599b23143ef1 Nicolas Sanguinetti contacto@nicolassanguinetti.info http://github.com/sr/bob/commit/c9d56ad6896965f104f9cf5a4bea301cb8c32e2a c9d56ad6896965f104f9cf5a4bea301cb8c32e2a 2009-04-12T12:24:44-07:00 2009-04-12T12:24:44-07:00 Make the comments more rdoc friendly 03a8d2cb3e6615c92a36e319d092b166793ed4d3 Nicolas Sanguinetti contacto@nicolassanguinetti.info