Creating documetation with RDoc

Chris Fullmer

I think typing "ruby" brings up a command line interpreter. Try typing a simple ruby command, see what it returns.

Once ruby is installed, you can then run rDoc on your plugins folder and it will export a a nice html package of all plugins, their methods, and any rDoc info the author has embedded. Most of my scripts are lightly rDoc compatible, based on the template Rick created a while ago. But I have not documented all my methods very well inside of the script.

But if we were serious about using rDoc I would document my scripts better to be more compatible.

Chris

thomthom

I finally worked it out. I was confusing running the command in the command-line with the IRB.

Only problem now is that I can't get Ubuntu to read my Windows7 shard folders. (I couldn't get this to work with Vista either...)

@chris fullmer said:

Most of my scripts are lightly rDoc compatible, based on the template Rick created a while ago. But I have not documented all my methods very well inside of the script.

What's not compatible? Doesn't it just extract the comments right above classes and methods?

thomthom

If I install Ruby 1.8.6 with the one-click installer - will that affect SU's ruby? Or will it leave it alone?

Chris Fullmer

It should leave it alone. I have had no known conflicts anyhow.

And yes, rDoc does just take the line above each class and method, but I have not taken the time to put that line in there. That is what I was thinking of. I would go through and do that if people were interested in using rDoc.

I was thinking it might be worth looking into for CityGen

thomthom

Yea, I'll start using it as well.

I'm currently writing a Unicode module, where I feel the need to documenting is very strong.
For these collaboration project I think we should agree on a formatting standard.

What I wrote up as a test for one of my methods are:


# = +FileSystem;;normalize_file_name(_file_name_)+ =
#
# == Description ==
# Normalizes the given _+file_name+_ string into Window's style of representing file names.
#
# == Return Values ==
# _String_ with all forward slashes converted to backward slashes.
#
# == Arguments ==
# +file_name+ UTF-8 +String+

I've yet to see how it looks like though. I'm going to install Ruby Standalone now and see if I can generate some test docs.

thomthom

uuhh.... I just got it working, and my first attempt did not look good. A different formatting is required.

thomthom

I've run into an issue.

Then I first pass a folder to rdoc it processes all files. But when I make modification to one of the files and run rdoc again it only processes the changed one. The HTML docs I get then only lists the content of that last changed file. The rest of the previously processed files isn't listed.
They aren't processed until I make changes to them. If I try to force process one of the unchanged files it says there's no newer version.

Some kind of bug?

thomthom

Is there any way of hosting the generated files on the Google Code project site?

thomthom

Hey, this documentation look much nicer than the default RDoc output. And from a web-developers standpoint it makes me happy that it doesn't use the ugly frames either. http://rdoc.rubyforge.org/RDoc/DOT/Node.html

Apparently made by this generater: http://deveiate.org/projects/Darkfish-Rdoc/ <- me wants to use this!

Jim

darkfish is the default output for the latest version of rdoc.

There are a few others. I like allison, but have not been able to make it work.

rdoc creates a lot of files, so there is no easy way to use them on google code. Ideally if you use google code would be to get rdoc to output in the google code wiki format.

thomthom

How do you install the latest RDoc on Windows?
I'm confused...

I see references to chm htere, it now makes .chm help files as well?

thomthom

Ah. I finally figured out what that gem thing was. Everything is working fine now.
Pretty docs.