Ruby Programming/RubyDoc

The standard Ruby library provides a tool for generating documentation from self documenting code called RubyDoc or RDoc for short. Though it's part of the standard library, RDoc isn't a file you require to use. Instead it consists of a command-line program called rdoc and a library for parsing specially-formatted comments out of Ruby and C code.

A Simple Example
Here are the contents of the file simpleNumber.rb which contains a class SimpleNumber


 * 1) This file is called simpleNumber.rb
 * 2) It contains the class SimpleNumber

class SimpleNumber

def initialize( num ) raise if !num.is_a?(Numeric) @x = num end

def add( y ) @x + y end

def multiply( y ) @x * y end

end

Just to get going, run rdoc on this file

>> rdoc simpleNumber.rb

simpleNumber.rb: c... Generating HTML...

Files:  1 Classes: 1 Modules: 0 Methods: 3 Elapsed: 0.426s

A quick look around reveals rdoc has created a new directory called doc/. It contains quite a few files (given such a simple class!)

>> ls doc/ classes     files                fr_file_index.html    index.html created.rid fr_class_index.html  fr_method_index.html  rdoc-style.css

Open the file doc/index.html in a web browser and find



What has RDoc done? First, it has scanned the given file (shown in the upper left pane). The middle pane lists all of the classes in <tt>simpleNumber.rb</tt>, and the right panel gives all of the methods in SimpleNumber. In this case the lower panel is showing the summary information for the file <tt>simpleNumber.rb</tt> which has been extracted from the top-level comment in the file. Once we select either a class or a function it will show more particular information.

Handling Multiple Files
Any directories included on the command line will be searched for Ruby files (with an <tt>.rb</tt> or <tt>.rbw</tt> extension) and C files (with a <tt>.c</tt> extension). rdoc will search recursively, which makes it convenient for documenting large trees of code. If no source files are specified, RubyDoc will start searching with the current directory. The output is always generated in a directory <tt>doc/</tt> under the current location.

Any files which aren't recognized as Ruby or C are not parsed by default, but can be included as command-line arguments to rdoc. In this case they are treated as SimpleMarkup (see below) -- generally speaking they will just be browsable as plain text files in the HTML documention.

Formatting for RDoc
RDoc uses a formatting system called SimpleMarkup for its markup purposes. SimpleMarkup is a simplified text-based markup system, much like many wiki markup languages. Here's a brief overview:


 * Consecutive lines aligned on the left margin (either column 0 in a text file, or after the comment character and whitespace in a source file) are considered a paragraph. An empty line starts a new paragraph.
 * If a line starts with "*", "-" or " " the following information is a list item, either unnumbered or numbered. All subsequent lines should be indented to match the text on the first line of the list item.  Here's an example (from the RDoc documentation):

the first item. This is the first paragraph.
 * this is a list with three paragraphs in

And this is the second paragraph.

1. This is an indented, numbered list. 2. This is the second item in that list

This is the third conventional paragraph in the first list item.


 * This is the second item in the original list

[cat] a small furry mammal that seems to sleep a lot
 * The lists can be labeled. Each label must be inside square brackets or followed by two colons:

[ant] a little insect that is known to enjoy picnics

cat:: a small furry mammal that seems to sleep a lot

ant:: a little insect that is known to enjoy picnics


 * Any line which starts to the right of the current left margin is considered verbatim text (like program code, for example)
 * Any line starting with one or more equals signs is a heading. One equals sign is a top-level header, two equals signs is a second-level heading, etc.
 * Three or more dashes on a line give a horizontal line.
 * Basic text markup:
 * Tags can be used, including asterisks for *bold text*, underscores for _emphasis_ text, and plus signs for <tt>+code+</tt> text.
 * Alternately, HTML tags can be used.

linking to other methods
To link to other methods format them like ri, ex:


 * 1) same as the #read method of the

You can avoid having a link created like \#method_name (won't be linked) and \Win32 for camelcase that shouldn't be linked to known classnames.

linking to a url
Here's an example:
 * 1) For detail, see the msdn.

Including Diagrams
If the program <tt>dot</tt> from the Graphviz is available, RDoc will generate class hierarchy diagrams as part of the HTML documentation. This behavior can be enabled with the command line option <tt>--diagram</tt> or <tt>-d</tt>.

Using RDoc to Generate Usage Output
Warning : This feature is only available in Ruby 1.8.X; Support for this feature has been dropped as of Rdoc for Ruby 1.9.X.

RDoc can be used to generate a command-line usage string (paragraph) from a file's comments. This is done with the class method <tt>RDoc::usage</tt>. Here's an example:


 * 1) TestRDocUsage: A useless file
 * 2)  Usage:  ruby testRDocUsage.rb  [options]
 * 1)  Usage:  ruby testRDocUsage.rb  [options]

require 'rdoc/usage'

RDoc::usage

Which when run:

>> ruby testRdocUsage.rb TestRDocUsage: A useless file

Usage: ruby testRDocUsage.rb  [options]

Not particularly interesting. <tt>RDoc::usage</tt> can take two kinds of command line options. If the first argument is an integer, this value is used as the exit code for the application (yes, <tt>RDoc::usage</tt> terminates the application). Any further (string) arguments call out sections of the introductory comment which should be used. Here's a slightly more complicated version of the above example:


 * 1) = Overview
 * 2) TestRDocUsage: A useless file
 * 3) = Usage
 * 4)  Usage:  ruby testRDocUsage.rb  [options]
 * 1)  Usage:  ruby testRDocUsage.rb  [options]
 * 1)  Usage:  ruby testRDocUsage.rb  [options]

require 'rdoc/usage'

RDoc::usage('Usage')

This time with section headers. Running the script gives

>> ruby testRdocUsage.rb

USAGE

=
Usage: ruby testRDocUsage.rb  [options]

Where only the 'Usage' section (called out as an argument to <tt>RDoc::usage</tt>) is included.

Other Interesting Command-Line Options
Here are a selection of other interesting rdoc command-line options which haven't been covered above:


 * -a, --all : Parse all class methods, not just public methods.
 * -x, --exclude pattern : Exclude files/directories matching pattern from search. Files included explicitly on the command line are never excluded.

Questions

 * How do you include an external image file when publishing RDoc inside a Gem? RDoc keeps converting the image into html!