Rdoc: how to generate rdoc & ri documentation of standard library?

ruby-talk
1

Hi,

how can I generate rdoc & ri documentation of the standard library? I
tried “cd /usr/local/lib/ruby; rdoc”, but had to cancel it because rdoc
tried eating up all my RAM (120MB when I killed it). Is this normal, or
am I doing something wrong?

Andreas

2

If you just let it run in the standard library, it will document
absolutely everything it finds (which is probably not what you want, as
most of the larger library modules have tons of internal classes and
methods which don’t really belong in the documentation). I ran that
here last night, and it took about 15 minutes to complete.

To get something more meaningful, start in the Ruby source tree (not
the installed library) and issue the command

   rdoc --ri *.c lib/*.rb

That will document (in ri form) the built-in functions and all the
direct standard library classes. It’ll take a minute or two, but when
it’s done, you’ll be able to say

ri  Array
ri CGI
ri Tempfile::open

and so on. In fact, on my box, you’ll have at least some kind of
documentation for 325 classes and 2300 methods.

To get standard rdoc documentation in HTML format, run command

 rdoc --op <somedir>  *.c lib/*.rb

If you’re on a Unix box, I recommend using the prettier output:

export LESS="-REX"    # allow escape sequences through
ri -f ansi Array

STANDARD DISCLAIMER:

This is still a work in progress. Many of the library files have not
yet been documented in RDoc format. Some of the constructs in these
files cause RDoc to issue warnings. We’re working on it.

Cheers

Dave

···

On Dec 31, 2003, at 6:11, Andreas Schwarz wrote:

how can I generate rdoc & ri documentation of the standard library? I
tried “cd /usr/local/lib/ruby; rdoc”, but had to cancel it because rdoc
tried eating up all my RAM (120MB when I killed it). Is this normal, or
am I doing something wrong?

3

Dave Thomas wrote:

To get something more meaningful, start in the Ruby source tree (not
the installed library) and issue the command

   rdoc --ri *.c lib/*.rb

That will document (in ri form) the built-in functions and all the
direct standard library classes. It’ll take a minute or two, but when
it’s done, you’ll be able to say

ri  Array
ri CGI
ri Tempfile::open

Ok, thanks. Where do I have to put the ri data to make it available to
all users? I tried “rdoc -o -o /usr/local/share/ri/1.8/system …”, but
rdoc still wrote the data to /root/.ri/.

Maybe it would make sense to add a ri rule to the ruby makefile?

Andreas

4

If I issue the command line above, I get class entries for Array and
Hash (and probably others) that contain no methods. If I amend the
command line to ‘rdoc --ri .c’ (i.e. excluding 'lib/.rb’), the Array
and Hash entries get populated with their methods.

A bug?

Ian

···

On Thu 01 Jan 2004 at 00:00:48 +0900, Dave Thomas wrote:

To get something more meaningful, start in the Ruby source tree (not
the installed library) and issue the command

  rdoc --ri *.c lib/*.rb

That will document (in ri form) the built-in functions and all the
direct standard library classes. It’ll take a minute or two, but when
it’s done, you’ll be able to say

ri Array
ri CGI
ri Tempfile::open

–
Ian Macdonald | Natural laws have no pity.
System Administrator |
ian@caliban.org |
http://www.caliban.org |
>

5

less also runs natively on Windows. The home page is
http://www.greenwoodsoftware.com/less/. I use it along with a port of
groff http://sourceforge.net/projects/gnuwin32/ all the time for
viewing manpages.

Regards,
Randy.

···

On 12/31/2003 10:00 AM, Dave Thomas wrote:

If you’re on a Unix box, I recommend using the prettier output:

export LESS=“-REX” # allow escape sequences through
ri -f ansi Array

6

Ok, thanks. Where do I have to put the ri data to make it available to
all users? I tried "rdoc -o -o /usr/local/share/ri/1.8/system ...", but
rdoc still wrote the data to /root/.ri/.

rdoc --help can be helpfull :slight_smile:

svg% rdoc --help

RDoc V1.0pr1: 2003/12/01 07:12:48 (1.1)

[...]
       --ri-site, -R generate output for use by 'ri.' The files are
                            stored in a site-wide directory, making them accessible
                            to others, so special privileges are needed.

[...]
svg%

Guy Decoux

7

Hmm… Perhaps, but not in RDoc, exactly… The class TSort extends
class Array, but flags it :nodoc: so it doesn’t get documented
internally. tsort should probably have used stopdoc instead.

Cheers

Dave

···

On Dec 31, 2003, at 19:26, Ian Macdonald wrote:

If I issue the command line above, I get class entries for Array and
Hash (and probably others) that contain no methods. If I amend the
command line to ‘rdoc --ri .c’ (i.e. excluding 'lib/.rb’), the Array
and Hash entries get populated with their methods.

A bug?