Extended maintenance of Ruby versions 1.8.7 and 1.9.2 ended on July 31, 2014. Read more

In Files

  • rdoc/generators/template/chm/chm.rb
  • rdoc/generators/template/html/hefss.rb
  • rdoc/generators/template/html/html.rb
  • rdoc/generators/template/html/kilmer.rb
  • rdoc/generators/template/html/old_html.rb
  • rdoc/generators/template/html/one_page_html.rb
  • rdoc/generators/template/xml/rdf.rb
  • rdoc/generators/template/xml/xml.rb
  • rdoc/generators/xml_generator.rb

Files

Class/Module Index [+]

Quicksearch

RDoc::Page

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

FONTS

a list of fonts to be used

STYLE

a CSS section (without the <style> or comments). This is used to generate a style.css file

BODY

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:

%title%

the page’s title

%style_url%

the url of a style sheet for this page

%diagram%

the optional URL of a diagram for this page

%description%

a (potentially multi-paragraph) string containing the description for th file/class/module.

%requires%

an optional list of %aref%/%name% pairs, one for each module required by this file.

%methods%

an optional list of %aref%/%name%, one for each method documented on this page. This is intended to be an index.

%attributes%

An optional list. For each attribute it contains:

%name%

the attribute name

%rw%

r/o, w/o, or r/w

%a_desc%

description of the attribute

%classlist%

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

%short_name%

The name of the file

%full_path%

The full path to the file

%dtm_modified%

The date/time the file was last changed

For class and module pages, the body will be passed

%classmod%

The name of the class or module

%files%

A list. For each file this class is defined in, it contains:

%full_path_url%

an (optional) URL of the RDoc page for this file

%full_path%

the name of the file

%par_url%

The (optional) URL of the RDoc page documenting this class’s parent class

%parent%

The name of this class’s parent.

For both files and classes, the body is passed the following information on includes and methods:

%includes%

Optional list of included modules. For each, it receives

%aref%

optional URL to RDoc page for the module

%name%

the name of the module

%method_list%

Optional list of methods of a particular class and category.

Each method list entry contains:

%type%

public/private/protected

%category%

instance/class

%methods%

a list of method descriptions

Each method description contains:

%aref%

a target aref, used when referencing this method description. You should code this as <a name=“%aref%”>

%codeurl%

the optional URL to the page containing this method’s source code.

%name%

the method’s name

%params%

the method’s parameters

%callseq%

a full calling sequence

%m_desc%

the (potentially multi-paragraph) description of this method.

CLASS_PAGE

Header for pages documenting classes and modules. See BODY above for the available parameters.

FILE_PAGE

Header for pages documenting files. See BODY above for the available parameters.

METHOD_LIST

Controls the display of the listing of methods. See BODY for parameters.

INDEX

The top-level index page. For a browser-like environment define a frame set that includes the file, class, and method indices. Passed

%title%

title of page

%initial_page%

url of initial page to display

CLASS_INDEX

Individual files for the three indexes. Passed:

%index_url%

URL of main index page

%entries%

List of

%name%

name of an index entry

%href%

url of corresponding page

METHOD_INDEX

Same as CLASS_INDEX for methods

FILE_INDEX

Same as CLASS_INDEX for methods

FR_INDEX_BODY

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!

SRC_PAGE

Page used to display source code. Passed %title% and %code%, the latter being a multi-line string of code.

Constants

BLANK

and a blank page to use as a target

BODY

B O D Y T E M P L A T E

CHM_INDEX
CLASS_INDEX
CLASS_PAGE

C L A S S P A G E H E A D E R T E M P L A T E

CONTENTS
CONTENTS_RDF
CONTENTS_XML

The following is used for the -1 option

CONTEXT_CONTENT

C O N T E X T C O N T E N T T E M P L A T E

FILE_INDEX
FILE_PAGE

F I L E P A G E H E A D E R T E M P L A T E

FONTS
FOOTER

F O O T E R T E M P L A T E

FR_INDEX_BODY

Index ################################

HEADER
HPP_FILE
INDEX
METHOD_INDEX
METHOD_LIST

M E T H O D L I S T T E M P L A T E

ONE_PAGE
SRC_PAGE

Source code ##########################

STYLE
XHTML_PREAMBLE

H E A D E R T E M P L A T E

Public Instance Methods

write_extra_pages() click to toggle source
 
               # File rdoc/generators/template/html/hefss.rb, line 412
def write_extra_pages
  template = TemplatePage.new(BLANK)
  File.open("blank.html", "w") { |f| template.write_html_on(f, {}) }
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus