Running a Local Gem Documentation Server on Mac OS X

2008-06-10

When I first started playing around with Ruby on Rails, one of the things that struck me was how development was done completely locally. Instead of uploading or synchronizing your source code to a remote web server, you simply fired up a Ruby web server process on your local machine, and the development process seemed to flow more smoothly.

In that same vein, documentation for Ruby gems can be annoying to hunt down. You have to go to the gem’s web site, and hope that RDoc exists somewhere. Or, you can navigate to your gem’s local install directory and poke around in there. Too much work, and it could break your flow. Not anymore:

$ gem server

Now, just visit http://localhost:8808, and you’re good to go. That easy!

Also, you may find yourself missing RDoc on updated gems, so make sure to do this when it bothers you:

$ gem rdoc [--all|gem_name]

Now, it would be great if the server just started automatically on boot up, with no need for a command line directive. In Mac OS X Leopard, the preferred way is to use launchd/launchctl, which is about as obvious to the uninitiated as the rules of Cricket. Luckily, there’s Lingon, which wraps all that ugly XML in a nice GUI. Make a new entry that looks like this:

Note the full path to the gem command, which I needed for the launch command to work. And that’s it. Full documentation to all your locally installed gems, available whenever you need them.

Special thanks to Daniel Fischer for the ‘gem server’ tip, and Brandon Beacher for the tip on Lingon.