The Rails Guides are actually really good overview documentation. The days of saying Rails documentation is terrible are over, with the good guides, and good api-level docs too.
I knew there was a Plugin Guide, but I only just noticed there’s an Engine Guide too.
For reasons I don’t know, the Engines guide is not listed on the Guides home table of contents page, even though it’s available at guides.rubyonrails.org. It also doesn’t google very well.
So here’s my part to publisize it. Both the Engines and Plugin guides are pretty good. They’re also overlapping in coverage. As the Engines guide says:
Engines are also closely related to plugins where the two share a common lib directory structure and are both generated using the rails plugin new generator. The difference being that an engine is considered a “full plugin” by Rails as indicated by the --full option that’s passed to the generator command, but this guide will refer to them simply as “engines” throughout. An engine can be a plugin, and a plugin can be an engine.
Maybe ideally they’d be merged, but they’re both good guides; you’ll probably want to review both if you’re working on Rails plugins OR engines.
Actually, you won’t find those exact words above in the current stable release of the Engines Guide, you’ll find it on edgeguides.rubyonrails.org instead. I believe the actual guides are versioned with Rails releases — after one is released to guides.rubyonrails.org with the most recent rails version, it’s never changed (but perhaps for very serious errors), rather any changes will be released with the next Rails release.But you can preview em on edgeguides (I’m not sure if new ‘stable’ guides at guides.rubyonrails are pushed with new patch-releases of Rails, or just new minor-releases).
So you might find edgeguides contains some content that doesn’t apply to the current Rails release; but it may also contain improved explication or better examples or more coverage, as a result of contributors improving things. It’s worth checking edgeguides for a complicated topic. In this case, the Engines guide is rather improved in the ‘edge’ version as of this writing, and I don’t believe it includes anything that won’t work in Rails 3.2, it’s worth checking out.
A while ago I learned about `rails plugin new plugin_name` command to give you a gem plugin skeleton. Including a very useful dummy app for testing. Before that I had been doing it by hand! But this generates a very lightweight plugin, I was going in by hand and adding the files and methods turning into a heavyweight engine. I only just now, from the Engines Guide, noticed you can do `rails plugin new plugin_name -full` to get a fully engine-ized plugin.
Note on plugins ‘vs’. gems
It’s not a “vs.”. Since Rails 3.0, Rails plugins could be distributed as gems. Since Rails 3.2, distributing a plugin as anything but a gem is deprecated — vendor/plugins is probably going to go away in future releases.
Although the great architecture of Rails 3 is such it wouldn’t be that hard to put it back into a particular app yourself, if you really needed to for legacy purposes. But in general, you don’t want, plugins-as-gems are great, making dependency management a lot more sane.
The current guides.rubyonrails.org plugin guide still gives you the option of a /vendor/plugin or a plugin-as-gem — it ought not to, since the current Rails version deprecates /vendor/plugin. So don’t do that with a new plugin.
The edgeguide is more clear. (I made the commit myself! Did you know anyone can commit to docrails github repo? The commits are reviewed by editors before being merged into actual rails, and in the case of guides, eventually deployed to guides.rubyonrails).
Bibliographic Wilderness 