make the location of USAGE file configurable

railties/lib/rails/generators/base.rb

@@ -27,18 +27,27 @@ def self.source_root(path=nil)
         @_source_root ||= default_source_root
       end
 
-      # Tries to get the description from a USAGE file one folder above the source
-      # root otherwise uses a default description.
+      # Tries to get the description from a USAGE file, otherwise uses a
+      # default description.
       def self.desc(description=nil)
         return super if description
-        usage = source_root && File.expand_path("../USAGE", source_root)
 
-        @desc ||= if usage && File.exist?(usage)
-          ERB.new(File.read(usage)).result(binding)
+        @desc ||= if usage_file && File.exist?(usage_file)
+          ERB.new(File.read(usage_file)).result(binding)
         else
           "Description:\n    Create #{base_name.humanize.downcase} files for #{generator_name} generator."
         end
       end
+
+      # Sets the location of the USAGE file for this generator.
+      # Defaults to one folder above the source root.
+      def self.usage_file(path=nil)
+        if path
+          @usage_file = path
+        else
+          @usage_file ||= source_root && File.expand_path("../USAGE", source_root)
+        end
+      end
 
       # Convenience method to get the namespace from the class name. It's the
       # same as Thor default except that the Generator at the end of the class

railties/test/generators_test.rb

@@ -203,8 +203,27 @@ def test_source_paths_for_not_namespaced_generators
   end
 
   def test_usage_with_embedded_ruby
-    require File.expand_path("fixtures/lib/generators/usage_template/usage_template_generator", File.dirname(__FILE__))
-    output = capture(:stdout) { Rails::Generators.invoke :usage_template, ['--help'] }
-    assert_match /:: 2 ::/, output
+    load File.expand_path("fixtures/lib/generators/usage_template/usage_template_generator.rb", File.dirname(__FILE__))
+    begin
+      output = capture(:stdout) { Rails::Generators.invoke :usage_template, ['--help'] }
+      assert_match /:: 2 ::/, output
+    ensure
+      # to prevent tainting other tests
+      Object.send :remove_const, :UsageTemplateGenerator
+    end
+  end
+
+  def test_usage_in_nonstandard_location
+    base = File.expand_path("fixtures/lib/generators/usage_template", File.dirname(__FILE__))
+    load File.join(base, "usage_template_generator.rb")
+    begin
+      UsageTemplateGenerator.source_root "." # so that it can't find default usage file
+      UsageTemplateGenerator.usage_file File.join(base, "USAGE")
+      output = capture(:stdout) { Rails::Generators.invoke :usage_template, ['--help'] }
+      assert_match /:: 2 ::/, output
+    ensure
+      # to prevent tainting other tests
+      Object.send :remove_const, :UsageTemplateGenerator
+    end
   end
 end