Generating rdoc for gems that refuse to generate docs

I recently upgraded to capistrano 2.1, and it's woefully lacking in documentation. Jamis Buck had already picked a documentation coordinator about a month ago, but nothing seemed to be happening since.

So it was time to go dumpster diving in cappy code. I at least wanted to see what the standard variables were. To my surprise, there were some docs in code, but I couldn't generate it with

gem rdoc capistrano

For those of us that had never made a gem, all you have to do to force it to is to edit the associated specification for the gem (/usr/lib/ruby/gems/1.8/specifications/), and add

s.has_rdoc = true

Maybe if I dig enough stuff out of it, I'll pose some prelim documentation for cappy 2.1 and donate it to the documentation effort.

As an aside and musing, ideally, the code itself would be documentation. However, just because you're reading code, doesn't mean that you can get the overall picture of how to use it. Even if you filtered out the details, and saw just the class and method declarations, that still wouldn't be enough since you can't see how things fit together. I don't know what a good solution would be. The simplest API is often complex enough to be nearly useless without good documentation.

Small tip!

Ruby's broken breakpoint workaround

I was messing around with different installations of ruby, and I was aghast when breakpoint stopped working. Having a debugger for imperative programing is one of the fundamental tools in a programmer's tool box. Well, one option is to use the ruby-debug gem, which I have yet to try out.

But I did find that it was because Binding.of_caller() was rewritten (or something) for 1.8.5. In any case, something changed. So if you want a breakpoint and it was broken somehow, try this:

Breakpoint.breakpoint(nil, binding)


How to install Ruby 1.8.5 from source on Ubuntu

Well, it ends up that installing Ruby 1.8.5 and the associated Gems is a pain on Ubuntu. I'm here to take away that pain, yo.

Installing Ruby 1.8.5 from source

First, get the source tarball of 1.8.5 from the ruby lang web page, and put it in /usr/local/src

sudo tar -xvzf ruby-1.8.5-p12
cd ruby-1.8.5-p12
sudo ./configure
sudo make
sudo make install

If all goes well, you're in business. But if it complains about "cannot open crt1.o"
(which is likely on Ubuntu), you'll divine on google that it needs a "glibc-devel-2.3.3-74.i386" package. But I've done the legwork already, and under ubuntu, it's actually called "libc6-dev"

sudo apt-get install libc6-dev

So try making Ruby again. It should be ok. If not, well, it's not documented here, since I didn't run into that problem.

What I did run into was more pain installing Gems.

Installing Ruby Gems from source

Again, go get the source tarball of ruby gems, and put it into /usr/local/src

sudo tar -xvzf rubygems-0.9.1
cd rubygems-0.9.1
sudo ruby setup.rb

Now, if all is well, you're golden. But since this is Ubuntu, it's likely that you're missing zlib. So, some people seemed to have been able to get it to work from using the "zlib-ruby" package. What I had to do was install zlib from source.

Installing Ruby Zlib from source

Get the Ruby Zlib source and again put it into /usr/local/src/

sudo tar -xvzf ruby-zlib-0.6.0
cd ruby-zlib-0.6.0
sudo ruby extconf.rb

If that didn't work, most likely, you got a bunch of stuff that said:

checking for deflateReset() in -lz... no
checking for deflateReset() in -llibz... no
checking for deflateReset() in -lzlib... no

That means that you need the headers for zlib. So install the package "zlib1g-dev"

sudo apt-get install zlib1g-dev

Then try it again. That should work, and once you get zlib installed, you can get gems up and running.