governor 0.2.0 → 0.2.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ./
   specs:
-    governor (0.1.1)
+    governor (0.2.0)
       rails (~> 3.0.5)
 
 GEM

data/{README.markdown → README.rdoc}

@@ -1,7 +1,6 @@
-Governor
-========
+= Governor
 
-**Governor** (named after Rod Blagojevich) is the pluggable blogging platform
+*Governor* (named after Rod Blagojevich) is the pluggable blogging platform
 for Rails, built for people who want to build their blog into their website,
 not build their website into their blog.
 
@@ -9,17 +8,15 @@ I'm just getting started, but feel free to poke around. I'm sure that when
 this starts getting functional, I'll write some setup documentation here. And
 try the specs, they're fresh!
 
-Dependencies
-------------
+== Dependencies
 
 * ActiveRecord
-* [will_paginate](https://github.com/mislav/will_paginate)
+* will_paginate[https://github.com/mislav/will_paginate]
 
 At some point (at least by v1.0), these dependencies will be removed. Sorry
 about the meantime.
 
-Setting Up
-----------
+== Setting Up
 
 Governor is a gem, so the first thing to do is to add Governor to your
 Gemfile.
@@ -40,8 +37,7 @@ you're ready to add a model:
 like Post, Blog, whatever. This will add a model, migration, and route to your
 app.
 
-Usage
------
+== Usage
 
 Now that you have an article model and a set of routes, you're ready to plug
 it into your app. I'd recommend running `rake routes` to see what routes have
@@ -51,8 +47,7 @@ The Governor initialization will check if Devise is installed, and will try to
 Do The Right Thing if it is. If not, it'll yell at you, so be sure to set up
 your authorization rules in this file.
 
-Authentication/Authorization
-----------------------------
+== Authentication/Authorization
 
 For now, Governor checks with Devise to make sure someone's logged in before
 creating an article, and verifies that the logged in user is an article's
@@ -60,8 +55,7 @@ author before allowing them to edit. You might have your own rules that you'd
 rather apply. You'll have to wait until a future version if you want something
 different, sorry.
 
-Roadmap
--------
+== Roadmap
 
 Less of a roadmap as a politician's promise of what will exist in future
 versions of Governor:
@@ -77,8 +71,7 @@ anything regarding backwards compatibility. Please let me know if something
 you were relying on breaks, and I'll do my best to steer you in the right
 direction or repair functionality.
 
-Contributing to Governor
-------------------------
+== Contributing to Governor
 
 Governor is just getting off the ground now, so while there's a lot to
 implement, the infrastructure might be too shaky to support multiple
@@ -92,9 +85,8 @@ developers. Still, if you're interested in improving this, let's talk.
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
-Copyright
----------
+== Copyright
 
-Copyright © 2011 Liam Morley. See LICENSE.txt for
+Copyright (C) 2011 Liam Morley. See LICENSE.txt for
 further details.
 

data/Rakefile

@@ -13,7 +13,7 @@ require 'jeweler'
 Jeweler::Tasks.new do |gem|
   # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
   gem.name = "governor"
-  gem.homepage = "http://github.com/carpeliam/governor"
+  gem.homepage = "http://carpeliam.github.com/governor"
   gem.license = "MIT"
   gem.summary = %Q{A pluggable blogging system for Rails 3.}
   gem.description = %Q{Because Blogojevich would be too tough to remember. It's a pluggable blogging system for Rails 3.}
@@ -44,7 +44,8 @@ Rake::RDocTask.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "governor #{version}"
+  rdoc.title = "Governor #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.exclude('lib/generators/**/*.rb')
 end

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/governor.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{governor}
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Liam Morley"]
@@ -14,7 +14,7 @@ Gem::Specification.new do |s|
   s.email = %q{liam@carpeliam.com}
   s.extra_rdoc_files = [
     "LICENSE.txt",
-    "README.markdown"
+    "README.rdoc"
   ]
   s.files = [
     ".document",
@@ -22,7 +22,7 @@ Gem::Specification.new do |s|
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
-    "README.markdown",
+    "README.rdoc",
     "Rakefile",
     "VERSION",
     "app/controllers/governor/articles_controller.rb",
@@ -113,7 +113,7 @@ Gem::Specification.new do |s|
     "spec/rails_app/vendor/plugins/.gitkeep",
     "spec/spec_helper.rb"
   ]
-  s.homepage = %q{http://github.com/carpeliam/governor}
+  s.homepage = %q{http://carpeliam.github.com/governor}
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.7}

data/lib/governor.rb

@@ -10,14 +10,67 @@ require 'governor/rails'
 
 
 module Governor
-  
-  mattr_reader :resources, :authorization_rules, :default_resource
-  mattr_accessor :if_not_allowed, :author
   @@resources = {}
+  mattr_reader :resources, :default_resource, :authorization_rules
+  
+  # Specifies the action that should occur if an unpermitted action is
+  # attempted. Usually specified within the initializer, though evaluated in
+  # the scope of a Rails session.
+  #
+  # Example:
+  #
+  #     Governor.if_not_allowed do
+  #       if respond_to?(Devise)
+  #         send("authenticate_#{Devise.default_scope}!")
+  #       else
+  #         raise ArgumentError.new("Set up Governor.if_not_allowed in #{File.expand_path(__FILE__)}")
+  #       end
+  #     end
+  #
+  mattr_accessor :if_not_allowed
+  
+  # Specifies how to reference the author of an article. Usually specified
+  # within the initializer, though evaluated in the scope of a Rails session.
+  #
+  # Example:
+  #
+  #     Governor.author = Proc.new do
+  #       if respond_to?(:current_user)
+  #         current_user
+  #       else
+  #         raise "Set up Governor.author in #{File.expand_path(__FILE__)}"
+  #       end
+  #     end
+  #
+  mattr_accessor :author
+  
+  # Maps a given resource name with a pair of options, to be supplied as
+  # arguments to the routes. Usually called from within +governate+.
   def self.map(resource, options = {})
     @@default_resource ||= self.resources[resource] = Governor::Mapping.new(resource, options)
   end
   
+  # Supply a set of rules that describe what the requirements are to perform a
+  # given Governor-related action on a given article. Usually specified within
+  # the initializer, though evaluated in the scope of a Rails session.
+  #
+  # Example (from the generated initialization file):
+  #
+  #     Governor.authorize_if do |action, article|
+  #       case action.to_sym
+  #       when :new, :create
+  #         if respond_to?(:user_signed_in?)
+  #           user_signed_in?
+  #         else
+  #           raise "Set up Governor.authorize_if in #{File.expand_path(__FILE__)}"
+  #         end
+  #       when :edit, :update, :destroy
+  #         article.author == instance_eval(&Governor.author)
+  #       else
+  #         raise ArgumentError.new('action must be new, create, edit, update, or destroy')
+  #       end
+  #     end
+  #
   def self.authorize_if(&blk)
     @@authorization_rules = blk
   end

data/lib/governor/article.rb

@@ -1,11 +1,17 @@
 module Governor
+  # Include this module into any class that will represent a blog article
+  # post.
   module Article
-    def self.included(base)
+    def self.included(base) #:nodoc:
       base.belongs_to :author, :polymorphic => true
       Governor::PluginManager.resources(:child_resources).each_key do |resource|
         base.has_many resource
       end
       
+      # Will retrieve all of the articles with a given year, month, or day. If
+      # day is not specified, it will find all of the posts for a given month;
+      # if month is not specified, then it will find all of the posts for a
+      # given year. Specifying a page will work with will_paginate.
       def base.find_all_by_date(year, month = nil, day = nil, page = 1)
         from, to = self.time_delta(year, month, day)
         conditions = ['created_at BETWEEN ? AND ?', from, to]

data/lib/governor/controllers/helpers.rb

@@ -1,18 +1,27 @@
 module Governor
-  module Controllers
+  module Controllers #:nodoc:
     module Helpers
+      # Represents the article for this session. Can also be accessed as an
+      # instance variable, for example <code>@article</code> if the Mapping
+      # class is Article.
       def resource
         instance_variable_get("@#{mapping.singular}")
       end
       
+      # Returns a symbol representation of this resource, for example
+      # <code>:article</code> if the Mapping class is Article.
       def resource_sym
         mapping.singular
       end
-
+      
+      # Returns the list of articles for this session. Can also be accessed as
+      # an instance variable, for example <code>@articles</code> if the
+      # Mapping class is Article.
       def resources
         instance_variable_get("@#{mapping.plural}")
       end
-
+      
+      # Returns the Mapping model class, for example: Article.
       def model_class
         @model_class ||= mapping.to
       end

data/lib/governor/formatters.rb

@@ -1,9 +1,9 @@
-# much love to Feather, borrowed from Merb
 module Governor
+  # heavily based on Feather[https://github.com/mleung/feather]
   module Formatters
     class << self
       ##
-      # This registers a block to format article content
+      # Registers a block to format article content
       def register_formatter(name, &block)
         @formatters ||= {'default' => default_formatter}
         raise "Formatter `#{name}` already registered!" unless @formatters[name].nil?
@@ -11,14 +11,14 @@ module Governor
       end
 
       ##
-      # This returns an array of available formatters that have been registered
+      # Returns an array of available formatters that have been registered
       def available_formatters
         @formatters ||= {'default' => default_formatter}
         return @formatters
       end
 
       ##
-      # This returns a default formatter used for replacing line breaks within text
+      # Returns a default formatter used for replacing line breaks within text
       # This is the only formatter included within Governor
       def default_formatter
         Proc.new do |text|
@@ -27,13 +27,13 @@ module Governor
       end
 
       ##
-      # This performs the relevant formatting for the article, and returns the formatted article content
+      # Performs the relevant formatting for the article, and returns the formatted article content
       def format_article(article)
         format_text(article.format, article.post)
       end
 
       ##
-      # This performs the requested formatting, returning the formatted text
+      # Performs the requested formatting, returning the formatted text
       def format_text(formatter, text)
         formatter = 'default' unless available_formatters.include?(formatter)
         @formatters[formatter].call(text).html_safe

data/lib/governor/mapping.rb

@@ -16,17 +16,14 @@ module Governor
       @controller = options[:controller] || 'governor/articles'
     end
     
-    def fullpath
-      "#{@path_prefix}/#{@path}".squeeze("/")
-    end
-    
+    # Provides the resource class.
     def to
       @ref.get
     end
     
+    # Presents a human-readable identifier of the resource type.
     def humanize
       @singular.to_s.humanize
     end
-    
   end
 end

data/lib/governor/plugin.rb

@@ -13,20 +13,58 @@ module Governor
       @migrations << path
     end
     
+    # Adds a nested resource. Any options are passed directly to the router.
+    # Any member or collection routes can be passed in as a block.
+    #
+    # Example:
+    #
+    #     comments = Governor::Plugin.new('comments')
+    #     comments.add_child_resource :comments do
+    #       member do
+    #         put 'mark_spam', 'not_spam'
+    #       end
+    #     end
+    #
     def add_child_resource(name, options={}, &block)
       options[:block] = block if block_given?
       @resources[:child_resources] ||= {}
       @resources[:child_resources][name] = options
     end
     
+    # Specifies that this plugin will display a partial of the given type, at
+    # the given path. This path is relative to the views directory underneath
+    # your app; it's expected that there will be a governor directory
+    # underneath views as well.
+    #
+    # DOCUMENTME I need to indicate which types are supported.
+    #
+    # Example:
+    #
+    #     comments.register_partial :after_article_whole, 'articles/comments'
+    #
     def register_partial(type, path)
       @partials[type.to_sym] = path
     end
     
+    # Returns the path associated with the given partial type.
+    #
+    # Example:
+    #
+    #     comments.partial_for(:after_article_whole) # => 'articles/comments'
+    #
     def partial_for(type)
       @partials[type.to_sym]
     end
     
+    # Associates a helper for this plugin, to be included into the controller
+    # and view.
+    #
+    # Currently this requires a string. This will be refactored soon.
+    #
+    # Example:
+    #
+    #     comments.add_helper "GovernorCommentsHelper"
+    #
     def add_helper(mod)
       @helpers << mod
     end

data/lib/governor/plugin_manager.rb

@@ -6,10 +6,27 @@ module Governor
     class << self
       @@plugins = []
       
+      # Registers the given plugins with Governor. Usually called within the
+      # context of a single plugin, but any number of plugins can be
+      # registered.
+      #
+      # Example:
+      #
+      #     comments = Governor::Plugin.new('comments')
+      #     Governor::PluginManager.register comments
+      #
       def register(*plugins)
         @@plugins += plugins
       end
       
+      # A convenience method for obtaining the resources for plugins.
+      #
+      # Example:
+      #
+      #     comments = Governor::Plugin.new('comments')
+      #     comments.add_child_resource :comments, :path_names => {:create => 'comment'}
+      #     Governor::PluginManager.register comments
+      #     Governor::PluginManager.resources(:child_resources) # => {:comments => {:create => 'comment'}}
       def resources(name)
         @@plugins.map{|p| p.resources[name] }.compact.reduce({}, :merge)
       end

data/lib/governor/rails.rb

@@ -1,6 +1,7 @@
 require 'governor/rails/routes'
 
 module Governor
+  # Standard <code>Rails::Engine</code>.
   class Engine < ::Rails::Engine
     
   end

data/lib/governor/rails/routes.rb

@@ -1,20 +1,34 @@
-module ActionDispatch::Routing
-  class Mapper
-    def governate(*resources)
-      options = resources.extract_options!
-      resources.map!(&:to_sym)
-      resources.each do |resource|
-        mapping = Governor.map(resource, options)
-        resources mapping.resource, :controller => mapping.controller, :governor_mapping => resource do
-          Governor::PluginManager.resources(:child_resources).each_pair do |child_resource, options|
-            options = {:module => :governor}.merge options
-            block = options.delete :block
-            resources(child_resource, options) do
-              instance_eval(&block) if block.present?
+module ActionDispatch #:nodoc:
+  module Routing #:nodoc:
+    class Mapper
+      # Attach a Governor-based resource to your application's Rails routes.
+      #
+      # Example:
+      #
+      #     RailsApp::Application.routes.draw do
+      #       # ...
+      #       governate :articles
+      #       # ...
+      #     end
+      #
+      # This will attach a controller that will create and modify Article
+      # objects.
+      def governate(*resources)
+        options = resources.extract_options!
+        resources.map!(&:to_sym)
+        resources.each do |resource|
+          mapping = Governor.map(resource, options)
+          resources mapping.resource, :controller => mapping.controller, :governor_mapping => resource do
+            Governor::PluginManager.resources(:child_resources).each_pair do |child_resource, options|
+              options = {:module => :governor}.merge options
+              block = options.delete :block
+              resources(child_resource, options) do
+                instance_eval(&block) if block.present?
+              end
             end
           end
         end
       end
     end
   end
-end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: governor
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: false
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Liam Morley
@@ -205,14 +205,14 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE.txt
-- README.markdown
+- README.rdoc
 files: 
 - .document
 - .rspec
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.markdown
+- README.rdoc
 - Rakefile
 - VERSION
 - app/controllers/governor/articles_controller.rb
@@ -303,7 +303,7 @@ files:
 - spec/rails_app/vendor/plugins/.gitkeep
 - spec/spec_helper.rb
 has_rdoc: true
-homepage: http://github.com/carpeliam/governor
+homepage: http://carpeliam.github.com/governor
 licenses: 
 - MIT
 post_install_message: