lib/rdoc/generator/html.rb

   1 require 'fileutils'
   2
   3 require 'rdoc/generator'
   4 require 'rdoc/markup/to_html'
   5
   6 ##
   7 # We're responsible for generating all the HTML files from the object tree
   8 # defined in code_objects.rb. We generate:
   9 #
  10 # [files]   an html file for each input file given. These
  11 #           input files appear as objects of class
  12 #           TopLevel
  13 #
  14 # [classes] an html file for each class or module encountered.
  15 #           These classes are not grouped by file: if a file
  16 #           contains four classes, we'll generate an html
  17 #           file for the file itself, and four html files
  18 #           for the individual classes.
  19 #
  20 # [indices] we generate three indices for files, classes,
  21 #           and methods. These are displayed in a browser
  22 #           like window with three index panes across the
  23 #           top and the selected description below
  24 #
  25 # Method descriptions appear in whatever entity (file, class, or module) that
  26 # contains them.
  27 #
  28 # We generate files in a structure below a specified subdirectory, normally
  29 # +doc+.
  30 #
  31 #  opdir
  32 #     |
  33 #     |___ files
  34 #     |       |__  per file summaries
  35 #     |
  36 #     |___ classes
  37 #             |__ per class/module descriptions
  38 #
  39 # HTML is generated using the Template class.
  40
  41 class RDoc::Generator::HTML
  42
  43   include RDoc::Generator::MarkUp
  44
  45   ##
  46   # Generator may need to return specific subclasses depending on the
  47   # options they are passed. Because of this we create them using a factory
  48
  49   def self.for(options)
  50     RDoc::Generator::AllReferences.reset
  51     RDoc::Generator::Method.reset
  52
  53     if options.all_one_file
  54       RDoc::Generator::HTMLInOne.new options
  55     else
  56       new options
  57     end
  58   end
  59
  60   class << self
  61     protected :new
  62   end
  63
  64   ##
  65   # Set up a new HTML generator. Basically all we do here is load up the
  66   # correct output temlate
  67
  68   def initialize(options) #:not-new:
  69     @options = options
  70     load_html_template
  71     @main_page_path = nil
  72   end
  73
  74   ##
  75   # Build the initial indices and output objects
  76   # based on an array of TopLevel objects containing
  77   # the extracted information.
  78
  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
  89
  90   private
  91
  92   ##
  93   # Load up the HTML template specified in the options.
  94   # If the template name contains a slash, use it literally
  95
  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
 113
 114   ##
 115   # Write out the style sheet used by the main frames
 116
 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
 136
 137   ##
 138   # See the comments at the top for a description of the directory structure
 139
 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
 147
 148   def build_indices
 149     @files, @classes = RDoc::Generator::Context.build_indicies(@toplevels,
 150                                                                @options)
 151   end
 152
 153   ##
 154   # Generate all the HTML
 155
 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
 169
 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
 180
 181   def gen_file_index
 182     gen_an_index @files, 'Files', @template::FILE_INDEX, "fr_file_index.html"
 183   end
 184
 185   def gen_class_index
 186     gen_an_index(@classes, 'Classes', @template::CLASS_INDEX,
 187                  "fr_class_index.html")
 188   end
 189
 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
 194
 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
 216
 217   ##
 218   # The main index page is mostly a template frameset, but includes the
 219   # initial page. If the <tt>--main</tt> option was given, we use this as
 220   # our main page, otherwise we use the first file specified on the command
 221   # line.
 222
 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
 243
 244   ##
 245   # Returns the url of the main page
 246
 247   def main_url
 248     @main_page = @options.main_page
 249     @main_page_ref = nil
 250     if @main_page
 251       @main_page_ref = RDoc::Generator::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 { |context| context.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
 272
 273 end
 274
 275 class RDoc::Generator::HTMLInOne < RDoc::Generator::HTML
 276
 277   def initialize(*args)
 278     super
 279   end
 280
 281   ##
 282   # Build the initial indices and output objects
 283   # based on an array of TopLevel objects containing
 284   # the extracted information.
 285
 286   def generate(info)
 287     @toplevels  = info
 288     @hyperlinks = {}
 289
 290     build_indices
 291     generate_xml
 292   end
 293
 294   ##
 295   # Generate:
 296   #
 297   # * a list of RDoc::Generator::File objects for each TopLevel object.
 298   # * a list of RDoc::Generator::Class objects for each first level
 299   #   class or module in the TopLevel objects
 300   # * a complete list of all hyperlinkable terms (file,
 301   #   class, module, and method names)
 302
 303   def build_indices
 304     @files, @classes = RDoc::Generator::Context.build_indices(@toplevels,
 305                                                               @options)
 306   end
 307
 308   ##
 309   # Generate all the HTML. For the one-file case, we generate
 310   # all the information in to one big hash
 311
 312   def generate_xml
 313     values = {
 314       'charset' => @options.charset,
 315       'files'   => gen_into(@files),
 316       'classes' => gen_into(@classes),
 317       'title'        => CGI.escapeHTML(@options.title),
 318     }
 319
 320     # this method is defined in the template file
 321     write_extra_pages if defined? write_extra_pages
 322
 323     template = RDoc::TemplatePage.new @template::ONE_PAGE
 324
 325     if @options.op_name
 326       opfile = open @options.op_name, 'w'
 327     else
 328       opfile = $stdout
 329     end
 330     template.write_html_on(opfile, values)
 331   end
 332
 333   def gen_into(list)
 334     res = []
 335     list.each do |item|
 336       res << item.value_hash
 337     end
 338     res
 339   end
 340
 341   def gen_file_index
 342     gen_an_index(@files, 'Files')
 343   end
 344
 345   def gen_class_index
 346     gen_an_index(@classes, 'Classes')
 347   end
 348
 349   def gen_method_index
 350     gen_an_index(RDoc::Generator::Method.all_methods, 'Methods')
 351   end
 352
 353   def gen_an_index(collection, title)
 354     res = []
 355     collection.sort.each do |f|
 356       if f.document_self
 357         res << { "href" => f.path, "name" => f.index_name }
 358       end
 359     end
 360
 361     return {
 362       "entries" => res,
 363       'list_title' => title,
 364       'index_url'  => main_url,
 365     }
 366   end
 367
 368 end
 369
 370