Class RDoc::Generator::HTML
In: generator/html.rb
Parent: Object

We‘re responsible for generating all the HTML files from the object tree defined in code_objects.rb. We generate:

files
an html file for each input file given. These input files appear as objects of class TopLevel
classes
an html file for each class or module encountered. These classes are not grouped by file: if a file contains four classes, we‘ll generate an html file for the file itself, and four html files for the individual classes.
indices
we generate three indices for files, classes, and methods. These are displayed in a browser like window with three index panes across the top and the selected description below

Method descriptions appear in whatever entity (file, class, or module) that contains them.

We generate files in a structure below a specified subdirectory, normally doc.

 opdir
    |
    |___ files
    |       |__  per file summaries
    |
    |___ classes
            |__ per class/module descriptions

HTML is generated using the Template class.

Methods

Included Modules

RDoc::Generator RDoc::Generator::MarkUp

Public Class methods

Generator may need to return specific subclasses depending on the options they are passed. Because of this we create them using a factory

[Source]

    # File generator/html.rb, line 50
50:   def self.for(options)
51:     RDoc::Generator::AllReferences.reset
52:     RDoc::Generator::Method.reset
53: 
54:     if options.all_one_file
55:       RDoc::Generator::HTMLInOne.new options
56:     else
57:       new options
58:     end
59:   end

Set up a new HTML generator. Basically all we do here is load up the correct output temlate

[Source]

    # File generator/html.rb, line 69
69:   def initialize(options) #:not-new:
70:     @options = options
71:     load_html_template
72:   end

Public Instance methods

[Source]

     # File generator/html.rb, line 148
148:   def build_indices
149:     @files, @classes = RDoc::Generator::Context.build_indicies(@toplevels,
150:                                                                @options)
151:   end

[Source]

     # File generator/html.rb, line 195
195:   def gen_an_index(collection, title, template, filename)
196:     template = RDoc::TemplatePage.new @template::FR_INDEX_BODY, template
197:     res = []
198:     collection.sort.each do |f|
199:       if f.document_self
200:         res << { "href" => f.path, "name" => f.index_name }
201:       end
202:     end
203: 
204:     values = {
205:       "entries"    => res,
206:       'list_title' => CGI.escapeHTML(title),
207:       'index_url'  => main_url,
208:       'charset'    => @options.charset,
209:       'style_url'  => style_url('', @options.css),
210:     }
211: 
212:     open filename, 'w' do |f|
213:       template.write_html_on(f, values)
214:     end
215:   end

[Source]

     # File generator/html.rb, line 185
185:   def gen_class_index
186:     gen_an_index(@classes, 'Classes', @template::CLASS_INDEX,
187:                  "fr_class_index.html")
188:   end

[Source]

     # File generator/html.rb, line 181
181:   def gen_file_index
182:     gen_an_index @files, 'Files', @template::FILE_INDEX, "fr_file_index.html"
183:   end

[Source]

     # File generator/html.rb, line 170
170:   def gen_into(list)
171:     list.each do |item|
172:       if item.document_self
173:         op_file = item.path
174:         FileUtils.mkdir_p(::File.dirname(op_file))
175:         open(op_file, "w") { |file| item.write_on(file) }
176:       end
177:     end
178: 
179:   end

The main index page is mostly a template frameset, but includes the initial page. If the —main option was given, we use this as our main page, otherwise we use the first file specified on the command line.

[Source]

     # File generator/html.rb, line 223
223:   def gen_main_index
224:     template = RDoc::TemplatePage.new @template::INDEX
225: 
226:     open 'index.html', 'w'  do |f|
227:       classes = @classes.sort.map { |klass| klass.value_hash }
228: 
229:       values = {
230:         'main_page'     => @main_page,
231:         'initial_page'  => main_url,
232:         'style_url'     => style_url('', @options.css),
233:         'title'         => CGI.escapeHTML(@options.title),
234:         'charset'       => @options.charset,
235:         'classes'       => classes,
236:       }
237: 
238:       values['inline_source'] = @options.inline_source
239: 
240:       template.write_html_on f, values
241:     end
242:   end

[Source]

     # File generator/html.rb, line 190
190:   def gen_method_index
191:     gen_an_index(RDoc::Generator::Method.all_methods, 'Methods',
192:                  @template::METHOD_INDEX, "fr_method_index.html")
193:   end

See the comments at the top for a description of the directory structure

[Source]

     # File generator/html.rb, line 140
140:   def gen_sub_directories
141:     FileUtils.mkdir_p RDoc::Generator::FILE_DIR
142:     FileUtils.mkdir_p RDoc::Generator::CLASS_DIR
143:   rescue
144:     $stderr.puts $!.message
145:     exit 1
146:   end

Build the initial indices and output objects based on an array of TopLevel objects containing the extracted information.

[Source]

    # File generator/html.rb, line 79
79:   def generate(toplevels)
80:     @toplevels  = toplevels
81:     @files      = []
82:     @classes    = []
83: 
84:     write_style_sheet
85:     gen_sub_directories()
86:     build_indices
87:     generate_html
88:   end

Generate all the HTML

[Source]

     # File generator/html.rb, line 156
156:   def generate_html
157:     # the individual descriptions for files and classes
158:     gen_into(@files)
159:     gen_into(@classes)
160:     # and the index files
161:     gen_file_index
162:     gen_class_index
163:     gen_method_index
164:     gen_main_index
165: 
166:     # this method is defined in the template file
167:     write_extra_pages if defined? write_extra_pages
168:   end

Load up the HTML template specified in the options. If the template name contains a slash, use it literally

[Source]

     # File generator/html.rb, line 96
 96:   def load_html_template
 97:     template = @options.template
 98: 
 99:     unless template =~ %r{/|\\} then
100:       template = ::File.join('rdoc', 'generator', @options.generator.key,
101:                              template)
102:     end
103: 
104:     require template
105: 
106:     @template = self.class.const_get @options.template.upcase
107:     @options.template_class = @template
108: 
109:   rescue LoadError
110:     $stderr.puts "Could not find HTML template '#{template}'"
111:     exit 99
112:   end

Returns the url of the main page

[Source]

     # File generator/html.rb, line 247
247:   def main_url
248:     @main_page = @options.main_page
249:     @main_page_ref = nil
250:     if @main_page
251:       @main_page_ref = AllReferences[@main_page]
252:       if @main_page_ref then
253:         @main_page_path = @main_page_ref.path
254:       else
255:         $stderr.puts "Could not find main page #{@main_page}"
256:       end
257:     end
258: 
259:     unless @main_page_path then
260:       file = @files.find { |file| file.document_self }
261:       @main_page_path = file.path if file
262:     end
263: 
264:     unless @main_page_path then
265:       $stderr.puts "Couldn't find anything to document"
266:       $stderr.puts "Perhaps you've used :stopdoc: in all classes"
267:       exit 1
268:     end
269: 
270:     @main_page_path
271:   end

Write out the style sheet used by the main frames

[Source]

     # File generator/html.rb, line 117
117:   def write_style_sheet
118:     return unless @template.constants.include? :STYLE or
119:                   @template.constants.include? 'STYLE'
120: 
121:     template = RDoc::TemplatePage.new @template::STYLE
122: 
123:     unless @options.css then
124:       open RDoc::Generator::CSS_NAME, 'w' do |f|
125:         values = {}
126: 
127:         if @template.constants.include? :FONTS or
128:            @template.constants.include? 'FONTS' then
129:           values["fonts"] = @template::FONTS
130:         end
131: 
132:         template.write_html_on(f, values)
133:       end
134:     end
135:   end

[Validate]