vendor/rails/railties/doc/guides/source/creating_plugins/odds_and_ends.txt

   1 == Odds and ends ==
   2
   3 === Generate RDoc Documentation ===
   4
   5 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.
   6
   7 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:
   8
   9  * Your name.
  10  * How to install.
  11  * How to add the functionality to the app (several examples of common use cases).
  12  * Warning, gotchas or tips that might help save users time.
  13
  14 Once your README is solid, go through and add rdoc comments to all of the methods that developers will use.
  15
  16 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.
  17
  18 Once your comments are good to go, navigate to your plugin directory and run:
  19
  20     rake rdoc
  21
  22 === Write custom Rake tasks in your plugin ===
  23
  24 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.
  25
  26 Many plugin authors put all of their rake tasks into a common namespace that is the same as the plugin, like so:
  27
  28 *vendor/plugins/yaffle/tasks/yaffle.rake*
  29
  30 [source, ruby]
  31 ---------------------------------------------------------
  32 namespace :yaffle do
  33   desc "Prints out the word 'Yaffle'"
  34   task :squawk => :environment do
  35     puts "squawk!"
  36   end
  37 end
  38 ---------------------------------------------------------
  39
  40 When you run `rake -T` from your plugin you will see:
  41
  42 ---------------------------------------------------------
  43 yaffle:squawk             # Prints out the word 'Yaffle'
  44 ---------------------------------------------------------
  45
  46 You can add as many files as you want in the tasks directory, and if they end in .rake Rails will pick them up.
  47
  48 === Store plugins in alternate locations ===
  49
  50 You can store plugins wherever you want - you just have to add those plugins to the plugins path in 'environment.rb'.
  51
  52 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.
  53
  54 You can even store plugins inside of other plugins for complete plugin madness!
  55
  56 [source, ruby]
  57 ---------------------------------------------------------
  58 config.plugin_paths << File.join(RAILS_ROOT,"vendor","plugins","yaffle","lib","plugins")
  59 ---------------------------------------------------------
  60
  61 === Create your own Plugin Loaders and Plugin Locators ===
  62
  63 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.
  64
  65
  66 === Use Custom Plugin Generators ===
  67
  68 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.
  69