Class: Generators::HTMLGenerator

for(options)

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

[Source]

      # File generators/html_generator.rb, line 1217
1217:     def HTMLGenerator.for(options)
1218:       AllReferences::reset
1219:       HtmlMethod::reset
1220: 
1221:       if options.all_one_file
1222:         HTMLGeneratorInOne.new(options)
1223:       else
1224:         HTMLGenerator.new(options)
1225:       end
1226:     end

gen_url(path, target)

convert a target url to one that is relative to a given path

[Source]

      # File generators/html_generator.rb, line 1194
1194:     def HTMLGenerator.gen_url(path, target)
1195:       from          = File.dirname(path)
1196:       to, to_file   = File.split(target)
1197:       
1198:       from = from.split("/")
1199:       to   = to.split("/")
1200:       
1201:       while from.size > 0 and to.size > 0 and from[0] == to[0]
1202:         from.shift
1203:         to.shift
1204:       end
1205: 
1206:       from.delete_if{|f| f =~ /^\.$/}
1207:       from.fill("..")
1208:       from.concat(to)
1209:       from << to_file
1210:       File.join(*from)
1211:     end

new(options)

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

[Source]

      # File generators/html_generator.rb, line 1235
1235:     def initialize(options) #:not-new:
1236:       @options    = options
1237:       load_html_template
1238:     end

build_class_list(from, html_file, class_dir)

[Source]

      # File generators/html_generator.rb, line 1321
1321:     def build_class_list(from, html_file, class_dir)
1322:       @classes << HtmlClass.new(from, html_file, class_dir, @options)
1323:       from.each_classmodule do |mod|
1324:         build_class_list(mod, html_file, class_dir)
1325:       end
1326:     end

build_indices()

Generate:

a list of HtmlFile objects for each TopLevel object.
a list of HtmlClass 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)

[Source]

      # File generators/html_generator.rb, line 1310
1310:     def build_indices
1311: 
1312:       @toplevels.each do |toplevel|
1313:         @files << HtmlFile.new(toplevel, @options, FILE_DIR)
1314:       end
1315: 
1316:       RDoc::TopLevel.all_classes_and_modules.each do |cls|
1317:         build_class_list(cls, @files[0], CLASS_DIR)
1318:       end
1319:     end

gen_an_index(collection, title, template, filename)

[Source]

      # File generators/html_generator.rb, line 1375
1375:     def gen_an_index(collection, title, template, filename)
1376:       template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
1377:       res = []
1378:       collection.sort.each do |f|
1379:         if f.document_self
1380:           res << { "href" => f.path, "name" => f.index_name }
1381:         end
1382:       end
1383: 
1384:       values = {
1385:         "entries"    => res,
1386:         'list_title' => CGI.escapeHTML(title),
1387:         'index_url'  => main_url,
1388:         'charset'    => @options.charset,
1389:         'style_url'  => style_url('', @options.css),
1390:       }
1391: 
1392:       File.open(filename, "w") do |f|
1393:         template.write_html_on(f, values)
1394:       end
1395:     end

gen_class_index()

[Source]

      # File generators/html_generator.rb, line 1362
1362:     def gen_class_index
1363:       gen_an_index(@classes, 'Classes',
1364:                    RDoc::Page::CLASS_INDEX,
1365:                    "fr_class_index.html")
1366:     end

gen_file_index()

[Source]

      # File generators/html_generator.rb, line 1356
1356:     def gen_file_index
1357:       gen_an_index(@files, 'Files', 
1358:                    RDoc::Page::FILE_INDEX, 
1359:                    "fr_file_index.html")
1360:     end

gen_into(list)

[Source]

      # File generators/html_generator.rb, line 1345
1345:     def gen_into(list)
1346:       list.each do |item|
1347:         if item.document_self
1348:           op_file = item.path
1349:           File.makedirs(File.dirname(op_file))
1350:           File.open(op_file, "w") { |file| item.write_on(file) }
1351:         end
1352:       end
1353: 
1354:     end

gen_main_index()

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 generators/html_generator.rb, line 1402
1402:     def gen_main_index
1403:       template = TemplatePage.new(RDoc::Page::INDEX)
1404:       File.open("index.html", "w") do |f|
1405:         values = {
1406:           "initial_page" => main_url,
1407:           'title'        => CGI.escapeHTML(@options.title),
1408:           'charset'      => @options.charset
1409:         }
1410:         if @options.inline_source
1411:           values['inline_source'] = true
1412:         end
1413:         template.write_html_on(f, values)
1414:       end
1415:     end

gen_method_index()

[Source]

      # File generators/html_generator.rb, line 1368
1368:     def gen_method_index
1369:       gen_an_index(HtmlMethod.all_methods, 'Methods', 
1370:                    RDoc::Page::METHOD_INDEX,
1371:                    "fr_method_index.html")
1372:     end

gen_sub_directories()

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

[Source]

      # File generators/html_generator.rb, line 1294
1294:     def gen_sub_directories
1295:       File.makedirs(FILE_DIR, CLASS_DIR)
1296:     rescue 
1297:       $stderr.puts $!.message
1298:       exit 1
1299:     end

generate(toplevels)

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

[Source]

      # File generators/html_generator.rb, line 1246
1246:     def generate(toplevels)
1247:       @toplevels  = toplevels
1248:       @files      = []
1249:       @classes    = []
1250: 
1251:       write_style_sheet
1252:       gen_sub_directories()
1253:       build_indices
1254:       generate_html
1255:     end

generate_html()

Generate all the HTML

[Source]

      # File generators/html_generator.rb, line 1331
1331:     def generate_html
1332:       # the individual descriptions for files and classes
1333:       gen_into(@files)
1334:       gen_into(@classes)
1335:       # and the index files
1336:       gen_file_index
1337:       gen_class_index
1338:       gen_method_index
1339:       gen_main_index
1340:       
1341:       # this method is defined in the template file
1342:       write_extra_pages if defined? write_extra_pages
1343:     end

load_html_template()

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

[Source]

      # File generators/html_generator.rb, line 1263
1263:     def load_html_template
1264:       template = @options.template
1265:       unless template =~ %r{/|\\}
1266:         template = File.join("rdoc/generators/template",
1267:                              @options.generator.key, template)
1268:       end
1269:       require template
1270:       extend RDoc::Page
1271:     rescue LoadError
1272:       $stderr.puts "Could not find HTML template '#{template}'"
1273:       exit 99
1274:     end

main_url()

return the url of the main page

[Source]

      # File generators/html_generator.rb, line 1418
1418:     def main_url
1419:       main_page = @options.main_page
1420:       ref = nil
1421:       if main_page
1422:         ref = AllReferences[main_page]
1423:         if ref
1424:           ref = ref.path
1425:         else
1426:           $stderr.puts "Could not find main page #{main_page}"
1427:         end
1428:       end
1429: 
1430:       unless ref
1431:         for file in @files
1432:           if file.document_self
1433:             ref = file.path 
1434:             break
1435:           end
1436:         end
1437:       end
1438: 
1439:       unless ref
1440:         $stderr.puts "Couldn't find anything to document"
1441:         $stderr.puts "Perhaps you've used :stopdoc: in all classes"
1442:         exit(1)
1443:       end
1444: 
1445:       ref
1446:     end

write_style_sheet()

Write out the style sheet used by the main frames

[Source]

      # File generators/html_generator.rb, line 1280
1280:     def write_style_sheet
1281:       template = TemplatePage.new(RDoc::Page::STYLE)
1282:       unless @options.css
1283:         File.open(CSS_NAME, "w") do |f|
1284:           values = { "fonts" => RDoc::Page::FONTS }
1285:           template.write_html_on(f, values)
1286:         end
1287:       end
1288:     end

Methods

Included Modules

Public Class methods

Public Instance methods