This is how you define the HTML that RDoc generates. Simply create a file in rdoc/generators/html_templates that creates the module RDoc::Page and populate it as described below. Then invoke rdoc using the –template <name of your file> option, and your template will be used.
The constants defining pages use a simple templating system:
The templating system is passed a hash. Keys in the hash correspond to tags on this page. The tag %abc% is looked up in the hash, and is replaced by the corresponding hash value.
Some tags are optional. You can detect this using IF/ENDIF
IF: title The value of title is %title% ENDIF: title
Some entries in the hash have values that are arrays, where each entry in the array is itself a hash. These are used to generate lists using the START: construct. For example, given a hash containing
{ 'people' => [ { 'name' => 'Fred', 'age' => '12' }, { 'name' => 'Mary', 'age' => '21' } ]
You could generate a simple table using
<table> START:people <tr><td>%name%<td>%age%</tr> END:people </table>
These lists can be nested to an arbitrary depth
the construct HREF:url:name: generates <a
href=“%url%”>%name%</a> if url
is defined in the
hash, or %name% otherwise.
Your file must contain the following constants
a list of fonts to be used
a CSS section (without the <style> or comments). This is used to generate a style.css file
The main body of all non-index RDoc pages. BODY will contain two !INCLUDE!s. The first is used to include a document-type specific header (FILE_PAGE or CLASS_PAGE). The second include is for the method list (METHOD_LIST). THe body is passed:
the page's title
the url of a style sheet for this page
the optional URL of a diagram for this page
a (potentially multi-paragraph) string containing the description for th file/class/module.
an optional list of %aref%/%name% pairs, one for each module required by this file.
an optional list of %aref%/%name%, one for each method documented on this page. This is intended to be an index.
An optional list. For each attribute it contains:
the attribute name
r/o, w/o, or r/w
description of the attribute
An optional string containing an already-formatted list of classes and modules documented in this file
For FILE_PAGE entries, the body will be passed
The name of the file
The full path to the file
The date/time the file was last changed
For class and module pages, the body will be passed
The name of the class or module
A list. For each file this class is defined in, it contains:
an (optional) URL of the RDoc page for this file
the name of the file
The (optional) URL of the RDoc page documenting this class's parent class
The name of this class's parent.
For both files and classes, the body is passed the following information on includes and methods:
Optional list of included modules. For each, it receives
optional URL to RDoc page for the module
the name of the module
Optional list of methods of a particular class and category.
Each method list entry contains:
public/private/protected
instance/class
a list of method descriptions
Each method description contains:
a target aref, used when referencing this method description. You should code this as <a name=“%aref%”>
the optional URL to the page containing this method's source code.
the method's name
the method's parameters
a full calling sequence
the (potentially multi-paragraph) description of this method.
Header for pages documenting classes and modules. See BODY above for the available parameters.
Header for pages documenting files. See BODY above for the available parameters.
Controls the display of the listing of methods. See BODY for parameters.
The top-level index page. For a browser-like environment define a frame set that includes the file, class, and method indices. Passed
title of page
url of initial page to display
Individual files for the three indexes. Passed:
URL of main index page
List of
name of an index entry
url of corresponding page
Same as CLASS_INDEX for methods
Same as CLASS_INDEX for methods
A wrapper around CLASS_INDEX, METHOD_INDEX, and FILE_INDEX. If those index strings contain the complete HTML for the output, then FR_INDEX_BODY can simply be !INCLUDE!
Page used to display source code. Passed %title% and %code%, the latter being a multi-line string of code.
and a blank page to use as a target
B O D Y T E M P L A T E
C L A S S P A G E H E A D E R T E M P L A T E
The following is used for the -1 option
C O N T E X T C O N T E N T T E M P L A T E
F I L E P A G E H E A D E R T E M P L A T E
F O O T E R T E M P L A T E
Index ################################
M E T H O D L I S T T E M P L A T E
Source code ##########################
H E A D E R T E M P L A T E