Get Sinatra, Rubygems, and Passenger working for offline RDocs? Count me in. I saw this and new I had to have it. I’ve been on some long plane rides recently and I frequently find myself wanting to look up something from a gem’s documentation while I’m coding. You can use the gem server command but that’s just such a pain to do every time you want to look something up. I hadn’t really given it much thought that there might be an easier way until I saw Jesse’s tweet about it. Having this offline using passenger at http://gems.local is great but I wanted to have a little more searching baked in. Here’s how I did it:
- Install the hanna gem from mislav.
You may need to have the HAML gem installed for this to work. The hanna gem is a great theme for rdoc output. It includes javascript to make some ajaxy type search so you can filter methods by typing in to a text field in one of the frames on the left. It took me a little while to find this theme. It’s the one currently in use on GitRDoc, which is a great resource (if you’re online).
- Tell rdoc to use the hanna theme
In order to tell rdoc and gem to use this when you use the "gem" command, you need to add to your .gemrc. Beware that this will affect all future rdoc generation when you install a gem. Add the following to ~/.gemrc:
- Regenerate your rdocs
You then need to regenerate all of your rdocs with this theme. You can do this by executing the following:
- Get sinatra-rubygems
Clone my fork of Jesse Newland’s sinatra-rubygems from GitHub:
git clone git://github.com/jseifer/sinatra-rubygems.git
- Add it to Passenger
Hook it up to your passenger preference pane and set the name to "gems.local", restart Apache and you’ll be all set:
After you complete the above steps, everything should be working. Enjoy! This will come in handy next time you don’t have internet access and need to look up some methods. I’d like to give a special thanks to Jesse Newland for releasing the sinatra-rubygems app.
Update: k776 points out in the comments that this doesn’t work on the latest version of rdoc, which is 2.4.1 as of this writing. It seems 2.3.0 is the version to go with.
Delicious 
Digg This Post 
Facebook 
Reddit This Post
No related posts.
Thanks for your article, it works great.
You have a typo in the first gist, it's “sudo gem install mislav-hanna” without an h at the end.
Also note that regenerating rdocs might take a long time, depending on how many gems you have installed.
Thanks a lot and good catch, I updated the command.
Good stuff. I wrote something similar, but working with a static html frameset and a Ruby script that will create it from the local gems installation. No need for sinatra, passenger or any other running servers. Just plain old HTML files on your machine: http://blog.olszowka.de/2009/02/13/rdoc-index-f...
Nice gemrc tip. For opening a gem's docs I just autocomplete any gem from my shell using my completion gem, http://github.com/cldwalker/dotfiles/tree/master. Setting up your own gem completion is as simple as having your gem's rdoc paths defined in a yaml: http://github.com/cldwalker/dotfiles/blob/maste....
Forgive my ignorance. I'm following the article and when it comes to rebuilding rdocs, I'm seeing
invalid argument: –format=html
I ran rdoc –help, and from the looks of it, html is not a valid format.
-f, –fmt, –format=FORMAT Set the output formatter. One of:
darkfish
ri
Any ideas?
Did you install the hanna gem from above? That's the first thing that I think I can think of that would cause that.
I did, yes. It installed fine too. I'm thinking maybe faulty rdoc install. Grabbing html markup file from rdoc CVS to see how that goes.
It might be a path issue also. Where is everything installed and is it in your path?
/opt/ruby-enterprise-1.8.6-20090201/ and it is in my path, sudo's path, and root users path. All gems are in /opt/ruby-enterprise-1.8.6-20090201/lib/ruby/gems/1.8 . No gems in ~/.gem (I install system wide). Tried uninstall rdoc and hanna, then reinstalling. No luck. Still only giving me ri and darkfish.
No luck with CVS. Even using the ones that are installed doesn't work.
$ sudo gem rdoc –all –no-ri –format=darkfish
ERROR: While executing gem … (OptionParser::InvalidOption)
invalid option: –format=darkfish
$ sudo gem rdoc –all –no-ri –format=ri
ERROR: While executing gem … (OptionParser::InvalidOption)
invalid option: –format=ri
If those work for you, then something is swewd with my setup @_@
It would appear the new Rdoc 2.4.1 doesn't have html format, doesn't support inline source, doesn't support hanna template, and fails on some gems because of opname/op-name. I've downgraded to 2.3.0 and it's working again. Thanks for the article.
Thanks a lot for this info. I've updated the post.
I had the same issues as k776, as I was on rdoc 2.4.1 as well.
Note1: –inline-source is deprecated as of 2.4.0
Note2: I used 'rdoc: –line-numbers –format=darkfish' in my .gemrc with no problems. Sorry, I just like darkfish better than hanna.
Great idea Jason.
Hey, thanks a lot. I like the layout of the darkfish template a lot but I couldn't find a way to search by the method names. I'm also not sure how the gem name dropdown looks with that template (or if it even works).
@Jason,
Well, I have to retreat on my previous comment, it crapped out after about 6 gems with the “–inline-source will be removed from RDoc on or after August 2009″ warning, even when not using hanna.
So it looks like it's back to rdoc 2.3.0.
You are right that DarkFish is missing the searchable methods and the dropdown is missing completely. Looks like it forkin' time.
Actually, I like RailsBrain.com docs about the best. Complete navigation via keyboard. Now, how do we get RailsBrain/DarkFish/hanna into the pot for a little rdoc-template stew.
Check out Bdoc. It's off-line (really off-line) Rdocs => http://github.com/manalang/bdoc/tree/master
Jason,
Thank you very much. I really needed the local documentation and find all the steps ready here :)
does it work with 2.4.3?
It doesn't indeed [hanna doesn't]
Also note here's a bdoc that has links to external url's, too: http://github.com/rogerdpack/bdoc/tree/master
It doesn't indeed [hanna doesn't]
Also note here's a bdoc that has links to external url's, too: http://github.com/rogerdpack/bdoc/tree/master
Do you still accomplish this the same way you did back in Feb 09?
WHAT!
Yep, although I've since stayed on the version of rdoc that's supported by hanna since I like that hanna template much more.
I found that I had to specify –overwrite to regenerate all rdocs.
gem rdoc –all –overwrite