Re: Rdoc with hyperlinks

On Jul 19, 2006, at 10:35, [email protected] wrote:

Dave H. wrote:

original source code file was.

Dave - I’m a little confused here. RDoc templates

(I assume you mean the actual generated documentation, not the template
files used by RDoc when generating documentation)

always have a link
to the files where the class comes from. However, the “file” pages
have no source code - only any file level RDoc, if there is any. But
RDoc must have the path to those files.

First, RDoc reads the actual source files, and constructs an internal
data structure representing all the stuff it’s going to document.
However, it does not include the path to the source file in the data
structure itself. It does include a fragmentary relative path. Relative
to RDoc at the time it ran, I think. It’s only useful for finding what
subdirectory (if any) that particular source file is in, relative to
the “home” directory for that gem, package, or whatever.

Once the structure is done (it’s parsed all the source files), then it
starts constructing the documentation files. Since the data structure
doesn’t include the full path of the original source file, the
documentation can’t either. Until you apply my modifications.

How would you modify RDoc to, instead of just including file level Rdoc
on file pages,

Huh? What do you mean by “file-level RDoc on file pages?”

RDoc pages do not have any links to the files where the class came
from. They have links to the HTML documentation file that corresponds
to the source file, as you mentioned above.

For example, if you go to Date, there’s a link in the upper right that
says “In: date.rb”. It’s not linked to a file named “date.rb”, it’s
linked to “date_rb.html”. The full path is probably something like

If you’ve installed the modifications I posted, on THAT page there’s a
link named “Source”. And it doesn’t link to an HTML page. It’s going to
be something like file:///usr/local/lib/ruby/1.8/lib/date.rb; that is,
it’s a link to the actual source file itself, not a copy for
documentations’ sake.

include the full, formatted, source of the file (just
like it does for methods)?

I wouldn’t. RDoc normally skips major amounts of the source; it doesn’t
document private methods by default, and the Ruby 1.8.4 source install
has .document files to instruct RDoc to completely ignore the majority
of the code in the standard library. If you need more than just the
method, you’ll probably need to look at a lot more than what RDoc would
normally document anyway. That’s why the code I provided creates links
to the actual production *.rb files, not to *.html files.

[Rather ironically, if you do the usual “./configure; make; make
install” for the standard installation (including documentation) of
Ruby 1.8.4, one of the things that doesn’t get documented is . . .
RDoc. ]

All RDoc does to code is embed it in HTML with some styles. An editor
with code coloring should do the same (on OSX, I use TextWrangler,
although rumor has it I could do even better). Or, if I pull it into
XCode, I can get an index of the classes and methods and leap around
the file by pulling them off the pop-down list.

I don’t know what your browser does when it gets a
file:///…filename.rb URL. Mine (Safari) opens a Finder window with
the file highlighted, ready to double-click open into an editor. I
suspect Firefox would simply display it in a browser window as it would
a text file, until/unless I changed the association. Perhaps you can
teach your browser to open the file in a Ruby syntax-aware editor?