Question on organizing local RDoc documentation

ruby-talk
1

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?

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?

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

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

Alex

2

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

3

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, RDoc Documentation 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

···

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

4

Alexy:

Let's start with the 'ri' side of things.

As you're installing from source, then you can arrange for the ri documentation for everything in the standard Ruby distribution to be generated at the time you build Ruby. There's some variance here, because the default of whether or not to generate this documentation changed between version of Ruby. So, in your Ruby source tree, you'd do a standard

   ./configure
   make
   make install

If you don't see that generating the ri documentation at the end, add one more step

   make install-doc

Then there's the libraries. If you use Gems, then I believe the latest will automatically manage installing the ri documentation. If you use rpa, I think it comes with a hacked version of ri that does the same thing.

For libraries that you install manually, you can add ri documentation to your local tree using

    rdoc --ri <filelist>
or
   rdoc --ri-site <filelist>

The first form installs the documentation for your personal use, the second installs them site wide.

When it comes to HTML documentation, the story is slightly different. ri keeps its documentation in a kind of database format. This allows me to add to it incrementally. For example, if a newly installed library adds a method to the String class, I can add that method in, and the next time you ask ri for a list of String's methods, that new method will appear.

I can't easily do that with the HTML versions of the documentation. As a result, its hard to maintain a merged set of HTML documentation for things that you add over time.

I'm thinking of a fix to this, which would involve generating a site HTML documentation tree from the ri database. This would give you what you want (I believe). Until then, I'd stick with ri for unified documentation and use RDoc for documentating individual modules.

Cheers

Dave

···

On Sep 24, 2004, at 15:28, Alexey Verkhovsky wrote:

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?

5

Unfortunately, Gems still doesn't do ri. Dave, Mauricio and I started
discussing how best to do ri generation for separate package managers,
but we have yet to come to a great conclusion. (Yes, I realize I'm
replying to Dave in the 3rd person ;).

We had ri generation in temporarily but took it out for 0.8.1. We'll
include it in the next release.

Chad

···

On Sun, 26 Sep 2004 01:54:29 +0900, Dave Thomas <dave@pragprog.com> wrote:

Then there's the libraries. If you use Gems, then I believe the latest
will automatically manage installing the ri documentation. If you use
rpa, I think it comes with a hacked version of ri that does the same
thing.

6

I think this has been disabled in RubyGems 0.8.x.
The ri distributed by RPA as ri-rpa was patched to allow RI documentation
to be removed on uninstall easily. It also includes pre-generated ri
documentation (so that one doesn't have to download Ruby's sources and
generate them manually).

···

On Sun, Sep 26, 2004 at 01:54:29AM +0900, Dave Thomas wrote:

If you don't see that generating the ri documentation at the end, add
one more step

  make install-doc

Then there's the libraries. If you use Gems, then I believe the latest
will automatically manage installing the ri documentation. If you use
rpa, I think it comes with a hacked version of ri that does the same
thing.

--
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com