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

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

[Source]

      # File generators/html_generator.rb, line 1191
1191:     def HTMLGenerator.gen_url(path, target)
1192:       from          = File.dirname(path)
1193:       to, to_file   = File.split(target)
1194:       
1195:       from = from.split("/")
1196:       to   = to.split("/")
1197:       
1198:       while from.size > 0 and to.size > 0 and from[0] == to[0]
1199:         from.shift
1200:         to.shift
1201:       end
1202:       
1203:       from.fill("..")
1204:       from.concat(to)
1205:       from << to_file
1206:       File.join(*from)
1207:     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 1231
1231:     def initialize(options) #:not-new:
1232:       @options    = options
1233:       load_html_template
1234:     end

Public Instance methods

[Source]

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

[Source]

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

[Source]

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

[Source]

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

[Source]

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

[Source]

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

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

[Source]

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

Generate all the HTML

[Source]

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

return the url of the main page

[Source]

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

Write out the style sheet used by the main frames

[Source]

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

[Validate]