Rails guide: Added PluginGem section, reorganized the odds and ends.

9 files changed, 126 insertions, 81 deletions

diff --git a/railties/doc/guides/source/creating_plugins/appendix.txt b/railties/doc/guides/source/creating_plugins/appendix.txt
index d890f861b5..19f677c5fd 100644
--- a/railties/doc/guides/source/creating_plugins/appendix.txt
+++ b/railties/doc/guides/source/creating_plugins/appendix.txt
@@ -1,5 +1,7 @@
 == Appendix ==
 
+If you prefer to use RSpec instead of tets, you may be interested in the http://github.com/pat-maddox/rspec-plugin-generator/tree/master[RSpec Plugin Generator].
+
 === References ===
 
  * http://nubyonrails.com/articles/the-complete-guide-to-rails-plugins-part-i
@@ -13,16 +15,23 @@
 The final plugin should have a directory structure that looks something like this:
 
 ------------------------------------------------
-vendor/plugins/yaffle/
 |-- MIT-LICENSE
 |-- README
 |-- Rakefile
 |-- generators
-|   `-- yaffle
+|   |-- yaffle_definition
+|   |   |-- USAGE
+|   |   |-- templates
+|   |   |   `-- definition.txt
+|   |   `-- yaffle_definition_generator.rb
+|   |-- yaffle_migration
+|   |   |-- USAGE
+|   |   |-- templates
+|   |   `-- yaffle_migration_generator.rb
+|   `-- yaffle_route
 |       |-- USAGE
 |       |-- templates
-|       |   `-- definition.txt
-|       `-- yaffle_generator.rb
+|       `-- yaffle_route_generator.rb
 |-- install.rb
 |-- lib
 |   |-- app
@@ -32,11 +41,16 @@ vendor/plugins/yaffle/
 |   |   |   `-- woodpeckers_helper.rb
 |   |   `-- models
 |   |       `-- woodpecker.rb
+|   |-- db
+|   |   `-- migrate
+|   |       `-- 20081116181115_create_birdhouses.rb
 |   |-- yaffle
 |   |   |-- acts_as_yaffle.rb
 |   |   |-- commands.rb
 |   |   `-- core_ext.rb
 |   `-- yaffle.rb
+|-- pkg
+|   `-- yaffle-0.0.1.gem
 |-- rails
 |   `-- init.rb
 |-- tasks
@@ -46,7 +60,9 @@ vendor/plugins/yaffle/
 |   |-- core_ext_test.rb
 |   |-- database.yml
 |   |-- debug.log
-|   |-- generator_test.rb
+|   |-- definition_generator_test.rb
+|   |-- migration_generator_test.rb
+|   |-- route_generator_test.rb
 |   |-- schema.rb
 |   |-- test_helper.rb
 |   |-- woodpecker_test.rb
diff --git a/railties/doc/guides/source/creating_plugins/controllers.txt b/railties/doc/guides/source/creating_plugins/controllers.txt
index 4f4417b416..e38cf8251e 100644
--- a/railties/doc/guides/source/creating_plugins/controllers.txt
+++ b/railties/doc/guides/source/creating_plugins/controllers.txt
@@ -4,7 +4,7 @@ This section describes how to add a controller named 'woodpeckers' to your plugi
 
 You can test your plugin's controller as you would test any other controller:
 
-*vendor/plugins/yaffle/yaffle/woodpeckers_controller_test.rb:*
+*vendor/plugins/yaffle/test/woodpeckers_controller_test.rb:*
 
 [source, ruby]
 ----------------------------------------------
diff --git a/railties/doc/guides/source/creating_plugins/gem.txt b/railties/doc/guides/source/creating_plugins/gem.txt
deleted file mode 100644
index 8a0bbb3bc0..0000000000
--- a/railties/doc/guides/source/creating_plugins/gem.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-== Gems ==
-
-http://www.mbleigh.com/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins
\ No newline at end of file
diff --git a/railties/doc/guides/source/creating_plugins/gems.txt b/railties/doc/guides/source/creating_plugins/gems.txt
new file mode 100644
index 0000000000..67d55adb3a
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/gems.txt
@@ -0,0 +1,50 @@
+== PluginGems ==
+
+Turning your rails plugin into a gem is a simple and straightforward task.  This section will cover how to turn your plugin into a gem.  It will not cover how to distribute that gem.
+
+Historically rails plugins loaded the plugin's 'init.rb' file.  In fact some plugins contain all of their code in that one file.  To be compatible with plugins, 'init.rb' was moved to 'rails/init.rb'.
+
+It's common practice to put any developer-centric rake tasks (such as tests, rdoc and gem package tasks) in 'Rakefile'.  A rake task that packages the gem might look like this:
+
+*vendor/plugins/yaffle/Rakefile:*
+
+[source, ruby]
+----------------------------------------------
+PKG_FILES = FileList[
+  '[a-zA-Z]*',
+  'generators/**/*', 
+  'lib/**/*', 
+  'rails/**/*',
+  'tasks/**/*', 
+  'test/**/*'
+]
+
+spec = Gem::Specification.new do |s| 
+  s.name = "yaffle"
+  s.version = "0.0.1"
+  s.author = "Gleeful Yaffler"
+  s.email = "yaffle@example.com"
+  s.homepage = "http://yafflers.example.com/"
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Sharing Yaffle Goodness"
+  s.files = PKG_FILES.to_a
+  s.require_path = "lib"
+  s.has_rdoc = false
+  s.extra_rdoc_files = ["README"]
+end
+
+desc 'Turn this plugin into a gem.'
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end 
+----------------------------------------------
+
+To build and install the gem locally, run the following commands:
+
+----------------------------------------------
+cd vendor/plugins/yaffle
+rake gem
+sudo gem install pkg/yaffle-0.0.1.gem
+----------------------------------------------
+
+To test this, create a new rails app, add 'config.gem "yaffle"' to environment.rb and all of your plugin's functionality will be available to you.
\ No newline at end of file
diff --git a/railties/doc/guides/source/creating_plugins/index.txt b/railties/doc/guides/source/creating_plugins/index.txt
index 5d10fa4f31..0607bc7487 100644
--- a/railties/doc/guides/source/creating_plugins/index.txt
+++ b/railties/doc/guides/source/creating_plugins/index.txt
@@ -51,6 +51,10 @@ include::generator_commands.txt[]
 
 include::migrations.txt[]
 
-include::odds_and_ends.txt[]
+include::tasks.txt[]
+
+include::gems.txt[]
+
+include::rdoc.txt[]
 
 include::appendix.txt[]
diff --git a/railties/doc/guides/source/creating_plugins/migrations.txt b/railties/doc/guides/source/creating_plugins/migrations.txt
index 7154f0bc06..4dd932734d 100644
--- a/railties/doc/guides/source/creating_plugins/migrations.txt
+++ b/railties/doc/guides/source/creating_plugins/migrations.txt
@@ -63,7 +63,7 @@ namespace :db do
 end
 ----------------------------------------------
 
-=== Call plugin migrations from regular migrations ===
+=== Call migrations directly ===
 
 *vendor/plugins/yaffle/lib/yaffle.rb:*
 
@@ -91,7 +91,7 @@ end
 
 NOTE: several plugin frameworks such as Desert and Engines provide more advanced plugin functionality.
 
-== Generating migrations ==
+=== Generate migrations ===
 
 Generating migrations has several advantages over other methods.  Namely, you can allow other developers to more easily customize the migration.  The flow looks like this:
 
diff --git a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt b/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
deleted file mode 100644
index e328c04a79..0000000000
--- a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
+++ /dev/null
@@ -1,69 +0,0 @@
-== Odds and ends ==
-
-=== Generate RDoc Documentation ===
-
-Once your plugin is stable, the tests pass on all database and you are ready to deploy do everyone else a favor and document it!  Luckily, writing documentation for your plugin is easy.
-
-The first step is to update the README file with detailed information about how to use your plugin.  A few key things to include are:
-
- * Your name.
- * How to install.
- * How to add the functionality to the app (several examples of common use cases).
- * Warning, gotchas or tips that might help save users time.
-
-Once your README is solid, go through and add rdoc comments to all of the methods that developers will use.
-
-Before you generate your documentation, be sure to go through and add nodoc comments to those modules and methods that are not important to your users.
-
-Once your comments are good to go, navigate to your plugin directory and run:
-
-    rake rdoc
-
-=== Write custom Rake tasks in your plugin ===
-
-When you created the plugin with the built-in rails generator, it generated a rake file for you in 'vendor/plugins/yaffle/tasks/yaffle.rake'.  Any rake task you add here will be available to the app.
-
-Many plugin authors put all of their rake tasks into a common namespace that is the same as the plugin, like so:
-
-*vendor/plugins/yaffle/tasks/yaffle.rake*
-
-[source, ruby]
----------------------------------------------------------
-namespace :yaffle do
-  desc "Prints out the word 'Yaffle'"
-  task :squawk => :environment do
-    puts "squawk!"
-  end
-end
----------------------------------------------------------
-
-When you run `rake -T` from your plugin you will see:
-
----------------------------------------------------------
-yaffle:squawk             # Prints out the word 'Yaffle'
----------------------------------------------------------
-
-You can add as many files as you want in the tasks directory, and if they end in .rake Rails will pick them up.
-
-=== Store plugins in alternate locations ===
-
-You can store plugins wherever you want - you just have to add those plugins to the plugins path in 'environment.rb'.
-
-Since the plugin is only loaded after the plugin paths are defined, you can't redefine this in your plugins - but it may be good to now.
-
-You can even store plugins inside of other plugins for complete plugin madness!
-
-[source, ruby]
----------------------------------------------------------
-config.plugin_paths << File.join(RAILS_ROOT,"vendor","plugins","yaffle","lib","plugins")
----------------------------------------------------------
-
-=== Create your own Plugin Loaders and Plugin Locators ===
-
-If the built-in plugin behavior is inadequate, you can change almost every aspect of the location and loading process.  You can write your own plugin locators and plugin loaders, but that's beyond the scope of this tutorial.
-
-
-=== Use Custom Plugin Generators ===
-
-If you are an RSpec fan, you can install the `rspec_plugin_generator` gem, which will generate the spec folder and database for you. See http://github.com/pat-maddox/rspec-plugin-generator/tree/master.
-
diff --git a/railties/doc/guides/source/creating_plugins/rdoc.txt b/railties/doc/guides/source/creating_plugins/rdoc.txt
new file mode 100644
index 0000000000..0f6f843c42
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/rdoc.txt
@@ -0,0 +1,18 @@
+== RDoc Documentation ==
+
+Once your plugin is stable and you are ready to deploy do everyone else a favor and document it!  Luckily, writing documentation for your plugin is easy.
+
+The first step is to update the README file with detailed information about how to use your plugin.  A few key things to include are:
+
+ * Your name
+ * How to install
+ * How to add the functionality to the app (several examples of common use cases)
+ * Warning, gotchas or tips that might help save users time
+
+Once your README is solid, go through and add rdoc comments to all of the methods that developers will use.  It's also customary to add '#:nodoc:' comments to those parts of the code that are not part of the public api.
+
+Once your comments are good to go, navigate to your plugin directory and run:
+
+---------------------------------------------------------
+rake rdoc
+---------------------------------------------------------
diff --git a/railties/doc/guides/source/creating_plugins/tasks.txt b/railties/doc/guides/source/creating_plugins/tasks.txt
new file mode 100644
index 0000000000..c71ba42bb0
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/tasks.txt
@@ -0,0 +1,29 @@
+== Rake tasks ==
+
+When you created the plugin with the built-in rails generator, it generated a rake file for you in 'vendor/plugins/yaffle/tasks/yaffle.rake'.  Any rake task you add here will be available to the app.
+
+Many plugin authors put all of their rake tasks into a common namespace that is the same as the plugin, like so:
+
+*vendor/plugins/yaffle/tasks/yaffle.rake*
+
+[source, ruby]
+---------------------------------------------------------
+namespace :yaffle do
+  desc "Prints out the word 'Yaffle'"
+  task :squawk => :environment do
+    puts "squawk!"
+  end
+end
+---------------------------------------------------------
+
+When you run `rake -T` from your plugin you will see:
+
+---------------------------------------------------------
+...
+yaffle:squawk             # Prints out the word 'Yaffle'
+...
+---------------------------------------------------------
+
+You can add as many files as you want in the tasks directory, and if they end in .rake Rails will pick them up.
+
+Note that tasks from 'vendor/plugins/yaffle/Rakefile' are not available to the main app.
\ No newline at end of file