Creating a new Rails Engine "blorgh" with RSpec and YARD

rails_engine.md

Creating a new Rails Engine "blorgh" w/ RSpec + YARD

I did all of the following with Rails 3.2.12 and Bundler 1.3.0 acquired with

$> gem install --version '3.2.12' rails
$> gem install --version '1.3.0' bundler

Start by using Rails' Engine generator with a few options.

$> rails plugin new blorgh --full --dummy-path=spec/dummy \
                           --skip-test-unit --skip-bundle --skip-gemspec

Then we'll use bundler's more intelligent handling of the "gemification".

$> bundle gem blorgh

When prompted, give the following answers to bundle's questions.

• n to blorgh/Gemfile
• y to blorgh/Rakefile
• y to blorgh/.gitignore
• n to blorgh/lib/blorgh.rb

Enter the blorgh directory.

$> cd blorgh

Modify blorgh.gemspec in the following way.

Gem::Specification.new do |spec|
    .
    .
    .
    spec.add_development_dependency "rails"			# <- Add
    spec.add_development_dependency "rspec-rails"	# <- Add
    spec.add_development_dependency "jquery-rails"	# <- Add
    spec.add_development_dependency "yard"			# <- Add
    spec.add_development_dependency "redcarpet"		# <- Add
end

Comment out or delete the following line in Gemfile.

gem "jquery-rails"

Add the following to Rakefile.

require 'yard'
YARD::Rake::YardocTask.new

Add these lines to the end of .gitignore:

log/*.log
pkg/
spec/dummy/db/*.sqlite3
spec/dummy/log/*.log
spec/dummy/tmp/
spec/dummy/.sass-cache	

Install RSpec such that it will run specs both in your gem and in the dummy rails app in spec/dummy:

$> cd spec/dummy
$> ln -s ../../spec
$> rails generate rspec:install
$> cd -

Remove "duplicates":

$> rm MIT-LICENSE
$> rm README.rdoc

Edit README.md, LICENSE.txt, lib/blorgh/version.rb, and blorgh.gemspec as necessary, especially fixing the TODOs in blorgh.gemspec, or your gem won't build.

Add and commit everything.

$> git add --all
$> git commit -m "initial commit of bare rails engine gem"

Now build your gem for the first time.

$> rake install

Your gem is now built and installed locally, and you can reference it in a rails app by putting the following in the app's Gemfile and running "bundle install".

gem "blorgh"

When you make changes, especially adding untracked files, you must commit them and then rerun "rake install".

If you changed the version of your gem (lib/blorgh/version.rb), then you must then rerun "bundle install" in your rails app.