Class | RDoc::Generator::HTML |
In: |
generator/html.rb
|
Parent: | Object |
We‘re responsible for generating all the HTML files from the object tree defined in code_objects.rb. We generate:
Method descriptions appear in whatever entity (file, class, or module) that contains them.
We generate files in a structure below a specified subdirectory, normally doc.
opdir | |___ files | |__ per file summaries | |___ classes |__ per class/module descriptions
HTML is generated using the Template class.
Generator may need to return specific subclasses depending on the options they are passed. Because of this we create them using a factory
# File generator/html.rb, line 50 50: def self.for(options) 51: RDoc::Generator::AllReferences.reset 52: RDoc::Generator::Method.reset 53: 54: if options.all_one_file 55: RDoc::Generator::HTMLInOne.new options 56: else 57: new options 58: end 59: end
# File generator/html.rb, line 148 148: def build_indices 149: @files, @classes = RDoc::Generator::Context.build_indicies(@toplevels, 150: @options) 151: end
# File generator/html.rb, line 195 195: def gen_an_index(collection, title, template, filename) 196: template = RDoc::TemplatePage.new @template::FR_INDEX_BODY, template 197: res = [] 198: collection.sort.each do |f| 199: if f.document_self 200: res << { "href" => f.path, "name" => f.index_name } 201: end 202: end 203: 204: values = { 205: "entries" => res, 206: 'list_title' => CGI.escapeHTML(title), 207: 'index_url' => main_url, 208: 'charset' => @options.charset, 209: 'style_url' => style_url('', @options.css), 210: } 211: 212: open filename, 'w' do |f| 213: template.write_html_on(f, values) 214: end 215: end
# File generator/html.rb, line 185 185: def gen_class_index 186: gen_an_index(@classes, 'Classes', @template::CLASS_INDEX, 187: "fr_class_index.html") 188: end
# File generator/html.rb, line 181 181: def gen_file_index 182: gen_an_index @files, 'Files', @template::FILE_INDEX, "fr_file_index.html" 183: end
# File generator/html.rb, line 170 170: def gen_into(list) 171: list.each do |item| 172: if item.document_self 173: op_file = item.path 174: FileUtils.mkdir_p(::File.dirname(op_file)) 175: open(op_file, "w") { |file| item.write_on(file) } 176: end 177: end 178: 179: 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.
# File generator/html.rb, line 223 223: def gen_main_index 224: template = RDoc::TemplatePage.new @template::INDEX 225: 226: open 'index.html', 'w' do |f| 227: classes = @classes.sort.map { |klass| klass.value_hash } 228: 229: values = { 230: 'main_page' => @main_page, 231: 'initial_page' => main_url, 232: 'style_url' => style_url('', @options.css), 233: 'title' => CGI.escapeHTML(@options.title), 234: 'charset' => @options.charset, 235: 'classes' => classes, 236: } 237: 238: values['inline_source'] = @options.inline_source 239: 240: template.write_html_on f, values 241: end 242: end
# File generator/html.rb, line 190 190: def gen_method_index 191: gen_an_index(RDoc::Generator::Method.all_methods, 'Methods', 192: @template::METHOD_INDEX, "fr_method_index.html") 193: end
See the comments at the top for a description of the directory structure
# File generator/html.rb, line 140 140: def gen_sub_directories 141: FileUtils.mkdir_p RDoc::Generator::FILE_DIR 142: FileUtils.mkdir_p RDoc::Generator::CLASS_DIR 143: rescue 144: $stderr.puts $!.message 145: exit 1 146: end
Build the initial indices and output objects based on an array of TopLevel objects containing the extracted information.
# File generator/html.rb, line 79 79: def generate(toplevels) 80: @toplevels = toplevels 81: @files = [] 82: @classes = [] 83: 84: write_style_sheet 85: gen_sub_directories() 86: build_indices 87: generate_html 88: end
Generate all the HTML
# File generator/html.rb, line 156 156: def generate_html 157: # the individual descriptions for files and classes 158: gen_into(@files) 159: gen_into(@classes) 160: # and the index files 161: gen_file_index 162: gen_class_index 163: gen_method_index 164: gen_main_index 165: 166: # this method is defined in the template file 167: write_extra_pages if defined? write_extra_pages 168: end
Load up the HTML template specified in the options. If the template name contains a slash, use it literally
# File generator/html.rb, line 96 96: def load_html_template 97: template = @options.template 98: 99: unless template =~ %r{/|\\} then 100: template = ::File.join('rdoc', 'generator', @options.generator.key, 101: template) 102: end 103: 104: require template 105: 106: @template = self.class.const_get @options.template.upcase 107: @options.template_class = @template 108: 109: rescue LoadError 110: $stderr.puts "Could not find HTML template '#{template}'" 111: exit 99 112: end
Returns the url of the main page
# File generator/html.rb, line 247 247: def main_url 248: @main_page = @options.main_page 249: @main_page_ref = nil 250: if @main_page 251: @main_page_ref = AllReferences[@main_page] 252: if @main_page_ref then 253: @main_page_path = @main_page_ref.path 254: else 255: $stderr.puts "Could not find main page #{@main_page}" 256: end 257: end 258: 259: unless @main_page_path then 260: file = @files.find { |file| file.document_self } 261: @main_page_path = file.path if file 262: end 263: 264: unless @main_page_path then 265: $stderr.puts "Couldn't find anything to document" 266: $stderr.puts "Perhaps you've used :stopdoc: in all classes" 267: exit 1 268: end 269: 270: @main_page_path 271: end
Write out the style sheet used by the main frames
# File generator/html.rb, line 117 117: def write_style_sheet 118: return unless @template.constants.include? :STYLE or 119: @template.constants.include? 'STYLE' 120: 121: template = RDoc::TemplatePage.new @template::STYLE 122: 123: unless @options.css then 124: open RDoc::Generator::CSS_NAME, 'w' do |f| 125: values = {} 126: 127: if @template.constants.include? :FONTS or 128: @template.constants.include? 'FONTS' then 129: values["fonts"] = @template::FONTS 130: end 131: 132: template.write_html_on(f, values) 133: end 134: end 135: end