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

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

[Source]

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

Public Instance methods

[Source]

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

[Source]

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

[Source]

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

[Source]

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

[Source]

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

[Source]

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

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

[Source]

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

Generate all the HTML

[Source]

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

return the url of the main page

[Source]

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

Write out the style sheet used by the main frames

[Source]

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

[Validate]