From 6b8500ce48f45f18696f6215b8a01f5cf0e328b5 Mon Sep 17 00:00:00 2001 From: Jeff Dean Date: Sun, 16 Nov 2008 22:27:08 -0500 Subject: Rails guide: Added PluginGem section, reorganized the odds and ends. --- railties/doc/guides/html/authors.html | 5 + railties/doc/guides/html/creating_plugins.html | 190 +++++++++++++-------- railties/doc/guides/html/routing_outside_in.html | 2 +- railties/doc/guides/source/authors.txt | 6 + .../guides/source/creating_plugins/appendix.txt | 26 ++- .../guides/source/creating_plugins/controllers.txt | 2 +- .../doc/guides/source/creating_plugins/gem.txt | 3 - .../doc/guides/source/creating_plugins/gems.txt | 50 ++++++ .../doc/guides/source/creating_plugins/index.txt | 6 +- .../guides/source/creating_plugins/migrations.txt | 4 +- .../source/creating_plugins/odds_and_ends.txt | 69 -------- .../doc/guides/source/creating_plugins/rdoc.txt | 18 ++ .../doc/guides/source/creating_plugins/tasks.txt | 29 ++++ 13 files changed, 254 insertions(+), 156 deletions(-) delete mode 100644 railties/doc/guides/source/creating_plugins/gem.txt create mode 100644 railties/doc/guides/source/creating_plugins/gems.txt delete mode 100644 railties/doc/guides/source/creating_plugins/odds_and_ends.txt create mode 100644 railties/doc/guides/source/creating_plugins/rdoc.txt create mode 100644 railties/doc/guides/source/creating_plugins/tasks.txt diff --git a/railties/doc/guides/html/authors.html b/railties/doc/guides/html/authors.html index a54135b14d..6fd556d2cd 100644 --- a/railties/doc/guides/html/authors.html +++ b/railties/doc/guides/html/authors.html @@ -231,6 +231,11 @@ Heiko has rarely looked back.

Tore Darell is an independent developer based in Menton, France who specialises in cruft-free web applications using Ruby, Rails and unobtrusive JavaScript. His home on the internet is his blog Sneaky Abstractions.

+
+
+
Jeff Dean
+

Jeff Dean is a software engineer with Pivotal Labs.

+
diff --git a/railties/doc/guides/html/creating_plugins.html b/railties/doc/guides/html/creating_plugins.html index 45c81f2af1..1762bd95d2 100644 --- a/railties/doc/guides/html/creating_plugins.html +++ b/railties/doc/guides/html/creating_plugins.html @@ -269,28 +269,20 @@ ul#navMain {
  • Create a custom rake task
    • -
  • Call plugin migrations from regular migrations
    • +
  • Call migrations directly
    • + +
  • Generate migrations
  • - Generating migrations + Rake tasks
  • - Odds and ends - + PluginGems +
    • +
  • + RDoc Documentation
  • Appendix @@ -1030,7 +1022,7 @@ http://www.gnu.org/software/src-highlite -->

    This section describes how to add a controller named woodpeckers to your plugin that will behave the same as a controller in your main app. This is very similar to adding a model.

    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:

    end end
    -

    11.2. Call plugin migrations from regular migrations

    +

    11.2. Call migrations directly

    vendor/plugins/yaffle/lib/yaffle.rb:

    several plugin frameworks such as Desert and Engines provide more advanced plugin functionality.
    -
    -

    12. Generating migrations

    -
    +

    11.3. 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:

    • @@ -1709,41 +1699,8 @@ http://www.gnu.org/software/src-highlite --> end
    -

    13. Odds and ends

    +

    12. Rake tasks

    -

    13.1. 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
    -
    -

    13.2. 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

    @@ -1762,28 +1719,99 @@ http://www.gnu.org/software/src-highlite -->

    When you run rake -T from your plugin you will see:

    -
    yaffle:squawk             # Prints out the word 'Yaffle'
    +
    ...
+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.

    -

    13.3. 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!

    +

    Note that tasks from vendor/plugins/yaffle/Rakefile are not available to the main app.

    +
    +

    13. 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:

    -
    config.plugin_paths << File.join(RAILS_ROOT,"vendor","plugins","yaffle","lib","plugins")
+
    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
    -

    13.4. 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.

    -

    13.5. 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.

    +

    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.

    -

    14. Appendix

    +

    14. RDoc Documentation

    -

    14.1. References

    +

    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
    +
    +
    +

    15. Appendix

    +
    +

    If you prefer to use RSpec instead of tets, you may be interested in the RSpec Plugin Generator.

    +

    15.1. References

    • @@ -1811,20 +1839,27 @@ http://www.gnu.org/software/src-highlite -->

    -

    14.2. Final plugin directory structure

    +

    15.2. Final plugin directory structure

    The final plugin should have a directory structure that looks something like this:

    -
    vendor/plugins/yaffle/
-|-- MIT-LICENSE
+
    |-- 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
@@ -1834,11 +1869,16 @@ http://www.gnu.org/software/src-highlite -->
 |   |   |   `-- 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
@@ -1848,7 +1888,9 @@ http://www.gnu.org/software/src-highlite -->
 |   |-- 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/html/routing_outside_in.html b/railties/doc/guides/html/routing_outside_in.html
index 947d0836ce..1d313b619f 100644
--- a/railties/doc/guides/html/routing_outside_in.html
+++ b/railties/doc/guides/html/routing_outside_in.html
@@ -1454,7 +1454,7 @@ http://www.gnu.org/software/src-highlite -->
 
 Tip
 
-If your application has many RESTful routes, using :only and :accept to generate only the routes that you actually need can cut down on memory use and speed up the routing process.
+If your application has many RESTful routes, using :only and :except to generate only the routes that you actually need can cut down on memory use and speed up the routing process.

    3.8. Nested Resources

    diff --git a/railties/doc/guides/source/authors.txt b/railties/doc/guides/source/authors.txt index 94dfc4db08..987238eb4c 100644 --- a/railties/doc/guides/source/authors.txt +++ b/railties/doc/guides/source/authors.txt @@ -37,3 +37,9 @@ Heiko has rarely looked back. Tore Darell is an independent developer based in Menton, France who specialises in cruft-free web applications using Ruby, Rails and unobtrusive JavaScript. His home on the internet is his blog http://tore.darell.no/[Sneaky Abstractions]. *********************************************************** + +.Jeff Dean +[[zilkey]] +*********************************************************** +Jeff Dean is a software engineer with http://pivotallabs.com/[Pivotal Labs]. +*********************************************************** 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 -- cgit v1.2.3