Help with rdoc - generate documentation for Ruby 1.9.1 StandardLibrary?

[Bjoern]

Hi,

since it isn't available online anywhere (afaik), I tried to generate
the documentation for the standard library myself. However, I have
troubles with rdoc.

What I tried was

rdoc -i lib -i ext -o rdoc_dir

in the ruby 1.9.1 source folder. However, in the output there is no
reference to json, which as far as I know is part of the stdlib. There
also is a json directory in ext.

What would the correct rdoc command be, and what directories should be
included (I think lib and ext, some more?).

If it works in the end I hope I can put it on the web somewhere.

Thanks!

Björn

 

[Bjoern]

Found my mistake - should habe run rdoc on the installed ruby, not the
source folder. Also I left out the -i options.

Still not sure what directories should be included for stdlib, and
what for core - is there even a difference?

 

[Roger Pack]

Found my mistake - should habe run rdoc on the installed ruby, not the
source folder. Also I left out the -i options.

Did it get the Gem class and such? I've been having some trouble
running rdoc against the core, too.

Still not sure what directories should be included for stdlib, and
what for core - is there even a difference?

I'm not sure either, though the extensions are probably stdlib.
=r

 

[Bjoern]

Did it get the Gem class and such?  I've been having some trouble
running rdoc against the core, too.

Yes it seems to have the Gem class.

I just ran it again with template kilmer and I realize it is not quite
perfect yet. For example index.html starts with the File class. I
guess something more telling would be nice.

Any idea what template http://www.ruby-doc.org/stdlib/ uses? The
sidebar is quite nice.

Björn

 

[Bjoern]

I have now tried to use the horo template from rails, but without
success. I have simpley copied the horo.rb file from rails to rdoc/
generate/html and tried the -T horo.rb option.

However, it results in an undefined constant error.

Has anybody succeeded in generating the stdlib with a nice template?

 

[Eric Hodel]

Found my mistake - should habe run rdoc on the installed ruby, not the
source folder.

That's wrong. You need to run rdoc against the source, and you should
run it like:

/path/to/rdoc_from_19 . -o /path/to/output

 

[Eric Hodel]

However, in the output there is no reference to json, which as far
as I know is part of the stdlib. There also is a json directory in
ext.

Looks like ext/.document wasn't updated for 1.9.1.

 

[Bjoern]

Looks like ext/.document wasn't updated for 1.9.1.

That would explain a lot, thanks!

Also James from ruby-doc explained to me another issue with rdoc not
handling re-openings of classes well (such as YAML adding methods to
String if YAML is required). Any workarounds for that?

What can I do to understand all this better? For example I still don't
know which files are STDLIB and which files belong to Core.

Björn

 

[Roger Pack]

Looks like ext/.document wasn't updated for 1.9.1.

Nice I hadn't noticed those before for some reason [adding a mention to
the rdoc rdoc's about it would be great]. Maybe that's the reason my
core rdoc's always seem a little sparse.

What can I do to understand all this better? For example I still don't
know which files are STDLIB and which files belong to Core.

I think core as trunk/*.c
and stdlib as lib/* + ext/*

Something like that anyway

=r

 

[Eric Hodel]

Also James from ruby-doc explained to me another issue with rdoc not
handling re-openings of classes well (such as YAML adding methods to
String if YAML is required). Any workarounds for that?

RDoc itself handles this just fine, but sometimes the files themselves
disable RDoc. For example:

class String # :nodoc:
def my_string_extension
end
end

The nodoc directive is global to the String class, never do this!

This is correct:

class String

# :stopdoc:
def my_string_extension
end
# :startdoc:

end

 

[James Britt]

RDoc itself handles this just fine,

Depends on what is meant by "fine."

Here's the rdoc behavior for 1.8.6: Running rdoc over the entire ruby
source tree gives you docs that claim String and Array, for example,
have a method named 'to_yaml', because the yaml code reopens those
classes. But rdoc pages do not indicate where that comes from, or under
what circumstances it exists.




--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.neurogami.com - Smart application development

 

[Ryan Davis]

Nice I hadn't noticed those before for some reason [adding a mention
to
the rdoc rdoc's about it would be great]. Maybe that's the reason my
core rdoc's always seem a little sparse.

You mean something like this?

DOT_DOC_FILENAME = ".document"
Name of the dotfile that contains the description of files to
be processed in the current directory

 

[Roger Pack]

You mean something like this?

DOT_DOC_FILENAME = ".document"
Name of the dotfile that contains the description of files to
be processed in the current directory

Yeah that's the one.
=r

 

[Ryan Davis]

Yeah that's the one.

Ah... I see... then why'd you ask for it when it is already there?

 

[Roger Pack]

Ah... I see... then why'd you ask for it when it is already there?

Because I didn't see it the first time I looked through the docs.
More prominent would be nice [i.e. in the MAIN file].

Thanks much.

=r