Class Generators::HTMLGenerator
In: generators/html_generator.rb
Parent: Object

Methods

Included Modules

MarkUp

Public Class methods

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 1216
1216:     def HTMLGenerator.for(options)
1217:       AllReferences::reset
1218:       HtmlMethod::reset
1219: 
1220:       if options.all_one_file
1221:         HTMLGeneratorInOne.new(options)
1222:       else
1223:         HTMLGenerator.new(options)
1224:       end
1225:     end

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

[Source]

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

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 1234
1234:     def initialize(options) #:not-new:
1235:       @options    = options
1236:       load_html_template
1237:     end

Public Instance methods

[Source]

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

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 1309
1309:     def build_indices
1310: 
1311:       @toplevels.each do |toplevel|
1312:         @files << HtmlFile.new(toplevel, @options, FILE_DIR)
1313:       end
1314: 
1315:       RDoc::TopLevel.all_classes_and_modules.each do |cls|
1316:         build_class_list(cls, @files[0], CLASS_DIR)
1317:       end
1318:     end

[Source]

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

[Source]

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

[Source]

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

[Source]

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

[Source]

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

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

[Source]

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

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 1245
1245:     def generate(toplevels)
1246:       @toplevels  = toplevels
1247:       @files      = []
1248:       @classes    = []
1249: 
1250:       write_style_sheet
1251:       gen_sub_directories()
1252:       build_indices
1253:       generate_html
1254:     end

Generate all the HTML

[Source]

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

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

return the url of the main page

[Source]

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

Write out the style sheet used by the main frames

[Source]

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

[Validate]