Alexey Verkhovsky 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?


Good question.  My understanding is that gem docs are stored separate
from any other docs; the gem doc server seems to only know about
installed gems, not core or std-lib docs.


> 
> 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?

Well, I believe that the current configure script does not install docs
by default.  You may need to do this:

  ./configure --enable-install-doc

I think, though, that this only docs the core classes, e.g., Array and
String, but not REXML or anything for which you  need to use 'require'.
  (But even this is not quite true, as doing this gets you ri info for
YAML, but not for REXML, though both are technically in the std-lib.)

So you should have at least all of the core classes, and then some small
number of standard lib classes.


You can also cd to the installed Ruby /lib directory and run rdoc there:
  cd path/to/lib
  rdoc --system

Which will install ri files.

I think simply running rdoc in the lib directory will generate the html
files.

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

If it's a gem, then using 'gem uninstall' should remove the docs for the
specified gem.  But if you installed the code using cp or install.rb or
the like then you may need to manually remove the docs (including
tracking down the ri *.yaml files if they were generated).

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


That would be much appreciated, as would any comments, corrections, and
suggestions on rdoc/ri best practices.

(On a side note, I tried Google to find pages that discussed RDoc, and
found countless pages *generated* by rdoc, as the default page title is,
or was,  "RDoc Documentation."  Which makes finding actual RDoc
documentation a bit harder.)


James