Merge branch 'master' of git@github.com:lifo/docrails

1 files changed, 98 insertions, 0 deletions

diff --git a/railties/doc/guides/source/creating_plugins/generators.txt b/railties/doc/guides/source/creating_plugins/generators.txt
new file mode 100644
index 0000000000..f856bec7a2
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/generators.txt
@@ -0,0 +1,98 @@
+== Generators ==
+
+Many plugins ship with generators.  When you created the plugin above, you specified the --with-generator option, so you already have the generator stubs in 'vendor/plugins/yaffle/generators/yaffle'.
+
+Building generators is a complex topic unto itself and this section will cover one small aspect of generators: generating a simple text file.
+
+=== Testing generators ===
+
+Many rails plugin authors do not test their generators, however testing generators is quite simple.  A typical generator test does the following:
+
+ * Creates a new fake rails root directory that will serve as destination
+ * Runs the generator
+ * Asserts that the correct files were generated
+ * Removes the fake rails root
+
+This section will describe how to create a simple generator that adds a file.  For the generator in this section, the test could look something like this:
+
+*vendor/plugins/yaffle/test/definition_generator_test.rb*
+
+[source, ruby]
+------------------------------------------------------------------
+require File.dirname(__FILE__) + '/test_helper.rb'
+require 'rails_generator'
+require 'rails_generator/scripts/generate'
+
+class DefinitionGeneratorTest < Test::Unit::TestCase
+
+  def setup
+    FileUtils.mkdir_p(fake_rails_root)
+    @original_files = file_list
+  end
+
+  def teardown
+    FileUtils.rm_r(fake_rails_root)
+  end
+  
+  def test_generates_correct_file_name
+    Rails::Generator::Scripts::Generate.new.run(["yaffle_definition"], :destination => fake_rails_root)
+    new_file = (file_list - @original_files).first
+    assert_equal "definition.txt", File.basename(new_file)
+  end
+
+  private
+  
+    def fake_rails_root
+      File.join(File.dirname(__FILE__), 'rails_root')
+    end
+  
+    def file_list
+      Dir.glob(File.join(fake_rails_root, "*"))
+    end
+  
+end
+------------------------------------------------------------------
+
+You can run 'rake' from the plugin directory to see this fail.  Unless you are doing more advanced generator commands it typically suffices to just test the Generate script, and trust that rails will handle the Destroy and Update commands for you.
+
+To make it pass, create the generator:
+
+*vendor/plugins/yaffle/generators/yaffle_definition/yaffle_definition_generator.rb*
+
+[source, ruby]
+------------------------------------------------------------------
+class YaffleDefinitionGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.file "definition.txt", "definition.txt"
+    end
+  end
+end
+------------------------------------------------------------------
+
+=== The USAGE file ===
+
+If you plan to distribute your plugin, developers will expect at least a minimum of documentation.  You can add simple documentation to the generator by updating the USAGE file.
+
+Rails ships with several built-in generators.  You can see all of the generators available to you by typing the following at the command line:
+
+------------------------------------------------------------------
+./script/generate
+------------------------------------------------------------------
+
+You should see something like this:
+
+------------------------------------------------------------------
+Installed Generators
+  Plugins (vendor/plugins): yaffle_definition
+  Builtin: controller, integration_test, mailer, migration, model, observer, plugin, resource, scaffold, session_migration
+------------------------------------------------------------------
+
+When you run `script/generate yaffle_definition -h` you should see the contents of your 'vendor/plugins/yaffle/generators/yaffle_definition/USAGE'.  
+
+For this plugin, update the USAGE file could look like this:
+
+------------------------------------------------------------------
+Description:
+    Adds a file with the definition of a Yaffle to the app's main directory
+------------------------------------------------------------------