On Saturday, September 25, 2004, 5:28:53 AM, Alexey wrote:

> My Ruby installation is a bit of a mess, especially so far as the
> documentation is concerned. I would like to give it some semblance of
> good order.

> Can someone suggest a nice way to organize and maintain both ri and HTML
> documentation for a Ruby installation, that includes built-in classes,
> standard library, thrd party libraries and a number of RubyGems?

I tend to use 'ri' for built-ins, http://ruby-doc.org/stdlib for the
standard library (local copy of that page, actually), and gem_server
for RubyGems.

'rdocweb' is a RubyForge project I started whose intention is to
generalise the code behind the stdlib site, so you can generate a
similar-looking set of HTML documentation for any set of Ruby
libraries.  But it's low-priority and hasn't gone anywhere.

> Say, you build the above said installation from scratch and want to
> generate documentation for everything - how do you actually do that?
> Where do you run rdoc, with what options, where do you place the output,
> etc?

To discover the answer to that question, you need two things:
 * RDoc knowledge, which can be gained by experimentation; and
 * a strategy, which I don't think has been discussed before, and
   which I attempt below

> And then, when you add/upgrade/delete a library, what do you do in those
> cases?

How do you organise your Ruby libraries, etc?  You could write a
program that visits each source directory, runs RDoc, collects the
results, and puts all the documentation behind a generated index page.
Dump the final results into a nice location, bookmark it, and you're
away.

Then extend it to include gems (I or someone else can help with that
when the time comes).

Whenever you add or remove a library, run the whole lot again.
Remembering some timestamps will help avoid expensive regeneration.

That's your third-party stuff covered.  Tie it in with a local copy of
the core and stdlib stuff, and you'll be smiling.

> I promise to summarize the answers and write a short guideline (assuming
> that I will have something to summarize :).

It may be you can write a generally-useful enough program to cover
everyone's needs.  The 'stdlib-doc' RubyForge project does some of this
stuff.  Feel free to ask about its innards if it seems useful.

Cheers,
Gavin