pivotal_doc 1.1.0

data/ext/date.rb

@@ -0,0 +1,9 @@
+class Date
+  def standard_format
+    self.strftime("%m-%d-%Y")
+  end
+  
+  def fancy_format
+    self.strftime("%b %d, %Y")    
+  end
+end

data/lib/pivotal_doc/configuration.rb

@@ -0,0 +1,37 @@
+module PivotalDoc
+  class Configuration
+    attr_accessor :settings
+    attr_reader :authenticated
+    alias :authenticated? :authenticated
+
+    def initialize(settings)
+      @settings= settings.respond_to?(:merge) ? settings : YAML::load(File.new(settings))
+    end
+    
+    def projects
+      self.settings['projects']
+    end
+    
+    def output_path
+      self.settings['output_path']
+    end
+    
+    def authenticate!
+      return if @authenticated
+      connection.token ? PT::Client.token=connection.token : PT::Client.token(connection.username, connection.password)
+      @authenticated= true
+    end
+
+    private
+    def connection
+      return @connection if @connection
+      @connection= Connection.new
+      @connection.token= settings['token']
+      @connection.username= settings['username']
+      @connection.password= settings['password']
+      @connection
+    end
+  end
+
+  class Connection < Struct.new(:token, :username, :password); end
+end

data/lib/pivotal_doc/exceptions.rb

@@ -0,0 +1,22 @@
+module PivotalDoc
+  class PivotalDocException < Exception
+  end
+  class FormatNotSupported < PivotalDocException
+    def initialize(format)
+      @format= format
+    end
+    
+    def message
+      "The format (#{@format}) is not currently supported"
+    end
+  end
+  class TemplateNonExistent < PivotalDocException
+    def initialize(template_name)
+      @template_name= template_name
+    end
+    
+    def message
+      "The template named \"#{@template_name}\" doesn't exist?"
+    end    
+  end
+end

data/lib/pivotal_doc/generator.rb

@@ -0,0 +1,30 @@
+module PivotalDoc
+  class Generator    
+    class << self
+      attr_accessor :releases
+      attr_reader :config
+      
+      def generate(format, settings={})
+        @config= PivotalDoc::Configuration.new(settings)
+        @config.authenticate!
+        raise FormatNotSupported.new(format) unless generators.has_key?(format)
+        collect_releases!
+        releases.each do |release|          
+          generators[format].new(release, config.settings).render_doc
+        end
+        true
+      end
+    
+      def generators
+        { :text=>Generators::Text, :html=>Generators::HTML }
+      end
+    
+      def collect_releases!
+        @releases= []
+        self.config.projects.each do |name, _attrs|
+          @releases << Release.new(PT::Project.find(_attrs['id'].to_i))
+        end
+      end
+    end    
+  end
+end

data/lib/pivotal_doc/generators/base.rb

@@ -0,0 +1,52 @@
+module PivotalDoc
+  module Generators
+    class Base
+      def initialize(release, options={})
+        @release= release
+        @options= options
+      end
+      
+      def output_path
+        @options['output_path'] || absolute_path
+      end
+      
+      def output_file
+        name= @options['output_file']
+        unless name
+          name=@release.name || self.object_id.to_s
+          name.gsub!(/\//, '') and name.gsub!(/\s/,'')
+        end
+        File.join(output_path, (name + output_ext))  
+      end
+      
+      def output_ext; '.default' end
+      
+      def absolute_path
+        File.dirname(__FILE__)
+      end
+      
+      def render_doc(output='')
+        begin
+          FileUtils.mkdir_p(output_path)
+          f= File.open(self.output_file, 'w+')
+          f.write(output)
+        rescue Exception=>e
+          $stdout.print(e.message)
+          $stdout.flush
+        ensure
+          f.close if f
+        end
+      end
+      
+      def template
+        path= File.join(PROJECT_ROOT, 'templates', template_name)
+        raise TemplateNonExistent.new(template_name) unless File.exists?(path)
+        @template ||= File.read(path)
+      end      
+      
+      def template_name
+        raise 'Not Implemented!'
+      end
+    end
+  end
+end

data/lib/pivotal_doc/generators/html.rb

@@ -0,0 +1,14 @@
+module PivotalDoc
+  module Generators
+    class HTML < Base  
+      def template_name
+        @options[:template_name] || 'html_gen.haml' 
+      end
+      def output_ext; '.html' end
+      def render_doc
+        html= Haml::Engine.new(template).render(Object.new, {:release=>@release})
+        super(html)
+      end
+    end
+  end
+end

data/lib/pivotal_doc/generators/text.rb

@@ -0,0 +1,12 @@
+module PivotalDoc
+  module Generators
+    class Text < Base
+      def template_name; 'text_gen.txt' end
+      def output_ext; '.txt' end
+      def output; '' end
+      def render_doc
+        super(output)
+      end
+    end
+  end
+end

data/lib/pivotal_doc/release.rb

@@ -0,0 +1,50 @@
+module PivotalDoc
+  class Release
+    attr_reader :project
+    attr_reader :iteration
+  
+    def initialize(project, iteration=nil)
+      @project= project
+      @iteration= (iteration || latest_iteration)
+    end
+    
+    def me
+      @me ||= self.iteration.stories.detect{|s| s.story_type.downcase=='release'} if self.iteration.stories
+    end
+    
+    def name
+      me.name if me.respond_to?(:name) 
+    end
+  
+    def project_name
+      @project.name
+    end
+  
+    def latest_iteration
+      PT::Iteration.done(@project, :offset=>'-1').first
+    end     
+    
+    def stories
+      @stories ||= filter_stories
+    end
+  
+    def bugs
+      @bugs ||= filter_stories('bug')
+    end    
+  
+    def chores
+      @chores ||= filter_stories('chore')
+    end
+    
+    [:stories, :bugs, :chores].each do |m|
+      define_method("#{m}_delivered") { self.send(m).size }
+    end
+    
+    private
+    def filter_stories(type='feature')
+      self.iteration.stories.reject do |s|
+        s.story_type.downcase != type || s.current_state.downcase != 'accepted'
+      end
+    end
+  end
+end

data/lib/pivotal_doc.rb

@@ -0,0 +1,14 @@
+require 'rubygems'
+require 'yaml'
+require 'pivotal-tracker'
+require 'haml'
+PT= PivotalTracker unless defined?(PT)
+PROJECT_ROOT= File.join(File.dirname(__FILE__), '/../') unless defined?(PROJECT_ROOT)
+
+Dir[File.expand_path(File.join(File.dirname(__FILE__),'../ext','**','*.rb'))].each {|f| require f}
+Dir[File.expand_path(File.join(File.dirname(__FILE__),'pivotal_doc/','**','*.rb'))].each {|f| require f}
+
+if ENV['mode'] == 'test'
+  require 'spec'
+  require 'spec/autorun'
+end

data/pivotal_doc.gemspec

@@ -0,0 +1,106 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{pivotal_doc}
+  s.version = "1.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Tim Linquist"]
+  s.date = %q{2010-10-29}
+  s.description = %q{
+        Automated release notes for apps hosted on pivotaltracker.com.  
+        Allows release notes to be generated for any project on pivotaltracker.com by retrieving the latest iteration for the specified project and displaying the completed features, bugs, and chores.
+      }
+  s.email = %q{tim.linquist@gmail.com}
+  s.extra_rdoc_files = [
+    "README"
+  ]
+  s.files = [
+    ".gitignore",
+     "README",
+     "Rakefile",
+     "VERSION",
+     "assets/css/ui-lightness/images/ui-bg_diagonals-thick_18_b81900_40x40.png",
+     "assets/css/ui-lightness/images/ui-bg_diagonals-thick_20_666666_40x40.png",
+     "assets/css/ui-lightness/images/ui-bg_flat_10_000000_40x100.png",
+     "assets/css/ui-lightness/images/ui-bg_glass_100_f6f6f6_1x400.png",
+     "assets/css/ui-lightness/images/ui-bg_glass_100_fdf5ce_1x400.png",
+     "assets/css/ui-lightness/images/ui-bg_glass_65_ffffff_1x400.png",
+     "assets/css/ui-lightness/images/ui-bg_gloss-wave_35_f6a828_500x100.png",
+     "assets/css/ui-lightness/images/ui-bg_highlight-soft_100_eeeeee_1x100.png",
+     "assets/css/ui-lightness/images/ui-bg_highlight-soft_75_ffe45c_1x100.png",
+     "assets/css/ui-lightness/images/ui-icons_222222_256x240.png",
+     "assets/css/ui-lightness/images/ui-icons_228ef1_256x240.png",
+     "assets/css/ui-lightness/images/ui-icons_ef8c08_256x240.png",
+     "assets/css/ui-lightness/images/ui-icons_ffd27a_256x240.png",
+     "assets/css/ui-lightness/images/ui-icons_ffffff_256x240.png",
+     "assets/css/ui-lightness/jquery-ui-1.8.5.custom.css",
+     "assets/js/jquery-1.4.2.min.js",
+     "assets/js/jquery-ui-1.8.5.custom.min.js",
+     "ext/date.rb",
+     "lib/pivotal_doc.rb",
+     "lib/pivotal_doc/configuration.rb",
+     "lib/pivotal_doc/exceptions.rb",
+     "lib/pivotal_doc/generator.rb",
+     "lib/pivotal_doc/generators/base.rb",
+     "lib/pivotal_doc/generators/html.rb",
+     "lib/pivotal_doc/generators/text.rb",
+     "lib/pivotal_doc/release.rb",
+     "pivotal_doc.gemspec",
+     "spec/fixtures/configs.yml",
+     "spec/fixtures/iterations.yml",
+     "spec/fixtures/projects.yml",
+     "spec/fixtures/stories.yml",
+     "spec/lib/configuration_spec.rb",
+     "spec/lib/generator_spec.rb",
+     "spec/lib/generators/base_spec.rb",
+     "spec/lib/generators/html_spec.rb",
+     "spec/lib/generators/text_spec.rb",
+     "spec/lib/release_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/support/mocks_helper.rb",
+     "spec/support/pt_api_helpers.rb",
+     "templates/fancy.haml",
+     "templates/html_gen.haml",
+     "templates/text_gen.txt"
+  ]
+  s.homepage = %q{http://github.com/timo3377/pivotal_doc}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A release documentation generator for pivotaltracker.com}
+  s.test_files = [
+    "spec/lib/configuration_spec.rb",
+     "spec/lib/generator_spec.rb",
+     "spec/lib/generators/base_spec.rb",
+     "spec/lib/generators/html_spec.rb",
+     "spec/lib/generators/text_spec.rb",
+     "spec/lib/release_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/support/mocks_helper.rb",
+     "spec/support/pt_api_helpers.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<pivotal-tracker>, [">= 0.2.1"])
+      s.add_runtime_dependency(%q<haml>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+    else
+      s.add_dependency(%q<pivotal-tracker>, [">= 0.2.1"])
+      s.add_dependency(%q<haml>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<pivotal-tracker>, [">= 0.2.1"])
+    s.add_dependency(%q<haml>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+  end
+end
+

data/spec/fixtures/configs.yml

@@ -0,0 +1,11 @@
+username: humpie
+password: dome
+token: some_funky_guid
+projects: 
+  github:
+   id: 1
+   members: 
+     - [
+         'hot.box@superhighme.com', 
+         'hammer.time@rockyajaw.com'
+       ]     

data/spec/fixtures/iterations.yml

@@ -0,0 +1,4 @@
+- finish: 2010-08-31T07:00:00+00:00
+  id: 1
+  number: 1
+  start: 2010-08-10T07:00:00+00:00

data/spec/fixtures/projects.yml

@@ -0,0 +1,11 @@
+- account: Awesome Guys
+  current_velocity: 3
+  id: 42411
+  initial_velocity: 4
+  iteration_length: 3
+  last_activity_at: 2010-09-16T19:41:29+00:00
+  name: My Hotness
+  point_scale: "0,1,2,3"
+  use_https: false
+  velocity_scheme: Average of 3 iterations
+  week_start_day: Tuesday

data/spec/fixtures/stories.yml

@@ -0,0 +1,87 @@
+- accepted_at: 2010-08-30T16:14:23+00:00
+  attachments: []
+  created_at: 2010-08-05T18:09:40+00:00
+  current_state: Delivered
+  description: Deploy core component of app to staging.
+  estimate: 2
+  id: 1
+  integration_id: 
+  jira_id: 
+  jira_url: 
+  labels: 
+  name: Create staging env for app
+  other_id: 
+  owned_by: Tim Linquist
+  project_id: 42411
+  requested_by: Tim Linquist
+  story_type: feature
+  url: http://www.pivotaltracker.com/story/show/1,
+
+- created_at: 2010-08-06T19:46:38+00:00
+  current_state: accepted
+  description: 
+  estimate: 1
+  id: 2
+  integration_id: 
+  jira_id: 
+  jira_url: 
+  labels: 
+  name: Eliminate Bots from app
+  other_id: 
+  owned_by: Tim Linquist
+  project_id: 42411
+  requested_by: Tim Linquist
+  story_type: feature
+  url: http://www.pivotaltracker.com/story/show/2
+
+- created_at: 2010-08-06T19:46:38+00:00
+  current_state: accepted
+  description: MongoDB server
+  estimate: 2
+  id: 3
+  integration_id: 
+  jira_id: 
+  jira_url: 
+  labels: 
+  name: Mongo Master host
+  other_id: 
+  owned_by: Tim Linquist
+  project_id: 42411
+  requested_by: Tim Linquist
+  story_type: chore
+  url: http://www.pivotaltracker.com/story/show/3
+
+- created_at: 2010-08-06T19:46:38+00:00
+  current_state: accepted
+  description: The app isn't working
+  estimate: 2
+  id: 4
+  integration_id: 
+  jira_id: 
+  jira_url: 
+  labels: 
+  name: The app needs to work better than it does
+  other_id: 
+  owned_by: Tim Linquist
+  project_id: 42411
+  requested_by: Tim Linquist
+  story_type: bug
+  url: http://www.pivotaltracker.com/story/show/4
+
+- created_at: 2010-08-06T19:46:38+00:00
+  current_state: Not Yet Started
+  description:
+  estimate: 
+  id: 5
+  integration_id: 
+  jira_id: 
+  jira_url: 
+  labels: 
+  name: Grateful Dead Sprint
+  other_id: 
+  owned_by: Project Owner
+  project_id: 42411
+  requested_by: Product Manager
+  story_type: release
+  url: http://www.pivotaltracker.com/story/show/5
+    

data/spec/lib/configuration_spec.rb

@@ -0,0 +1,88 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe PivotalDoc::Configuration do
+  before(:each) do
+    @connection= PivotalDoc::Connection.new('A18das1', 'radical', 'dude')
+    @config= PivotalDoc::Configuration.new(File.join(File.dirname(__FILE__), '/../fixtures/', 'configs.yml'))
+  end
+
+  it "should load the settings from the file" do
+    @config.settings.should be_an_instance_of(Hash)
+  end
+  
+  it "should load the settings from the options" do
+    settings= {:test=>'parameter'}
+    config= PivotalDoc::Configuration.new(settings)
+    config.settings.should eql(settings)
+  end
+
+  describe "Authenticating" do
+    before(:each) do
+      @config.instance_variable_set(:@connection, @connection)
+    end
+    
+    after(:each) do
+      @config.instance_variable_set(:@authenticated, false)
+    end
+    
+    it "should set the token if it's configured" do
+      PT::Client.should_receive(:token=).with(@connection.token)
+      @config.authenticate!            
+    end
+    
+    it "should set the token via the username & password if the token isn't configured" do
+      @connection.token= nil
+      PT::Client.should_receive(:token).with(@connection.username, @connection.password)
+      @config.authenticate!      
+    end
+    
+    it "should not set the token again if the client is already authenticated" do
+      PT::Client.should_receive(:token=).exactly(:once)
+      @config.authenticate!
+      @config.authenticate!
+    end
+  end
+
+  describe "A Project" do
+    before(:each) do
+      @projects= @config.projects
+      @project= @projects.fetch(@projects.keys.first)
+    end
+    
+    it "should know all of the projects" do
+      @projects.should_not be_empty
+    end
+    
+    it "should know the members" do
+      @project['members'].should be_an_instance_of(Array)
+    end
+    
+    it "should know its id" do
+      @project['id'].should be_an_instance_of(Fixnum)
+    end
+  end
+  
+  describe "Connection" do
+    after(:each) do
+      @config.instance_variable_set(:@connection, nil)
+    end
+    
+    [:token, :username, :password].each do |property|
+      connection= PivotalDoc::Connection.new
+      it "should have the #{property} property" do
+        connection.should respond_to(property)
+      end
+    end
+
+    it "should not redefine the connection" do
+      PivotalDoc::Connection.should_receive(:new).exactly(:once).and_return(@connection)
+      @config.send(:connection)
+    end
+    
+    it "should default to the config.yml settings" do
+      %w(token username password).each do |_attr|
+        @config.send(:connection).send(_attr.to_sym).should eql(@config.settings[_attr])  
+      end
+    end
+  end
+end

data/spec/lib/generator_spec.rb

@@ -0,0 +1,57 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe PivotalDoc::Generator do
+  before(:each) do
+    @config= PivotalDoc::Configuration.new(File.join(File.dirname(__FILE__), '/../fixtures/', 'configs.yml'))
+    PivotalDoc::Configuration.stub!(:new).and_return(@config)
+    PivotalDoc::Generator.generators.values.each do |g| 
+      generator= mock(g.to_s)
+      g.stub!(:new).and_return(generator)
+      generator.stub!(:render_doc)
+    end
+  end
+  
+  describe "Configuring" do
+    before(:each) do
+      PivotalDoc::Generator.stub!(:collect_releases!)
+      PivotalDoc::Generator.releases= []
+    end
+
+    it "should create a config object from the settings" do
+      settings= {}
+      @config.stub!(:authenticate!)
+      PivotalDoc::Configuration.should_receive(:new).with(settings).and_return(@config)
+      PivotalDoc::Generator.generate(:html, settings)
+      PivotalDoc::Generator.config.should eql(@config)
+    end
+
+    it "should authenticate against pivotal before generating the release docs" do
+      @config.should_receive(:authenticate!)
+      PivotalDoc::Generator.generate(:html)
+    end
+  end
+
+  describe "generation" do
+    before(:each) do
+      @config.stub!(:authenticate!).and_return(true)
+      @release= mocks_helper(:release)
+      PT::Project.stub!(:find).and_return(@release.project)
+      PivotalDoc::Release.stub!(:new).and_return(@release)
+    end
+
+    describe "Formattting" do
+      before(:each) do
+        @options={:my_custom_option=>'my custom value'}
+        @html_gen= PivotalDoc::Generators::HTML.new({})
+        @html_gen.stub!(:render_doc)
+      end
+      it "should render the release with the specified format and custom settings" do
+        PivotalDoc::Generators::HTML.should_receive(:new).with(@release, @config.settings).and_return(@html_gen)
+        PivotalDoc::Generator.generate(:html)
+      end
+      it "should raise an error if the specified format isn't supported" do
+        lambda{ PivotalDoc::Generator.generate(:unsupported) }.should raise_error(PivotalDoc::FormatNotSupported)        
+      end
+    end
+  end
+end

data/spec/lib/generators/base_spec.rb

@@ -0,0 +1,64 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe PivotalDoc::Generators::Base do
+  before(:each) do
+    @release= mocks_helper(:release)
+    @base= PivotalDoc::Generators::Base.new(@release)
+  end
+  it "should raise an exception if the template doesn't exist" do
+    @base.stub!(:template_name).and_return('non-existent.txt')
+    lambda{@base.template}.should raise_error(PivotalDoc::TemplateNonExistent)
+  end
+
+  describe "Rendering the doc" do
+    before(:each) do
+      @base.stub!(:template).and_return('index.txt')
+    end
+
+    after(:each) do
+      File.delete(@base.output_file) if File.exists?(@base.output_file)
+    end
+
+    describe "options" do
+      it "should be a fully qualified file" do
+        base= PivotalDoc::Generators::Base.new(@release, {:output_file=>'my_file'})
+        f= File.open(base.output_file, 'w')
+        f.should be_an_instance_of(File)
+        File.delete(f.path)
+      end
+
+      it "should use the output_file if present" do
+        base= PivotalDoc::Generators::Base.new(@release, {'output_file'=>'my_file'})
+        base.output_file.should =~ /\/my_file/
+      end
+
+      it "should default the output_file to the release's name (unique filename for multiple projects)" do
+        base= PivotalDoc::Generators::Base.new(@release)
+        base.output_file.should =~ /\/#{@release.name}/
+      end
+
+      it "should use the output_path if present" do
+        base= PivotalDoc::Generators::Base.new(@release, {'output_path'=>'my_path'})
+        base.output_path.should =~ /^my_path/
+      end
+
+      it "should default the output_path to the relative directory" do
+        base= PivotalDoc::Generators::Base.new(@release)
+        base.output_path.should =~ /^#{base.absolute_path}/
+      end
+    end
+
+    it "should open the output file and write the output" do
+      output= 'My custom output'
+      @base.render_doc(output)
+      File.read(@base.output_file).should eql(output)
+    end
+
+    it "should handle any exceptions and output STDOUT" do
+      File.stub!(:open).and_raise(Exception.new('A MAJOR CATASTROPHE'))
+      $stdout.should_receive(:print).with('A MAJOR CATASTROPHE')
+      $stdout.should_receive(:flush)
+      @base.render_doc
+    end
+  end
+end