1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
|
require 'fileutils'
require 'rdoc/generator'
require 'rdoc/markup/to_html'
##
# 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.
class RDoc::Generator::HTML
include RDoc::Generator::MarkUp
##
# Generator may need to return specific subclasses depending on the
# options they are passed. Because of this we create them using a factory
def self.for(options)
RDoc::Generator::AllReferences.reset
RDoc::Generator::Method.reset
if options.all_one_file
RDoc::Generator::HTMLInOne.new options
else
new options
end
end
class << self
protected :new
end
##
# Set up a new HTML generator. Basically all we do here is load up the
# correct output temlate
def initialize(options) #:not-new:
@options = options
load_html_template
end
##
# Build the initial indices and output objects
# based on an array of TopLevel objects containing
# the extracted information.
def generate(toplevels)
@toplevels = toplevels
@files = []
@classes = []
write_style_sheet
gen_sub_directories
build_indices
generate_html
end
private
##
# Load up the HTML template specified in the options.
# If the template name contains a slash, use it literally
def load_html_template
#
# If the template is not a path, first look for it
# in rdoc's HTML template directory. Perhaps this behavior should
# be reversed (first try to include the template and, only if that
# fails, try to include it in the default template directory).
# One danger with reversing the behavior, however, is that
# if something like require 'html' could load up an
# unrelated file in the standard library or in a gem.
#
template = @options.template
unless template =~ %r{/|\\} then
template = File.join('rdoc', 'generator', @options.generator.key,
template)
end
begin
require template
@template = self.class.const_get @options.template.upcase
@options.template_class = @template
rescue LoadError => e
#
# The template did not exist in the default template directory, so
# see if require can find the template elsewhere (in a gem, for
# instance).
#
if(e.message[template] && template != @options.template)
template = @options.template
retry
end
$stderr.puts "Could not find HTML template '#{template}': #{e.message}"
exit 99
end
end
##
# Write out the style sheet used by the main frames
def write_style_sheet
return unless @template.constants.include? :STYLE or
@template.constants.include? 'STYLE'
template = RDoc::TemplatePage.new @template::STYLE
unless @options.css then
open RDoc::Generator::CSS_NAME, 'w' do |f|
values = {}
if @template.constants.include? :FONTS or
@template.constants.include? 'FONTS' then
values["fonts"] = @template::FONTS
end
template.write_html_on(f, values)
end
end
end
##
# See the comments at the top for a description of the directory structure
def gen_sub_directories
FileUtils.mkdir_p RDoc::Generator::FILE_DIR
FileUtils.mkdir_p RDoc::Generator::CLASS_DIR
rescue
$stderr.puts $!.message
exit 1
end
def build_indices
@files, @classes = RDoc::Generator::Context.build_indices(@toplevels,
@options)
end
##
# Generate all the HTML
def generate_html
@main_url = main_url
# the individual descriptions for files and classes
gen_into(@files)
gen_into(@classes)
# and the index files
gen_file_index
gen_class_index
gen_method_index
gen_main_index
# this method is defined in the template file
values = {
'title_suffix' => CGI.escapeHTML("[#{@options.title}]"),
'charset' => @options.charset,
'style_url' => style_url('', @options.css),
}
@template.write_extra_pages(values) if @template.respond_to?(:write_extra_pages)
end
def gen_into(list)
#
# The file, class, and method lists technically should be regenerated
# for every output file, in order that the relative links be correct
# (we are worried here about frameless templates, which need this
# information for every generated page). Doing this is a bit slow,
# however. For a medium-sized gem, this increased rdoc's runtime by
# about 5% (using the 'time' command-line utility). While this is not
# necessarily a problem, I do not want to pessimize rdoc for large
# projects, however, and so we only regenerate the lists when the
# directory of the output file changes, which seems like a reasonable
# optimization.
#
file_list = {}
class_list = {}
method_list = {}
prev_op_dir = nil
list.each do |item|
next unless item.document_self
op_file = item.path
op_dir = File.dirname(op_file)
if(op_dir != prev_op_dir)
file_list = index_to_links op_file, @files
class_list = index_to_links op_file, @classes
method_list = index_to_links op_file, RDoc::Generator::Method.all_methods
end
prev_op_dir = op_dir
FileUtils.mkdir_p op_dir
open op_file, 'w' do |io|
item.write_on io, file_list, class_list, method_list
end
end
end
def gen_file_index
gen_an_index @files, 'Files', @template::FILE_INDEX, "fr_file_index.html"
end
def gen_class_index
gen_an_index(@classes, 'Classes', @template::CLASS_INDEX,
"fr_class_index.html")
end
def gen_method_index
gen_an_index(RDoc::Generator::Method.all_methods, 'Methods',
@template::METHOD_INDEX, "fr_method_index.html")
end
def gen_an_index(collection, title, template, filename)
template = RDoc::TemplatePage.new @template::FR_INDEX_BODY, template
res = []
collection.sort.each do |f|
if f.document_self
res << { "href" => f.path, "name" => f.index_name }
end
end
values = {
"entries" => res,
'title' => CGI.escapeHTML("#{title} [#{@options.title}]"),
'list_title' => CGI.escapeHTML(title),
'index_url' => @main_url,
'charset' => @options.charset,
'style_url' => style_url('', @options.css),
}
open filename, 'w' do |f|
template.write_html_on(f, values)
end
end
##
# The main index page is mostly a template frameset, but includes the
# initial page. If the <tt>--main</tt> option was given, we use this as
# our main page, otherwise we use the first file specified on the command
# line.
def gen_main_index
if @template.const_defined? :FRAMELESS then
#
# If we're using a template without frames, then just redirect
# to it from index.html.
#
# One alternative to this, expanding the main page's template into
# index.html, is tricky because the relative URLs will be different
# (since index.html is located in at the site's root,
# rather than within a files or a classes subdirectory).
#
open 'index.html', 'w' do |f|
f.puts(%{<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">})
f.puts(%{<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
lang="en">})
f.puts(%{<head>})
f.puts(%{<title>#{CGI.escapeHTML(@options.title)}</title>})
f.puts(%{<meta http-equiv="refresh" content="0; url=#{@main_url}" />})
f.puts(%{</head>})
f.puts(%{<body></body>})
f.puts(%{</html>})
end
else
main = RDoc::TemplatePage.new @template::INDEX
open 'index.html', 'w' do |f|
style_url = style_url '', @options.css
classes = @classes.sort.map { |klass| klass.value_hash }
values = {
'initial_page' => @main_url,
'style_url' => style_url('', @options.css),
'title' => CGI.escapeHTML(@options.title),
'charset' => @options.charset,
'classes' => classes,
}
values['inline_source'] = @options.inline_source
main.write_html_on f, values
end
end
end
def index_to_links(output_path, collection)
collection.sort.map do |f|
next unless f.document_self
{ "href" => RDoc::Markup::ToHtml.gen_relative_url(output_path, f.path),
"name" => f.index_name }
end.compact
end
##
# Returns the url of the main page
def main_url
main_page = @options.main_page
#
# If a main page has been specified (--main), then search for it
# in the AllReferences array. This allows either files or classes
# to be used for the main page.
#
if main_page then
main_page_ref = RDoc::Generator::AllReferences[main_page]
if main_page_ref then
return main_page_ref.path
else
$stderr.puts "Could not find main page #{main_page}"
end
end
#
# No main page has been specified, so just use the README.
#
@files.each do |file|
if file.name =~ /^README/ then
return file.path
end
end
#
# There's no README (shame! shame!). Just use the first file
# that will be documented.
#
@files.each do |file|
if file.document_self then
return file.path
end
end
#
# There are no files to be documented... Something seems very wrong.
#
raise RDoc::Error, "Couldn't find anything to document (perhaps :stopdoc: has been used in all classes)!"
end
private :main_url
end
class RDoc::Generator::HTMLInOne < RDoc::Generator::HTML
def initialize(*args)
super
end
##
# Build the initial indices and output objects
# based on an array of TopLevel objects containing
# the extracted information.
def generate(info)
@toplevels = info
@hyperlinks = {}
build_indices
generate_xml
end
##
# Generate:
#
# * a list of RDoc::Generator::File objects for each TopLevel object.
# * a list of RDoc::Generator::Class objects for each first level
# class or module in the TopLevel objects
# * a complete list of all hyperlinkable terms (file,
# class, module, and method names)
def build_indices
@files, @classes = RDoc::Generator::Context.build_indices(@toplevels,
@options)
end
##
# Generate all the HTML. For the one-file case, we generate
# all the information in to one big hash
def generate_xml
values = {
'charset' => @options.charset,
'files' => gen_into(@files),
'classes' => gen_into(@classes),
'title' => CGI.escapeHTML(@options.title),
}
template = RDoc::TemplatePage.new @template::ONE_PAGE
if @options.op_name
opfile = open @options.op_name, 'w'
else
opfile = $stdout
end
template.write_html_on(opfile, values)
end
def gen_into(list)
res = []
list.each do |item|
res << item.value_hash
end
res
end
end
|