Fingertips-jewelry_portfolio 0.2.3 → 0.3.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Fingertips, Eloy Duran <eloy.de.enige@gmail.com>, Thijs van der Vossen <thijs@fngtps.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,124 +1,106 @@
-= JewelryPortfolio
+= Jewelry Portfolio
 
-Surely also lazy developers like to showcase their jewelry portfolio on their
-GitHub pages.
+<em>Surely also lazy developers like to showcase their jewelry portfolio on
+their GitHub pages.</em>
 
-Imagine writing an erb template once and use <tt>rake release</tt> to release
-your gem with Jeweler as usual, but in addition re-generate and push the
-index.html for your GitHub pages. If that sounds good to you, you're in luck.
-Because that's exactly what this add-on for
-Jeweler[http://github.com/technicalpickles/jeweler/tree/master] does.
+Imagine writing a template once and use <tt>rake portfolio:release</tt>
+to generate and push an index.html and feed.xml file to your GitHub pages
+repository containing all the repositories you want to. If that sounds good to
+you, you're in luck. Because that's exactly what this gem does.
 
-== Usage
+Note that if you have a <tt>rake release</tt> task, then the <tt>rake
+portfolio:release</tt> task is automatically invoked after the original
+finishes. An example of a Gem which provides such a task is
+Jeweler[http://github.com/technicalpickles/jeweler/tree/master].
 
-=== GitHub pages repository
+== Installation
 
-First things first; create a GitHub pages repository if you haven't done so
-already. See http://github.com/guides/pages for more info.
+Run the following if you haven't done so before:
 
-Then create the following files, and content, in the master branch of your
-pages repository (<em>for a more elaborate example see:
-http://github.com/alloy/alloy.github.com/tree/master</em>):
+  gem sources -a http://gems.github.com
 
-* <b>Rakefile:</b>
+Install the gem:
 
-    require 'jewelry_portfolio/tasks'
-    JewelryPortfolio::Tasks.new do |t|
-      t.account     = 'Fingertips'
-      t.name        = 'passengerpane'
-      t.version     = '1.2.0'
-      t.summary     = 'A short summary about the project.'
-      t.description = 'A longer description about the project.'
-    end
+  sudo gem install Fingertips-jewelry_portfolio
 
-  The +account+ is only necessary when you haven't configured github.user in
-  the local or global git config. (For more info see:
-  http://github.com/guides/local-github-config.) Or if you want to override the
-  +account+ that was retrieved from the git config.
-  
-  The other attributes are only necessary when there's no gemspec file in the
-  work directory.
+== GitHub pages repository
 
-* <b>template.html.erb:</b>
-
-  This is the main template file which will be used to generate the index.html
-  file. All repositories and their gem specifications are available as the
-  local variable <tt>repos</tt>. See JewelryPortfolio::Template and
-  JewelryPortfolio::Repo for more information.</em>.
+First things first; create a GitHub pages repository if you haven't done so
+already. See http://github.com/guides/pages for more info.
 
-    <html>
-      <head>
-        <title>Alloy&rsquo;s jewelry</title>
-      </head>
+Then you can merge the code from our Fingertips pages repository as an example
+on how to create your index.html and feed.xml files:
 
-      <p>This is an overview of the available gems by Eloy Duran, aka `alloy'.</p>
+  $ git remote add fingertips git://github.com/Fingertips/fingertips.github.com.git
+  $ git fetch fingertips
+  $ git merge fingertips/master
 
-      <body>
-        <% repos.each do |repo| %>
-          <%= repo_partial(repo) %>
-        <% end %>
-      </body>
-    </html>
+Update the Rakefile to use the correct account, or none if it can be inflected
+from the <tt>github.user</tt> value of your local or global git config. For
+more info see: http://github.com/guides/local-github-config.
 
-* <b>repo.html.erb:</b>
+For more information on the template renderers see:
+JewelryPortfolio::Template::HTML and JewelryPortfolio::Template::Feed.
 
-  This file is completely optional; it's just a showcase of using a repo
-  partial.
+If you want to add repos by hand then take a look at <tt>repos.yml</tt>. When
+done remove it so you have a fresh state:
 
-    <div>
-      <h1><a href="<%= repo.url %>"><%= spec.name %> <%= spec.version %></a></h1>
-      <p><%= spec.description %></p>
-      <p>Install: <code>$ <%= repo.gem_install_command %></code></p>
-      <p>Clone: <code>$ git clone <%= repo.clone_url %></code></p>
-    </div>
+  $ git rm repos.yml
+  $ git commit -a -m "Reset repos.yml state"
 
-Now you can generate the index.html file with:
+Now you can generate the index.html and feed.xml files with:
 
   $ rake portfolio:generate
 
-Since you haven't added any projects yet the generated index will be pretty
-dull. But for now just release this version:
+And generate, commit and push to the remote branch with:
 
   $ rake portfolio:release
 
-Whenever you update the template you can use these tasks to preview and/or
+Whenever you update the templates you can use these tasks to preview and/or
 release it.
 
-=== Add super-cow powers to your project's Rakefile
+== Using in a non-Gem project
 
-Update the Rakefile of the project that you would like to include in your
-jewelry portfolio like so:
+In your Rakefile instantiate a JewelryPortfolio::Tasks object, and give it a
+block with details about your project:
 
   begin
-    require 'jeweler'
-    Jeweler::Tasks.new do |s|
-      # ...
-    end
-    
-    # Add the following to your Rakefile to use JewelryPortfolio
-    begin
-      require 'jewelry_portfolio/tasks'
-      JewelryPortfolio::Tasks.new do |t|
-        # Only specify the account if it's different from `github.user' in the git config.
-        t.account = 'Fingertips'
-      end
-    rescue LoadError
-      puts "JewelryPortfolio not available. Install it with: sudo gem install Fingertips-jewelry_portfolio -s http://gems.github.com"
+    require 'jewelry_portfolio/tasks'
+    JewelryPortfolio::Tasks.new do |p|
+      # p.account = 'Fingertips'
+      p.name = 'jewelry_portfolio'
+      p.version = '1.0.0'
+      p.summary = 'Short summary about the project.'
+      p.description = 'Long description about the project.'
     end
-    
   rescue LoadError
-    puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+    puts "JewelryPortfolio not available. Install it with: sudo gem install Fingertips-jewelry_portfolio -s http://gems.github.com"
   end
 
-From now on, whenever you use the +release+ rake task, the GitHub pages
-index.html will be re-generated and pushed to GitHub after releasing the gem.
+In this example +p+ is a JewelryPortfolio::Repo instance. See its reference for
+details about the available options.
+
+Note that the +account+ value should _only_ be set if it can't be inflected
+from the <tt>github.user</tt> value of your local or global git config. For
+more info see: http://github.com/guides/local-github-config.
+
+For generating and releasing the portfolio, use the aforementioned
+<tt>portfolio:generate</tt> and <tt>portfolio:release</tt> rake tasks.
+
+== Using in a Gem project
+
+If your project contains a gemspec file, then not much configuration is needed
+because all values will be copied from it. Simply add the following to your
+Rakefile:
+
+  require 'jewelry_portfolio/tasks'
+  JewelryPortfolio::Tasks.new
 
-If you just want to re-generate, or release, the jewelry portfolio use the
-aforementioned <tt>portfolio:generate</tt> and <tt>portfolio:release</tt> rake
-tasks.
+You can override the attributes as described in ‘Using in a non-Gem project’.
 
-Note that it isn't necessary to use Jeweler to be able to use JewelryPortfolio.
+For generating and releasing the portfolio, use the aforementioned
+<tt>portfolio:generate</tt> and <tt>portfolio:release</tt> rake tasks.
 
 == COPYRIGHT
 
-Copyright (c) 2009 Fingertips, Eloy Duran. See LICENSE for details.
+Copyright © 2009 Fingertips, Eloy Duran, Thijs van der Vossen. See LICENSE for details.

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
+:minor: 3
+:patch: 0
 :major: 0
-:minor: 2
-:patch: 3

data/lib/jewelry_portfolio.rb

@@ -3,9 +3,7 @@ require 'jewelry_portfolio/repos_index'
 require 'jewelry_portfolio/template'
 
 class JewelryPortfolio
-  class FileMissingError < StandardError; end
-  
-  attr_reader :account, :repo, :index, :template
+  attr_reader :account, :repo, :index, :html_template, :feed_template
   
   # Initializes a JewelryPortfolio instance for the specified +account+.
   #
@@ -17,18 +15,20 @@ class JewelryPortfolio
     raise ArgumentError, "No `account' given." unless account
     raise ArgumentError, "No valid `repo' given." if repo && !repo.valid?
     
-    @account  = account
-    @repo     = repo
-    @index    = ReposIndex.new(@account, (Dir.pwd unless @repo))
-    @template = Template.new(File.join(@index.path, 'template'), @index.repos)
+    @account = account
+    @repo    = repo
+    @index   = ReposIndex.new(@account, (Dir.pwd unless @repo))
+    
+    @html_template = template(Template::HTML, 'index.erb')
+    @feed_template = template(Template::Feed, 'feed.rb')
     
     @index.add(@repo) if @repo
   end
   
   # Renders the index.html file.
   def render!
-    puts "Generating html"
-    File.open(File.join(@index.path, 'index.html'), 'w') { |f| f << @template.render }
+    write_out('HTML', 'index.html', @html_template.render)
+    write_out('feed', 'feed.xml', @feed_template.render)
   end
   
   # Renders the index.html file, then commits and pushes it to the remote.
@@ -40,6 +40,15 @@ class JewelryPortfolio
   
   private
   
+  def template(klass, file)
+    klass.new(File.join(@index.path, file), @account, @index.repos)
+  end
+  
+  def write_out(message, file, data)
+    puts "Generating #{message}"
+    File.open(File.join(@index.path, file), 'w') { |f| f << data }
+  end
+  
   def commit_message
     if @repo
       "Updated github pages for: #{@repo.name}-#{@repo.version}"

data/lib/jewelry_portfolio/repo.rb

@@ -25,13 +25,21 @@ class JewelryPortfolio
     # Not needed when initialized with a Gem::Specification.
     attr_accessor :description
     
+    # The Time at which this Repo was last updated.
+    attr_reader :updated_at
+    
     def initialize(account = nil, spec = nil)
       @account = account
       @gem = !spec.nil?
       
-      %w{ name version summary description }.each do |attr|
-        send("#{attr}=", spec.send(attr).to_s)
-      end if spec
+      if spec
+        @updated_at = Time.utc(spec.date.year, spec.date.month, spec.date.day)
+        %w{ name version summary description }.each do |attr|
+          send("#{attr}=", spec.send(attr).to_s)
+        end
+      end
+      
+      @updated_at = Time.now unless @updated_at
     end
     
     # Returns whether or not there's a Ruby gem for this repo.
@@ -70,6 +78,14 @@ class JewelryPortfolio
       @name.hash
     end
     
+    def <=>(other)
+      if (res = @updated_at <=> other.updated_at) != 0
+        res
+      else
+        @version.split('.') <=> other.version.split('.')
+      end
+    end
+    
     def ==(other)
       other.is_a?(Repo) && hash == other.hash
     end

data/lib/jewelry_portfolio/repos_index.rb

@@ -84,6 +84,7 @@ class JewelryPortfolio
         @pages_repo = Git.open(path)
         unless @custom_work_directory
           puts "Pulling `#{url}'"
+          @pages_repo.checkout('.')
           @pages_repo.checkout('master')
           @pages_repo.fetch('origin')
           @pages_repo.merge('origin/master')

data/lib/jewelry_portfolio/template.rb

@@ -1,69 +1,43 @@
-require 'erb'
+require 'jewelry_portfolio/template/feed'
+require 'jewelry_portfolio/template/html'
 
 class JewelryPortfolio
   # This class is responsible for rendering a template.
   class Template
+    class FileMissingError < StandardError; end
+    class NotImplemented < StandardError; end
+    
     # The full path to the template file.
-    attr_reader :template
+    attr_reader :file
     
     # The directory in which the template resides.
     attr_reader :view_path
     
+    # The account name on GitHub.
+    attr_reader :account
+    
     # The array of JewelryPortfolio::Repo instances.
     attr_reader :repos
     
     # Initialize with the path to the +template+, minus the extensions, and an
     # array of JewelryPortfolio::Repo instances as +repos+.
-    def initialize(template, repos)
-      template   = File.expand_path(template)
-      @view_path = File.dirname(template)
-      @template  = html_template_file(File.basename(template))
+    def initialize(template_file, account, repos)
+      @file = template_file
+      verify_template!
+      
+      @view_path = File.dirname(@file)
+      @account   = account
       @repos     = repos.to_a
     end
     
-    # Renders the template and returns the output.
     def render
-      erb @template, binding
-    end
-    
-    # Renders a partial specified by +partial_name+ minus the extension. You
-    # can optionally specify a hash of +local_variables+ which will be
-    # available while rendering the partial.
-    #
-    # Consider a partial named <tt>foo.html.erb</tt>, in the same directory as
-    # the template, containing the following:
-    #
-    #   Text: <%= text %>
-    #
-    # This partial can now be rendered like this:
-    #
-    #   partial('foo', :text => 'bar') # => "Text: bar"
-    def partial(partial_name, local_variables = {})
-      for (var_name, var_value) in local_variables
-        eval "#{var_name} = var_value"
-      end
-      erb html_template_file(partial_name), binding
-    end
-    
-    # Renders a partial for the specified +repo+. This method looks for a
-    # partial file named <tt>repo.html.erb</tt> in the same directory as the
-    # template.
-    #
-    # See partial for more info.
-    def repo_partial(repo, local_variables = {})
-      partial 'repo', local_variables.merge(:repo => repo)
+      raise NotImplemented, 'Needs to be implemented by the subclass.'
     end
     
     private
     
-    def erb(file, binding)
-      ERB.new(File.read(file)).result(binding)
-    end
-    
-    def html_template_file(name)
-      path = File.join(view_path, "#{name}.html.erb")
-      raise FileMissingError, "Could not find template at path `#{path}'" unless File.exist?(path)
-      path
+    def verify_template!
+      raise FileMissingError, "Could not find template at path `#{@file}'" unless File.exist?(@file)
     end
   end
 end

data/lib/jewelry_portfolio/template/feed.rb

@@ -0,0 +1,123 @@
+require "builder"
+require "rss"
+
+class JewelryPortfolio
+  class Template
+    # This class is responsible for rendering an Atom RSS feed template.
+    #
+    # To override the title or description of the feed in your template:
+    #
+    #   feed.title = 'Code from alloy'
+    #   feed.description = 'The Ruby libraries, from alloy, available as open-source projects'
+    #
+    # To override any of the attributes generated for each repo, override the
+    # methods: id_for_repo, updated_for_repo, title_for_repo, link_for_repo,
+    # summary_for_repo, and description_for_repo:
+    #
+    #   def feed.title_for_repo(repo)
+    #     "#{repo.name.capitalize} (#{repo.version})"
+    #   end
+    class Feed < Template
+      # The title that should be used for the feed.
+      #
+      # This defaults to <tt>"Code from #{@account}"</tt>.
+      attr_accessor :title
+      
+      # The description (+subtitle+) that should be used for the feed.
+      #
+      # This defaults to <tt>"The Ruby libraries, from #{@account}, available
+      # as open-source projects"</tt>.
+      attr_accessor :description
+      
+      def initialize(template_file, account, repos)
+        super
+        @title = "Code from #{@account}"
+        @description = "The Ruby libraries, from #{@account}, available as open-source projects"
+        load_template!
+      end
+      
+      # Loads the template. A local variable named `feed' is made available,
+      # which holds a reference to this JewelryPortfolio::Template::Feed
+      # instance.
+      def load_template!
+        feed = self
+        eval(File.read(@file))
+      end
+      
+      # Returns the repos ordered by +updated_at+ then +version+.
+      #
+      # See JewelryPortfolio::Repo#<=>
+      def repos
+        super.sort
+      end
+      
+      # Returns the +id+ to be used for the feed.
+      def feed_id
+        "http://#{@account.downcase}.github.com/"
+      end
+      
+      # Returns the URL to the feed.
+      def feed_url
+        "http://#{@account}.github.com/feed.xml"
+      end
+      
+      # Returns the +id+ attribute to be used for the repo.
+      def id_for_repo(repo)
+        "#{repo.url}##{repo.version}"
+      end
+      
+      # Returns the +updated+ attribute to be used for the repo.
+      def updated_for_repo(repo)
+        repo.updated_at.iso8601
+      end
+      
+      # Returns the +title+ attribute to be used for the repo.
+      def title_for_repo(repo)
+        "#{repo.name} #{repo.version}"
+      end
+      
+      # Returns the +link+ attribute to be used for the repo.
+      def link_for_repo(repo)
+        repo.url
+      end
+      
+      # Returns the +summary+ attribute to be used for the repo.
+      def summary_for_repo(repo)
+        repo.summary
+      end
+      
+      # Returns the +description+ attribute to be used for the repo.
+      def description_for_repo(repo)
+        repo.description
+      end
+      
+      # Renders the HTML and returns the output.
+      def render(&block)
+        output = ''
+        
+        xml = Builder::XmlMarkup.new(:target => output, :indent => 2)
+        xml.instruct!
+        xml.feed "xmlns" => "http://www.w3.org/2005/Atom" do
+          xml.id      feed_id
+          xml.link    "rel" => "self", "href" => feed_url
+          xml.updated Time.now.iso8601
+          xml.author  { xml.name @account }
+          
+          xml.title    @title
+          xml.subtitle @description
+          
+          repos.each do |repo|
+            xml.entry do
+              xml.id      id_for_repo(repo)
+              xml.updated updated_for_repo(repo)
+              xml.title   title_for_repo(repo)
+              xml.link    :href => link_for_repo(repo)
+              xml.summary summary_for_repo(repo)
+              xml.content description_for_repo(repo)
+            end
+          end
+        end
+      end
+    end
+  end
+end