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 lib/rdoc/generators/html_generator.rb, line 1160
1160:     def HTMLGenerator.for(options)
1161:       AllReferences::reset
1162:       HtmlMethod::reset
1163: 
1164:       if options.all_one_file
1165:         HTMLGeneratorInOne.new(options)
1166:       else
1167:         HTMLGenerator.new(options)
1168:       end
1169:     end

gen_url(path, target)

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

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1138
1138:     def HTMLGenerator.gen_url(path, target)
1139:       from          = File.dirname(path)
1140:       to, to_file   = File.split(target)
1141:       
1142:       from = from.split("/")
1143:       to   = to.split("/")
1144:       
1145:       while from.size > 0 and to.size > 0 and from[0] == to[0]
1146:         from.shift
1147:         to.shift
1148:       end
1149:       
1150:       from.fill("..")
1151:       from.concat(to)
1152:       from << to_file
1153:       File.join(*from)
1154:     end

new(options)

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

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1178
1178:     def initialize(options) #:not-new:
1179:       @options    = options
1180:       load_html_template
1181:     end

generate(toplevels)

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

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1189
1189:     def generate(toplevels)
1190:       @toplevels  = toplevels
1191:       @files      = []
1192:       @classes    = []
1193: 
1194:       write_style_sheet
1195:       gen_sub_directories()
1196:       build_indices
1197:       generate_html
1198:     end

build_class_list(from, html_file, class_dir)

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1264
1264:     def build_class_list(from, html_file, class_dir)
1265:       @classes << HtmlClass.new(from, html_file, class_dir, @options)
1266:       from.each_classmodule do |mod|
1267:         build_class_list(mod, html_file, class_dir)
1268:       end
1269:     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 lib/rdoc/generators/html_generator.rb, line 1253
1253:     def build_indices
1254: 
1255:       @toplevels.each do |toplevel|
1256:         @files << HtmlFile.new(toplevel, @options, FILE_DIR)
1257:       end
1258: 
1259:       RDoc::TopLevel.all_classes_and_modules.each do |cls|
1260:         build_class_list(cls, @files[0], CLASS_DIR)
1261:       end
1262:     end

gen_an_index(collection, title, template, filename)

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1318
1318:     def gen_an_index(collection, title, template, filename)
1319:       template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
1320:       res = []
1321:       collection.sort.each do |f|
1322:         if f.document_self
1323:           res << { "href" => f.path, "name" => f.index_name }
1324:         end
1325:       end
1326: 
1327:       values = {
1328:         "entries"    => res,
1329:         'list_title' => CGI.escapeHTML(title),
1330:         'index_url'  => main_url,
1331:         'charset'    => @options.charset,
1332:         'style_url'  => style_url('', @options.css),
1333:       }
1334: 
1335:       File.open(filename, "w") do |f|
1336:         template.write_html_on(f, values)
1337:       end
1338:     end

gen_class_index()

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1305
1305:     def gen_class_index
1306:       gen_an_index(@classes, 'Classes',
1307:                    RDoc::Page::CLASS_INDEX,
1308:                    "fr_class_index.html")
1309:     end

gen_file_index()

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1299
1299:     def gen_file_index
1300:       gen_an_index(@files, 'Files', 
1301:                    RDoc::Page::FILE_INDEX, 
1302:                    "fr_file_index.html")
1303:     end

gen_into(list)

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1288
1288:     def gen_into(list)
1289:       list.each do |item|
1290:         if item.document_self
1291:           op_file = item.path
1292:           File.makedirs(File.dirname(op_file))
1293:           File.open(op_file, "w") { |file| item.write_on(file) }
1294:         end
1295:       end
1296: 
1297:     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 lib/rdoc/generators/html_generator.rb, line 1345
1345:     def gen_main_index
1346:       template = TemplatePage.new(RDoc::Page::INDEX)
1347:       File.open("index.html", "w") do |f|
1348:         values = {
1349:           "initial_page" => main_url,
1350:           'title'        => CGI.escapeHTML(@options.title),
1351:           'charset'      => @options.charset
1352:         }
1353:         if @options.inline_source
1354:           values['inline_source'] = true
1355:         end
1356:         template.write_html_on(f, values)
1357:       end
1358:     end

gen_method_index()

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1311
1311:     def gen_method_index
1312:       gen_an_index(HtmlMethod.all_methods, 'Methods', 
1313:                    RDoc::Page::METHOD_INDEX,
1314:                    "fr_method_index.html")
1315:     end

gen_sub_directories()

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

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1237
1237:     def gen_sub_directories
1238:       File.makedirs(FILE_DIR, CLASS_DIR)
1239:     rescue 
1240:       $stderr.puts $!.message
1241:       exit 1
1242:     end

generate_html()

Generate all the HTML

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1274
1274:     def generate_html
1275:       # the individual descriptions for files and classes
1276:       gen_into(@files)
1277:       gen_into(@classes)
1278:       # and the index files
1279:       gen_file_index
1280:       gen_class_index
1281:       gen_method_index
1282:       gen_main_index
1283:       
1284:       # this method is defined in the template file
1285:       write_extra_pages if defined? write_extra_pages
1286:     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 lib/rdoc/generators/html_generator.rb, line 1206
1206:     def load_html_template
1207:       template = @options.template
1208:       unless template =~ %r{/|\\}
1209:         template = File.join("rdoc/generators/template",
1210:                              @options.generator.key, template)
1211:       end
1212:       require template
1213:       extend RDoc::Page
1214:     rescue LoadError
1215:       $stderr.puts "Could not find HTML template '#{template}'"
1216:       exit 99
1217:     end

main_url()

return the url of the main page

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1361
1361:     def main_url
1362:       main_page = @options.main_page
1363:       ref = nil
1364:       if main_page
1365:         ref = AllReferences[main_page]
1366:         if ref
1367:           ref = ref.path
1368:         else
1369:           $stderr.puts "Could not find main page #{main_page}"
1370:         end
1371:       end
1372: 
1373:       unless ref
1374:         for file in @files
1375:           if file.document_self
1376:             ref = file.path 
1377:             break
1378:           end
1379:         end
1380:       end
1381: 
1382:       unless ref
1383:         $stderr.puts "Couldn't find anything to document"
1384:         $stderr.puts "Perhaps you've used :stopdoc: in all classes"
1385:         exit(1)
1386:       end
1387: 
1388:       ref
1389:     end

write_style_sheet()

Write out the style sheet used by the main frames

[Source]

      # File lib/rdoc/generators/html_generator.rb, line 1223
1223:     def write_style_sheet
1224:       template = TemplatePage.new(RDoc::Page::STYLE)
1225:       unless @options.css
1226:         File.open(CSS_NAME, "w") do |f|
1227:           values = { "fonts" => RDoc::Page::FONTS }
1228:           template.write_html_on(f, values)
1229:         end
1230:       end
1231:     end

Methods

Included Modules

Public Class methods

Public Instance methods

Private Instance methods