webby 0.1.0 → 0.2.0

data/lib/webby/pages_db.rb

@@ -1,4 +1,4 @@
-# $Id: pages_db.rb 6 2007-08-22 22:25:53Z tim_pease $
+# $Id: pages_db.rb 18 2007-08-28 15:48:17Z tim_pease $
 
 module Webby
 
@@ -7,20 +7,32 @@ module Webby
 class PagesDB
   include Enumerable
 
+  # call-seq:
+  #    PagesDB.new
+  #
   def initialize
     @db = Hash.new {|h,k| h[k] = []}
   end
 
+  # call-seq:
+  #    add( resource )
+  #
   def add( page )
     @db[page.dir] << page
     self
   end
   alias :<< :add
 
+  # call-seq:
+  #    clear
+  #
   def clear
     @db.clear
   end
 
+  # call-seq:
+  #    each {|resource| block}
+  #
   def each( &b )
     keys = @db.keys.sort
     keys.each do |k|
@@ -28,6 +40,9 @@ class PagesDB
     end
   end
 
+  # call-seq:
+  #    find_by_name( name )
+  #
   def find_by_name( name )
     self.find {|page| page.filename == name}
   end
@@ -37,6 +52,7 @@ class PagesDB
   #
   # Options include:
   #    :sorty_by => 'attribute'
+  #    :reverse  => true
   #
   def siblings( page, opts = {} )
     ary = @db[page.dir].dup
@@ -49,6 +65,13 @@ class PagesDB
     ary
   end
 
+  # call-seq:
+  #    children( page, opts = {} )    => array
+  #
+  # Options include:
+  #    :sorty_by => 'attribute'
+  #    :reverse  => true
+  #
   def children( page, opts = {} )
     rgxp = Regexp.new "\\A#{page.dir}/[^/]+"
 

data/lib/webby/renderer.rb

@@ -1,4 +1,4 @@
-# $Id: renderer.rb 2 2007-08-20 17:55:30Z tim_pease $
+# $Id: renderer.rb 19 2007-08-28 22:48:24Z tim_pease $
 
 require 'erb'
 
@@ -7,7 +7,17 @@ try_require 'redcloth'
 
 module Webby
 
+# The Webby::Renderer is used to _filter_ and _layout_ the text found in the
+# resource page files in the content directory.
 #
+# A page is filtered based on the settings of the 'filter' option in the
+# page's meta-data information. For example, if 'textile' is specified as
+# a filter, then the page will be run through the RedCloth markup filer.
+# More than one filter can be used on a page; they will be run in the
+# order specified in the meta-data.
+#
+# A page is rendered into a layout specified by the 'layout' option in the
+# page's meta-data information.
 #
 class Renderer
   include ERB::Util
@@ -15,6 +25,10 @@ class Renderer
   # call-seq:
   #    Renderer.new( page )
   #
+  # Create a new renderer for the given _page_. The renderer will apply the
+  # desired filters to the _page_ (from the page's meta-data) and then
+  # render the filtered page into the desired layout.
+  #
   def initialize( page )
     unless page.is_page?
       raise ArgumentError,
@@ -27,7 +41,12 @@ class Renderer
   end
 
   # call-seq:
-  #    layout_page
+  #    layout_page    => string
+  #
+  # Apply the desired filters to the page and then render the filtered page
+  # into the desired layout. The filters to apply to the page are determined
+  # from the page's meta-data. The layout to use is also determined from the
+  # page's meta-data.
   #
   def layout_page
     layouts = Resource.layouts
@@ -51,7 +70,10 @@ class Renderer
   end
 
   # call-seq:
-  #    render_page
+  #    render_page    => string
+  #
+  # Apply the desired filters to the page. The filters to apply are
+  # determined from the page's meta-data.
   #
   def render_page
     str = ::Webby::File.read(@page.path)

data/lib/webby/resource.rb

@@ -1,30 +1,65 @@
-# $Id: resource.rb 5 2007-08-22 04:25:49Z tim_pease $
+# $Id: resource.rb 17 2007-08-28 04:11:00Z tim_pease $
 
 module Webby
 
+# A Webby::Resource is any file that can be found in the content directory
+# or in the layout directory. This class contains information about the
+# resources available to Webby. This information includes the resource
+# type (static, page, layout), if the resource is dirty (it needs to be
+# rendered), the output location of the rendered resource, etc.
 #
+# A resource is a "layout" if the resource is found in the layout
+# directory. Static and page resources are found in the content directory.
+#
+# A resource is considered static only if it *does not* contain a YAML
+# meta-data header at the top of the file. These resources will be copied
+# as-is from the content directory to the output directory.
+#
+# If a resouce does have meta-data, then it will be processed (i.e.
+# rendered/filtered) by Webby, and the rendered results will be written to
+# the output directory.
 #
 class Resource
 
   class << self
+    # Returns the pages hash object.
     def pages
       @pages ||= PagesDB.new
     end
 
+    # Returns the layouts hash object.
     def layouts
       @layouts ||= PagesDB.new
     end
 
+    # Clear the contents of the +layouts+ and the +pages+ hash objects.
     def clear
       self.pages.clear
       self.layouts.clear
     end
   end  # class << self
 
+  # The full path to the resource file
+  attr_reader :path
+
+  # The directory of the resource excluding the content directory
+  attr_reader :dir
+
+  # The resource filename excluding path and extension
+  attr_reader :filename
+
+  # Extesion of the resource file
+  attr_reader :ext
+
+  # Resource file modification time
+  attr_reader :mtime
+
   # call-seq:
-  #    Resource.new( filename, defaults = {} )    => page
+  #    Resource.new( filename )    => resource
   #
-  def initialize( fn, defaults = {} )
+  # Creates a new resource object given the _filename_.
+  #
+  def initialize( fn )
     @path     = fn.sub(%r/\A(?:\.\/|\/)/o, '').freeze
     @dir      = ::File.dirname(@path).sub(%r/\A[^\/]+\/?/o, '')
     @filename = ::File.basename(@path).sub(%r/\.\w+\z/o, '')
@@ -36,7 +71,9 @@ class Resource
     # deal with the meta-data
     @mdata = ::Webby::File.meta_data(@path)
     @have_mdata = !@mdata.nil?
-    @mdata = @have_mdata ? defaults.merge(@mdata) : {}
+
+    @mdata ||= {}
+    @mdata = ::Webby.page_defaults.merge(@mdata) if is_page?
     @mdata.sanitize!
 
     self.class.pages << self if is_page? or is_static?
@@ -46,6 +83,9 @@ class Resource
   # call-seq:
   #    equal?( other )    => true or false
   #
+  # Returns +true+ if the path of this resource is equivalent to the path of
+  # the _other_ resource. Returns +false+ if this is not the case.
+  #
   def equal?( other )
     return false unless self.class == other.class
     @path == other.path
@@ -56,17 +96,25 @@ class Resource
   # call-seq:
   #    resource <=> other    => -1, 0, +1, or nil
   #
+  # Resource comparison operates on the full path of the resource objects
+  # and uses the standard String comparison operator. Returns +nil+ if
+  # _other_ is not a Resource instance.
+  #
   def <=>( other )
     return unless self.class == other.class
     @path <=> other.path
   end
 
-
-  attr_reader :path, :dir, :filename, :mtime, :ext
-
   # call-seq:
   #    extension    => string
   #
+  # Returns the extension that will be appended to the output destination
+  # filename. The extension is determined by looking at the following:
+  #
+  # * this resource's meta-data for an 'extension' property
+  # * the meta-data of this resource's layout for an 'extension' propery
+  # * the extension of this resource file
+  #
   def extension
     return @mdata['extension'] if @mdata.has_key? 'extension'
 
@@ -79,19 +127,39 @@ class Resource
     @ext
   end
 
+  # call-seq:
+  #    destination    => string
+  #
+  # Returns the path in the output directory where the results of rendering
+  # this resource should be stored. This path is used to determine if the
+  # resource is dirty and in need of rendering.
+  #
+  # The destination for any resource can be overridden by explicitly setting
+  # the 'destination' propery in the resource's meta-data.
+  #
   def destination
-    return @destination if defined? @destination
-    return @destination = ::Webby.config['output_dir'] if is_layout?
+    return @dest if defined? @dest
+    return @dest = ::Webby.config['output_dir'] if is_layout?
 
-    @destination = File.join(::Webby.config['output_dir'], dir, filename)
-    @destination << '.'
-    @destination << extension
-    @destination
+    @dest = if @mdata.has_key? 'destination' then @mdata['destination']
+            else File.join(dir, filename) end
+
+    @dest = File.join(::Webby.config['output_dir'], @dest)
+    @dest << '.'
+    @dest << extension
+    @dest
   end
 
   # call-seq:
   #    render   => string
   #
+  # Creates a new Webby::Renderer instance and uses that instance to render
+  # the resource contents using the configured filter(s). The filter(s) to
+  # use is defined in the resource's meta-data as the 'filter' key.
+  #
+  # Note, this only renders this resource. The returned string does not
+  # include any layout rendering.
+  #
   def render
     raise Error, "page '#@path' is in a rendering loop" if @rendering
 
@@ -164,6 +232,14 @@ class Resource
     @mdata['dirty'] = false
   end
 
+  # call-seq:
+  #    method_missing( symbol [, *args, &block] )    => result
+  #
+  # Invoked by Ruby when a message is sent to the resource that it cannot
+  # handle. The default behavior is to convert _symbol_ to a string and
+  # search for that string in the resource's meta-data. If found, the
+  # meta-data item is returned; otherwise, +nil+ is returned.
+  #
   def method_missing( name, *a, &b )
     @mdata[name.to_s]
   end

data/lib/webby/webby_task.rb

@@ -1,4 +1,4 @@
-# $Id: webby_task.rb 7 2007-08-22 22:31:08Z tim_pease $
+# $Id: webby_task.rb 15 2007-08-25 19:05:39Z tim_pease $
 
 begin
   require 'rake'
@@ -33,27 +33,22 @@ module Rake
 #
 class WebbyTask < TaskLib
 
-  # Location of the generated website
-  attr_accessor :output_dir
-
-  # Location of the webiste source material
-  attr_accessor :content_dir
-
-  # Location of the layout files for generated pages
-  attr_accessor :layout_dir
-
-  # Location of the page templates
-  attr_accessor :template_dir
-
-  # Array of patterns used to exclude files
-  attr_accessor :exclude
+  # Define a setter and getter for each key in the Webby configuration hash
+  ::Webby.config.keys.each do |key|
+    self.class_eval do
+      define_method(key) {::Webby.config[key]}
+      define_method(key+'=') {|val| ::Webby.config[key] = val}
+    end
+  end
 
-  # Global page attributes (default is {})
-  attr_reader :page_defaults
+  # Global page attributes
+  def page_defaults
+    ::Webby.page_defaults
+  end
 
   # Merge the given _hash_ with the page defaults hash
   def page_defaults=( hash )
-    @page_defaults.merge! hash
+    ::Webby.page_defaults.merge! hash
   end
 
   # call-seq:
@@ -63,34 +58,17 @@ class WebbyTask < TaskLib
   # pages in the website.
   #
   def initialize
-    @output_dir = 'output'
-    @content_dir = 'content'
-    @layout_dir = 'layouts'
-    @template_dir = 'templates'
-    @exclude = %w(tmp$ bak$ ~$ CVS \.svn)
-    @page_defaults = {
-      'extension' => 'html',
-      'layout'    => 'default'
-    }
-
     yield self if block_given?
 
-    ::Webby.config.merge!({
-      'output_dir' => @output_dir,
-      'content_dir' => @content_dir,
-      'layout_dir' => @layout_dir,
-      'template_dir' => @template_dir,
-      'exclude' => @exclude
-    })
-    ::Webby.page_defaults.merge! @page_defaults
+    # load any user defined libraries
+    glob = File.join(FileUtils.pwd, 'lib', '**', '*.rb')
+    Dir.glob(glob).sort.each {|fn| require fn}
 
+    # create the Webby rake tasks
     define_build_tasks
     namespace(:create) {define_create_tasks}
   end
 
-
-  private
-
   # Defines the :build and :rebuild tasks
   #
   def define_build_tasks
@@ -114,7 +92,7 @@ class WebbyTask < TaskLib
   # task for creating a new page based on that template.
   #
   def define_create_tasks
-    FileList["#{@template_dir}/*"].each do |template|
+    FileList["#{template_dir}/*"].each do |template|
       name = template.pathmap '%n'
 
       desc "create a new #{name} page"
@@ -122,7 +100,7 @@ class WebbyTask < TaskLib
         raise "Usage:  rake #{t.name} path" unless ARGV.length == 2
 
         page = t.application.top_level_tasks.pop
-        page = File.join(@content_dir, page)
+        page = File.join(content_dir, page)
         page << '.txt' if File.extname(page).empty?
 
         ::Webby::Builder.create page, :from => template

data/tasks/doc.rake

@@ -1,7 +1,6 @@
-# $Id$
+# $Id: doc.rake 11 2007-08-23 15:45:16Z tim_pease $
 
 require 'rake/rdoctask'
-require 'rake/contrib/sshpublisher'
 
 namespace :doc do
 
@@ -9,7 +8,7 @@ namespace :doc do
   Rake::RDocTask.new do |rd|
     rd.main = PROJ.rdoc_main
     rd.options << '-d' if !WIN32 and `which dot` =~ %r/\/dot/
-    rd.rdoc_dir = 'doc'
+    rd.rdoc_dir = PROJ.rdoc_dir
 
     incl = Regexp.new(PROJ.rdoc_include.join('|'))
     excl = Regexp.new(PROJ.rdoc_exclude.join('|'))
@@ -37,22 +36,6 @@ namespace :doc do
     rm_r 'ri' rescue nil
   end
 
-  if PROJ.rubyforge_name && HAVE_RUBYFORGE
-    desc "Publish RDoc to RubyForge"
-    task :release => %w(doc:clobber_rdoc doc:rdoc) do
-      config = YAML.load(
-          File.read(File.expand_path('~/.rubyforge/user-config.yml'))
-      )
-
-      host = "#{config['username']}@rubyforge.org"
-      remote_dir = "/var/www/gforge-projects/#{rubyforge_name}/"
-      remote_dir << PROJ.rdoc_remote_dir || PROJ.name
-      local_dir = 'doc'
-
-      Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
-    end
-  end
-
 end  # namespace :doc
 
 task :clobber => %w(doc:clobber_rdoc doc:clobber_ri)

data/tasks/gem.rake

@@ -1,11 +1,10 @@
-# $Id$
+# $Id: gem.rake 11 2007-08-23 15:45:16Z tim_pease $
 
 require 'rake/gempackagetask'
-require 'rubyforge' if PROJ.rubyforge_name && HAVE_RUBYFORGE
 
 namespace :gem do
 
-  spec = Gem::Specification.new do |s|
+  PROJ.spec = Gem::Specification.new do |s|
     s.name = PROJ.name
     s.version = PROJ.version
     s.summary = PROJ.summary
@@ -19,9 +18,6 @@ namespace :gem do
     PROJ.dependencies.each do |dep|
       s.add_dependency(*dep)
     end
-    if PROJ.rubyforge_name && HAVE_RUBYFORGE
-      s.add_dependency('rubyforge', ">= #{::RubyForge::VERSION}")
-    end
     s.add_dependency('rake', ">= #{RAKEVERSION}")
 
     s.files = PROJ.files
@@ -32,8 +28,15 @@ namespace :gem do
     dirs = Dir['{lib,ext}']
     s.require_paths = dirs unless dirs.empty?
 
-    rdoc_files = PROJ.files.grep %r/txt$/
-    rdoc_files.delete 'Manifest.txt'
+    incl = Regexp.new(PROJ.rdoc_include.join('|'))
+    excl = PROJ.rdoc_exclude.dup.concat %w[\.rb$ ^(\.\/|\/)?ext]
+    excl = Regexp.new(excl.join('|'))
+    rdoc_files = PROJ.files.find_all do |fn|
+                   case fn
+                   when excl: false
+                   when incl: true
+                   else false end
+                 end
     s.rdoc_options = PROJ.rdoc_opts + ['--main', PROJ.rdoc_main]
     s.extra_rdoc_files = rdoc_files
     s.has_rdoc = true
@@ -57,17 +60,17 @@ namespace :gem do
 
   desc 'Show information about the gem'
   task :debug do
-    puts spec.to_ruby
+    puts PROJ.spec.to_ruby
   end
 
-  Rake::GemPackageTask.new(spec) do |pkg|
+  Rake::GemPackageTask.new(PROJ.spec) do |pkg|
     pkg.need_tar = PROJ.need_tar
     pkg.need_zip = PROJ.need_zip
   end
 
   desc 'Install the gem'
   task :install => [:clobber, :package] do
-    sh "#{SUDO} #{GEM} install pkg/#{spec.file_name}"
+    sh "#{SUDO} #{GEM} install pkg/#{PROJ.spec.file_name}"
   end
 
   desc 'Uninstall the gem'
@@ -75,36 +78,6 @@ namespace :gem do
     sh "#{SUDO} #{GEM} uninstall -v '#{PROJ.version}' #{PROJ.name}"
   end
 
-  if PROJ.rubyforge_name && HAVE_RUBYFORGE
-    desc 'Package and upload to RubyForge'
-    task :release => [:clobber, :package] do |t|
-      v = ENV['VERSION'] or abort 'Must supply VERSION=x.y.z'
-      abort "Versions don't match #{v} vs #{PROJ.version}" if v != PROJ.version
-      pkg = "pkg/#{spec.full_name}"
-
-      if $DEBUG then
-        puts "release_id = rf.add_release #{PROJ.rubyforge_name.inspect}, #{PROJ.name.inspect}, #{PROJ.version.inspect}, \"#{pkg}.tgz\""
-        puts "rf.add_file #{PROJ.rubyforge_name.inspect}, #{PROJ.name.inspect}, release_id, \"#{pkg}.gem\""
-      end
-
-      rf = RubyForge.new
-      puts 'Logging in'
-      rf.login
-
-      c = rf.userconfig
-      c['release_notes'] = PROJ.description if PROJ.description
-      c['release_changes'] = PROJ.changes if PROJ.changes
-      c['preformatted'] = true
-
-      files = [(PROJ.need_tar ? "#{pkg}.tgz" : nil),
-               (PROJ.need_zip ? "#{pkg}.zip" : nil),
-               "#{pkg}.gem"].compact
-
-      puts "Releasing #{PROJ.name} v. #{PROJ.version}"
-      rf.add_release PROJ.rubyforge_name, PROJ.name, PROJ.version, *files
-    end
-  end
-
 end  # namespace :gem
 
 task :clobber => 'gem:clobber_package'