From: Dave Howell <groups@...>
Date: 2006-05-10T09:34:45+09:00
Subject: Re: Ruby documentation discovery


On May 9, 2006, at 16:23, John Conrad wrote:

> Here's the gist of it: I'm not aware of a good, solid, universal 
> method for
> discovering the documentation of various libraries, classes, and 
> methods in
> Ruby.

> I love ri, when it knows about what I'm asking it, but too often it is
> unaware of the class or method I'm referring to. I think gem_server is
> nifty, but I prefer ri in most cases because it takes a specific 
> argument
> rather than making me browse through web pages with my mouse.

Huh. I got so tired of trying to play "guess the spelling and 
capitalization" with ri, along with the bonus "oh, did rdoc even get 
run for that?", that I wiped the entire directory. I vastly prefer 
being able to scroll through an HTML list, and use hyperlinks. 
Hyperlinks! Bliss! And multiple windows to compare, say, Process and 
Thread, or have Enumerate open along with String! Yay!

Unfortunately, RDoc has quite poor support for HTML. It overwrites 
existing files, so to update, you have to re-run it from scratch on 
*everything.* That takes *hours*.

Fortunately, I have Ruby. I wrote a program (RDC) that generates HTML 
documentation via Rdoc for, well, whatever it can find. Gems mostly 
arrived with HTML documentation already built for them. RDC doesn't 
regenerate existing documentation. It checks the Ruby core, the gem 
dir, and the site dir. Each component gets its documentation stored in 
its own subtree, following the gem structure, more or less. Then RDC 
builds (or rebuilds, as needed) a master index page that links to all 
the other documents, thus providing the critical missing "Home Page" 
for Ruby HTML documentation.

A search function would be nice, but that'd involve actually having a 
mini-web server or something running, instead of just the static file 
structure I have now. This has been working for me more than well 
enough to not provoke further tinkering. Which means it's working very 
well indeed. :)

I just have to remember to run it after installing something new.