So you've written a masterpiece, a class in a class of its own, and you'd like to share it with the world. But, being a responsible developer, you feel the need to document your creation. What do you do? The simplest solution is to use Ruby's built-in documentation format, RD, and rdtool
, a Ruby utility suite that converts this documentation into a variety of output formats.
rdtool
scans a file for =begin
and =end
pairs, and extracts the text between them all. This text is assumed to be documentation in RD format. The text is then processed according to a simple set of rules:
= Top Level Heading
== Second Level Heading
...
This is normal text
* start of a
multiline bullet item
* and another
* nested item
* second nested
* third item at top level
(1) A numbered item
* subitem in a bulleted list
* subitem
(2) Second numbered item
(9) This will actually be labeled '3.'
: red
when the light is red, you
must stop
: amber
the amber light means that things are about to change. Either:
* step on the gas, or
* slam on the brakes
: green
green means GO
Indented text that isn't part of a list is set verbatim (such as the stuff under “Synopsis” in Figures A.1 and A.2).
Within blocks of text and headings, you can use special inline sequences to control text formatting. All sequences are nested within a set of double parentheses.
Sequence | Example | Intended Use |
---|---|---|
((*emphasis*)) | emphasis | Emphasis (normally italic) |
(({code stuff})) | code stuff |
Code |
((|variable|)) | variable | Variable name |
((%type me%)) | type me |
Keyboard input |
((:index term:)) | index term | Something to be indexed |
((<reference>)) | reference | Hyperlink reference |
((-footnote-)) | text.4 | Footnote text. A reference is placed inline, and the text of the footnote appears at the bottom of the page. |
(('verb')) | verb | Verbatim text |
The content of headings, the labels of labeled lists, and the names of methods are automatically made into potential cross reference targets. You make links to these targets from elsewhere in the document by citing their contents in the ((<...>))
construct.
= Synopsis
...
See ((<Return Codes>)) for details.
..
== Instance Methods
— Tempfile.open( filename )
Opens the file...
== Return Codes
..
The method ((<Tempfile.open>)) raises an (({IOException}))...
If a reference starts with “URL:”, rdtool
attempts to format it as an external hyperlink.
The reference ((<display part|label>))
generates a link to label
but places the text “display part” in the output document. This is used in the description section of the example in Figure A.1 to generate references to the method names:
perspective, apart from the unusual ((<(({new}))|Tempfile.new>)),
...
This construct displays the word “new” in code font but uses it as a hyperlink to the method Tempfile.new
.
rdtool
makes certain assumptions about the format of method names. Class or module methods should appear as Class.method
, instance methods as Class#method
, and class or module constants as Class::Const
.
— Tempfile::IOWRITE
Open the file write-only.
...
— Tempfile.new( filename )
Constructs a temporary file in the given directory. The file
...
— Tempfile#open
Reopens ((|aTempfile|)) using mode “r+”, which allows reading
..
The contents of filename will be inserted wherever the document contains
<<< filename
If the file is specified with an .rd
or .rb
extension, it will be interpreted as RD documentation.
If the filename has no extension, rdtool
will look for a file with an extension that matches the type of output being produced (.html
for HTML files, .man
for man files, and so on) and interpolate that file's contents in the output
stream. Thus, a line such as:
<<< header
could be used to add an output-dependent header to a document.
RD documentation can be included directly in a Ruby source program or written into a separate file (which by convention will have the extension .rd
). These files are processed using the rd2
command to produce appropriately formatted output.
rd2 [options] inputfile [>outputfile]
Some common options include:
-r format |
Select an output format. -rrd/rd2html-lib.rb produces HTML output (the default). -rrd/rd2man-lib.rb produces Unix man page output. |
-o name |
Set the base part of the output filename. |
--help |
List the full set of options. |
As we are writingthis, RD and rdtool
are undergoing continuous development. It is likely that some of the details we give here will be out of date (or just plain wrong) by the time you read this.
Included with therdtool
distribution is the file README.rd
. We suggest you do so, as it will give you the current scoop on producing Ruby documentation.
Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2001 by Addison Wesley Longman, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/).
Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.
Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.