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 1215
1215:     def HTMLGenerator.for(options)
1216:       AllReferences::reset
1217:       HtmlMethod::reset
1218: 
1219:       if options.all_one_file
1220:         HTMLGeneratorInOne.new(options)
1221:       else
1222:         HTMLGenerator.new(options)
1223:       end
1224:     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 1192
1192:     def HTMLGenerator.gen_url(path, target)
1193:       from          = File.dirname(path)
1194:       to, to_file   = File.split(target)
1195:       
1196:       from = from.split("/")
1197:       to   = to.split("/")
1198:       
1199:       while from.size > 0 and to.size > 0 and from[0] == to[0]
1200:         from.shift
1201:         to.shift
1202:       end
1203:       
1204:       from.delete_if{|f| f =~ /^\.$/}
1205:       from.fill("..")
1206:       from.concat(to)
1207:       from << to_file
1208:       File.join(*from)
1209:     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 1233
1233:     def initialize(options) #:not-new:
1234:       @options    = options
1235:       load_html_template
1236:     end

build_class_list(from, html_file, class_dir)

[Source]

      # File generators/html_generator.rb, line 1319
1319:     def build_class_list(from, html_file, class_dir)
1320:       @classes << HtmlClass.new(from, html_file, class_dir, @options)
1321:       from.each_classmodule do |mod|
1322:         build_class_list(mod, html_file, class_dir)
1323:       end
1324:     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 1308
1308:     def build_indices
1309: 
1310:       @toplevels.each do |toplevel|
1311:         @files << HtmlFile.new(toplevel, @options, FILE_DIR)
1312:       end
1313: 
1314:       RDoc::TopLevel.all_classes_and_modules.each do |cls|
1315:         build_class_list(cls, @files[0], CLASS_DIR)
1316:       end
1317:     end

gen_an_index(collection, title, template, filename)

[Source]

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

gen_class_index()

[Source]

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

gen_file_index()

[Source]

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

gen_into(list)

[Source]

      # File generators/html_generator.rb, line 1343
1343:     def gen_into(list)
1344:       list.each do |item|
1345:         if item.document_self
1346:           op_file = item.path
1347:           File.makedirs(File.dirname(op_file))
1348:           File.open(op_file, "w") { |file| item.write_on(file) }
1349:         end
1350:       end
1351: 
1352:     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 1400
1400:     def gen_main_index
1401:       template = TemplatePage.new(RDoc::Page::INDEX)
1402:       File.open("index.html", "w") do |f|
1403:         values = {
1404:           "initial_page" => main_url,
1405:           'title'        => CGI.escapeHTML(@options.title),
1406:           'charset'      => @options.charset
1407:         }
1408:         if @options.inline_source
1409:           values['inline_source'] = true
1410:         end
1411:         template.write_html_on(f, values)
1412:       end
1413:     end

gen_method_index()

[Source]

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

gen_sub_directories()

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

[Source]

      # File generators/html_generator.rb, line 1292
1292:     def gen_sub_directories
1293:       File.makedirs(FILE_DIR, CLASS_DIR)
1294:     rescue 
1295:       $stderr.puts $!.message
1296:       exit 1
1297:     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 1244
1244:     def generate(toplevels)
1245:       @toplevels  = toplevels
1246:       @files      = []
1247:       @classes    = []
1248: 
1249:       write_style_sheet
1250:       gen_sub_directories()
1251:       build_indices
1252:       generate_html
1253:     end

generate_html()

Generate all the HTML

[Source]

      # File generators/html_generator.rb, line 1329
1329:     def generate_html
1330:       # the individual descriptions for files and classes
1331:       gen_into(@files)
1332:       gen_into(@classes)
1333:       # and the index files
1334:       gen_file_index
1335:       gen_class_index
1336:       gen_method_index
1337:       gen_main_index
1338:       
1339:       # this method is defined in the template file
1340:       write_extra_pages if defined? write_extra_pages
1341:     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 1261
1261:     def load_html_template
1262:       template = @options.template
1263:       unless template =~ %r{/|\\}
1264:         template = File.join("rdoc/generators/template",
1265:                              @options.generator.key, template)
1266:       end
1267:       require template
1268:       extend RDoc::Page
1269:     rescue LoadError
1270:       $stderr.puts "Could not find HTML template '#{template}'"
1271:       exit 99
1272:     end

main_url()

return the url of the main page

[Source]

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

write_style_sheet()

Write out the style sheet used by the main frames

[Source]

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

Methods

Included Modules

Public Class methods

Public Instance methods