diff options
Diffstat (limited to 'lib/rdoc/generator')
| -rw-r--r-- | lib/rdoc/generator/html.rb | 1691 | ||||
| -rw-r--r-- | lib/rdoc/generator/html/html.rb | 8 |
2 files changed, 269 insertions, 1430 deletions
diff --git a/lib/rdoc/generator/html.rb b/lib/rdoc/generator/html.rb index e6a6cd9ac9..95617725e9 100644 --- a/lib/rdoc/generator/html.rb +++ b/lib/rdoc/generator/html.rb @@ -3,1528 +3,367 @@ require 'fileutils' require 'rdoc/generator' require 'rdoc/markup/to_html' -module RDoc::Generator +## +# We're responsible for generating all the HTML files from the object tree +# defined in code_objects.rb. We generate: +# +# [files] an html file for each input file given. These +# input files appear as objects of class +# TopLevel +# +# [classes] an html file for each class or module encountered. +# These classes are not grouped by file: if a file +# contains four classes, we'll generate an html +# file for the file itself, and four html files +# for the individual classes. +# +# [indices] we generate three indices for files, classes, +# and methods. These are displayed in a browser +# like window with three index panes across the +# top and the selected description below +# +# 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. + +class RDoc::Generator::HTML + + include RDoc::Generator::MarkUp ## - # Build a hash of all items that can be cross-referenced. - # This is used when we output required and included names: - # if the names appear in this hash, we can generate - # an html cross reference to the appropriate description. - # We also use this when parsing comment blocks: any decorated - # words matching an entry in this list are hyperlinked. - - class AllReferences - @@refs = {} - - def AllReferences::reset - @@refs = {} - end + # Generator may need to return specific subclasses depending on the + # options they are passed. Because of this we create them using a factory - def AllReferences.add(name, html_class) - @@refs[name] = html_class - end + def self.for(options) + RDoc::Generator::AllReferences.reset + RDoc::Generator::Method.reset - def AllReferences.[](name) - @@refs[name] + if options.all_one_file + RDoc::Generator::HTMLInOne.new options + else + new options end + end - def AllReferences.keys - @@refs.keys - end + class << self + protected :new end ## - # Subclass of the RDoc::Markup::ToHtml class that supports looking up words - # in the AllReferences list. Those that are found (like AllReferences in - # this comment) will be hyperlinked - - class HyperlinkHtml < RDoc::Markup::ToHtml - - ## - # We need to record the html path of our caller so we can generate - # correct relative paths for any hyperlinks that we find - def initialize(from_path, context, options) - super() - - @from_path = from_path - - @parent_name = context.parent_name - @parent_name += "::" if @parent_name - @context = context - - @options = options - end - - ## - # We're invoked when any text matches the CROSSREF pattern - # (defined in MarkUp). If we fine the corresponding reference, - # generate a hyperlink. If the name we're looking for contains - # no punctuation, we look for it up the module/class chain. For - # example, HyperlinkHtml is found, even without the Generator:: - # prefix, because we look for it in module Generator first. - - def handle_special_CROSSREF(special) - name = special.text - if name[0,1] == '#' - lookup = name[1..-1] - name = lookup unless @options.show_hash - else - lookup = name - end - - # Find class, module, or method in class or module. - if /([A-Z]\w*)[.\#](\w+[!?=]?)/ =~ lookup - container = $1 - method = $2 - ref = @context.find_symbol(container, method) - elsif /([A-Za-z]\w*)[.\#](\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?)/ =~ lookup - container = $1 - method = $2 - ref = @context.find_symbol(container, method) - else - ref = @context.find_symbol(lookup) - end - - if ref and ref.document_self - "<a href=\"#{ref.as_href(@from_path)}\">#{name}</a>" - else - name - end - end - - ## - # Generate a hyperlink for url, labeled with text. Handle the - # special cases for img: and link: described under handle_special_HYPEDLINK - - def gen_url(url, text) - if url =~ /([A-Za-z]+):(.*)/ - type = $1 - path = $2 - else - type = "http" - path = url - url = "http://#{url}" - end - - if type == "link" - if path[0,1] == '#' # is this meaningful? - url = path - else - url = HTML.gen_url(@from_path, path) - end - end - - if (type == "http" || type == "link") && - url =~ /\.(gif|png|jpg|jpeg|bmp)$/ - - "<img src=\"#{url}\" />" - else - "<a href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>" - end - end - - ## - # And we're invoked with a potential external hyperlink mailto: - # just gets inserted. http: links are checked to see if they - # reference an image. If so, that image gets inserted using an - # <img> tag. Otherwise a conventional <a href> is used. We also - # support a special type of hyperlink, link:, which is a reference - # to a local file whose path is relative to the --op directory. - - def handle_special_HYPERLINK(special) - url = special.text - gen_url(url, url) - end - - ## - # Here's a hypedlink where the label is different to the URL - # <label>[url] - - def handle_special_TIDYLINK(special) - text = special.text -# unless text =~ /(\S+)\[(.*?)\]/ - unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/ - return text - end - label = $1 - url = $2 - gen_url(url, label) - end + # Set up a new HTML generator. Basically all we do here is load up the + # correct output temlate + def initialize(options) #:not-new: + @options = options + load_html_template end ## - # Handle common markup tasks for the various Html classes - - module MarkUp - - ## - # Convert a string in markup format into HTML. We keep a cached - # RDoc::Markup object lying around after the first time we're - # called per object. - - def markup(str, remove_para=false) - return '' unless str - unless defined? @markup - @markup = RDoc::Markup.new - - # class names, variable names, or instance variables - @markup.add_special(/( - \w+(::\w+)*[.\#]\w+(\([\.\w+\*\/\+\-\=\<\>]+\))? # A::B.meth(**) (for operator in Fortran95) - | \#\w+(\([.\w\*\/\+\-\=\<\>]+\))? # meth(**) (for operator in Fortran95) - | \b([A-Z]\w*(::\w+)*[.\#]\w+) # A::B.meth - | \b([A-Z]\w+(::\w+)*) # A::B.. - | \#\w+[!?=]? # #meth_name - | \b\w+([_\/\.]+\w+)*[!?=]? # meth_name - )/x, - :CROSSREF) - - # external hyperlinks - @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK) - - # and links of the form <text>[<url>] - @markup.add_special(/(((\{.*?\})|\b\S+?)\[\S+?\.\S+?\])/, :TIDYLINK) -# @markup.add_special(/\b(\S+?\[\S+?\.\S+?\])/, :TIDYLINK) - - end - unless defined? @html_formatter - @html_formatter = HyperlinkHtml.new(self.path, self, @options) - end - - # Convert leading comment markers to spaces, but only - # if all non-blank lines have them + # Build the initial indices and output objects + # based on an array of TopLevel objects containing + # the extracted information. + + def generate(toplevels) + @toplevels = toplevels + @files = [] + @classes = [] + + write_style_sheet + gen_sub_directories() + build_indices + generate_html + end - if str =~ /^(?>\s*)[^\#]/ - content = str - else - content = str.gsub(/^\s*(#+)/) { $1.tr('#',' ') } - end + private - res = @markup.convert(content, @html_formatter) - if remove_para - res.sub!(/^<p>/, '') - res.sub!(/<\/p>$/, '') - end - res - end + ## + # Load up the HTML template specified in the options. + # If the template name contains a slash, use it literally - ## - # Qualify a stylesheet URL; if if +css_name+ does not begin with '/' or - # 'http[s]://', prepend a prefix relative to +path+. Otherwise, return it - # unmodified. + def load_html_template + template = @options.template - def style_url(path, css_name=nil) -# $stderr.puts "style_url( #{path.inspect}, #{css_name.inspect} )" - css_name ||= CSS_NAME - if %r{^(https?:/)?/} =~ css_name - return css_name - else - return HTML.gen_url(path, css_name) - end + unless template =~ %r{/|\\} then + template = File.join('rdoc', 'generator', @options.generator.key, + template) end - ## - # Build a webcvs URL with the given 'url' argument. URLs with a '%s' in them - # get the file's path sprintfed into them; otherwise they're just catenated - # together. + require template - def cvs_url(url, full_path) - if /%s/ =~ url - return sprintf( url, full_path ) - else - return url + full_path - end - end + @template = self.class.const_get @options.template.upcase + @options.template_class = @template + rescue LoadError + $stderr.puts "Could not find HTML template '#{template}'" + exit 99 end ## - # A Context is built by the parser to represent a container: contexts - # hold classes, modules, methods, require lists and include lists. - # ClassModule and TopLevel are the context objects we process here - - class ContextUser + # Write out the style sheet used by the main frames - include MarkUp + def write_style_sheet + return unless @template.constants.include? :STYLE or + @template.constants.include? 'STYLE' - attr_reader :context + template = RDoc::TemplatePage.new @template::STYLE - def initialize(context, options) - @context = context - @options = options + unless @options.css then + open RDoc::Generator::CSS_NAME, 'w' do |f| + values = {} - # HACK ugly - @template = options.template_class - end - - ## - # convenience method to build a hyperlink - - def href(link, cls, name) - %{<a href="#{link}" class="#{cls}">#{name}</a>} #" - end - - ## - # Returns a reference to outselves to be used as an href= the form depends - # on whether we're all in one file or in multiple files - - def as_href(from_path) - if @options.all_one_file - "#" + path - else - HTML.gen_url(from_path, path) - end - end - - ## - # Create a list of HtmlMethod objects for each method in the corresponding - # context object. If the @options.show_all variable is set (corresponding - # to the <tt>--all</tt> option, we include all methods, otherwise just the - # public ones. - - def collect_methods - list = @context.method_list - unless @options.show_all - list = list.find_all {|m| m.visibility == :public || m.visibility == :protected || m.force_documentation } - end - @methods = list.collect {|m| HtmlMethod.new(m, self, @options) } - end - - ## - # Build a summary list of all the methods in this context - - def build_method_summary_list(path_prefix="") - collect_methods unless @methods - meths = @methods.sort - res = [] - meths.each do |meth| - res << { - "name" => CGI.escapeHTML(meth.name), - "aref" => "#{path_prefix}\##{meth.aref}" - } - end - res - end - - ## - # Build a list of aliases for which we couldn't find a - # corresponding method - - def build_alias_summary_list(section) - values = [] - @context.aliases.each do |al| - next unless al.section == section - res = { - 'old_name' => al.old_name, - 'new_name' => al.new_name, - } - if al.comment && !al.comment.empty? - res['desc'] = markup(al.comment, true) - end - values << res - end - values - end - - ## - # Build a list of constants - - def build_constants_summary_list(section) - values = [] - @context.constants.each do |co| - next unless co.section == section - res = { - 'name' => co.name, - 'value' => CGI.escapeHTML(co.value) - } - res['desc'] = markup(co.comment, true) if co.comment && !co.comment.empty? - values << res - end - values - end - - def build_requires_list(context) - potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] } - end - - def build_include_list(context) - potentially_referenced_list(context.includes) - end - - ## - # Build a list from an array of <i>Htmlxxx</i> items. Look up each - # in the AllReferences hash: if we find a corresponding entry, - # we generate a hyperlink to it, otherwise just output the name. - # However, some names potentially need massaging. For example, - # you may require a Ruby file without the .rb extension, - # but the file names we know about may have it. To deal with - # this, we pass in a block which performs the massaging, - # returning an array of alternative names to match - - def potentially_referenced_list(array) - res = [] - array.each do |i| - ref = AllReferences[i.name] -# if !ref -# container = @context.parent -# while !ref && container -# name = container.name + "::" + i.name -# ref = AllReferences[name] -# container = container.parent -# end -# end - - ref = @context.find_symbol(i.name) - ref = ref.viewer if ref - - if !ref && block_given? - possibles = yield(i.name) - while !ref and !possibles.empty? - ref = AllReferences[possibles.shift] - end - end - h_name = CGI.escapeHTML(i.name) - if ref and ref.document_self - path = url(ref.path) - res << { "name" => h_name, "aref" => path } - else - res << { "name" => h_name } - end - end - res - end - - ## - # Build an array of arrays of method details. The outer array has up - # to six entries, public, private, and protected for both class - # methods, the other for instance methods. The inner arrays contain - # a hash for each method - - def build_method_detail_list(section) - outer = [] - - methods = @methods.sort - for singleton in [true, false] - for vis in [ :public, :protected, :private ] - res = [] - methods.each do |m| - if m.section == section and - m.document_self and - m.visibility == vis and - m.singleton == singleton - row = {} - if m.call_seq - row["callseq"] = m.call_seq.gsub(/->/, '→') - else - row["name"] = CGI.escapeHTML(m.name) - row["params"] = m.params - end - desc = m.description.strip - row["m_desc"] = desc unless desc.empty? - row["aref"] = m.aref - row["visibility"] = m.visibility.to_s - - alias_names = [] - m.aliases.each do |other| - if other.viewer # won't be if the alias is private - alias_names << { - 'name' => other.name, - 'aref' => other.viewer.as_href(path) - } - end - end - unless alias_names.empty? - row["aka"] = alias_names - end - - if @options.inline_source - code = m.source_code - row["sourcecode"] = code if code - else - code = m.src_url - if code - row["codeurl"] = code - row["imgurl"] = m.img_url - end - end - res << row - end - end - if res.size > 0 - outer << { - "type" => vis.to_s.capitalize, - "category" => singleton ? "Class" : "Instance", - "methods" => res - } - end - end - end - outer - end - - ## - # Build the structured list of classes and modules contained - # in this context. - - def build_class_list(level, from, section, infile=nil) - res = "" - prefix = " ::" * level; - - from.modules.sort.each do |mod| - next unless mod.section == section - next if infile && !mod.defined_in?(infile) - if mod.document_self - res << - prefix << - "Module " << - href(url(mod.viewer.path), "link", mod.full_name) << - "<br />\n" << - build_class_list(level + 1, mod, section, infile) + if @template.constants.include? :FONTS or + @template.constants.include? 'FONTS' then + values["fonts"] = @template::FONTS end - end - - from.classes.sort.each do |cls| - next unless cls.section == section - next if infile && !cls.defined_in?(infile) - if cls.document_self - res << - prefix << - "Class " << - href(url(cls.viewer.path), "link", cls.full_name) << - "<br />\n" << - build_class_list(level + 1, cls, section, infile) - end - end - - res - end - - def url(target) - HTML.gen_url(path, target) - end - - def aref_to(target) - if @options.all_one_file - "#" + target - else - url(target) - end - end - - def document_self - @context.document_self - end - - def diagram_reference(diagram) - res = diagram.gsub(/((?:src|href)=")(.*?)"/) { - $1 + url($2) + '"' - } - res - end - ## - # Find a symbol in ourselves or our parent - - def find_symbol(symbol, method=nil) - res = @context.find_symbol(symbol, method) - if res - res = res.viewer - end - res - end - - ## - # create table of contents if we contain sections - - def add_table_of_sections - toc = [] - @context.sections.each do |section| - if section.title - toc << { - 'secname' => section.title, - 'href' => section.sequence - } - end + template.write_html_on(f, values) end - - @values['toc'] = toc unless toc.empty? end - end ## - # Wrap a ClassModule context - - class HtmlClass < ContextUser - - attr_reader :path - - def initialize(context, html_file, prefix, options) - super(context, options) - - @html_file = html_file - @is_module = context.is_module? - @values = {} - - context.viewer = self - - if options.all_one_file - @path = context.full_name - else - @path = http_url(context.full_name, prefix) - end - - collect_methods - - AllReferences.add(name, self) - end - - ## - # Returns the relative file name to store this class in, which is also its - # url - - def http_url(full_name, prefix) - path = full_name.dup - if path['<<'] - path.gsub!(/<<\s*(\w*)/) { "from-#$1" } - end - File.join(prefix, path.split("::")) + ".html" - end - - def name - @context.full_name - end - - def parent_name - @context.parent.full_name - end - - def index_name - name - end - - def write_on(f) - value_hash - template = RDoc::TemplatePage.new(@template::BODY, - @template::CLASS_PAGE, - @template::METHOD_LIST) - template.write_html_on(f, @values) - end - - def value_hash - class_attribute_values - add_table_of_sections - - @values["charset"] = @options.charset - @values["style_url"] = style_url(path, @options.css) - - d = markup(@context.comment) - @values["description"] = d unless d.empty? - - ml = build_method_summary_list @path - @values["methods"] = ml unless ml.empty? - - il = build_include_list(@context) - @values["includes"] = il unless il.empty? - - @values["sections"] = @context.sections.map do |section| - - secdata = { - "sectitle" => section.title, - "secsequence" => section.sequence, - "seccomment" => markup(section.comment) - } - - al = build_alias_summary_list(section) - secdata["aliases"] = al unless al.empty? - - co = build_constants_summary_list(section) - secdata["constants"] = co unless co.empty? - - al = build_attribute_list(section) - secdata["attributes"] = al unless al.empty? - - cl = build_class_list(0, @context, section) - secdata["classlist"] = cl unless cl.empty? - - mdl = build_method_detail_list(section) - secdata["method_list"] = mdl unless mdl.empty? - - secdata - end - - @values - end - - def build_attribute_list(section) - atts = @context.attributes.sort - res = [] - atts.each do |att| - next unless att.section == section - if att.visibility == :public || att.visibility == :protected || @options.show_all - entry = { - "name" => CGI.escapeHTML(att.name), - "rw" => att.rw, - "a_desc" => markup(att.comment, true) - } - unless att.visibility == :public || att.visibility == :protected - entry["rw"] << "-" - end - res << entry - end - end - res - end - - def class_attribute_values - h_name = CGI.escapeHTML(name) - - @values["path"] = @path - @values["classmod"] = @is_module ? "Module" : "Class" - @values["title"] = "#{@values['classmod']}: #{h_name}" - - c = @context - c = c.parent while c and !c.diagram - if c && c.diagram - @values["diagram"] = diagram_reference(c.diagram) - end - - @values["full_name"] = h_name - - parent_class = @context.superclass - - if parent_class - @values["parent"] = CGI.escapeHTML(parent_class) - - if parent_name - lookup = parent_name + "::" + parent_class - else - lookup = parent_class - end - - parent_url = AllReferences[lookup] || AllReferences[parent_class] - - if parent_url and parent_url.document_self - @values["par_url"] = aref_to(parent_url.path) - end - end - - files = [] - @context.in_files.each do |f| - res = {} - full_path = CGI.escapeHTML(f.file_absolute_name) - - res["full_path"] = full_path - res["full_path_url"] = aref_to(f.viewer.path) if f.document_self - - if @options.webcvs - res["cvsurl"] = cvs_url( @options.webcvs, full_path ) - end - - files << res - end - - @values['infiles'] = files - end - - def <=>(other) - self.name <=> other.name - end + # See the comments at the top for a description of the directory structure + + def gen_sub_directories + FileUtils.mkdir_p RDoc::Generator::FILE_DIR + FileUtils.mkdir_p RDoc::Generator::CLASS_DIR + rescue + $stderr.puts $!.message + exit 1 + end + def build_indices + @files, @classes = RDoc::Generator::Context.build_indicies(@toplevels, + @options) end ## - # Handles the mapping of a file's information to HTML. In reality, - # a file corresponds to a +TopLevel+ object, containing modules, - # classes, and top-level methods. In theory it _could_ contain - # attributes and aliases, but we ignore these for now. - - class HtmlFile < ContextUser - - attr_reader :path - attr_reader :name - - def initialize(context, options, file_dir) - super(context, options) - - @values = {} - - if options.all_one_file - @path = filename_to_label - else - @path = http_url(file_dir) - end - - @name = @context.file_relative_name - - collect_methods - AllReferences.add(name, self) - context.viewer = self - end - - def http_url(file_dir) - File.join(file_dir, @context.file_relative_name.tr('.', '_')) + - ".html" - end - - def filename_to_label - @context.file_relative_name.gsub(/%|\/|\?|\#/) do |s| - '%%%x' % s[0].unpack('C') - end - end - - def index_name - name - end - - def parent_name - nil - end - - def value_hash - file_attribute_values - add_table_of_sections - - @values["charset"] = @options.charset - @values["href"] = path - @values["style_url"] = style_url(path, @options.css) - - if @context.comment - d = markup(@context.comment) - @values["description"] = d if d.size > 0 - end - - ml = build_method_summary_list - @values["methods"] = ml unless ml.empty? - - il = build_include_list(@context) - @values["includes"] = il unless il.empty? - - rl = build_requires_list(@context) - @values["requires"] = rl unless rl.empty? - - if @options.promiscuous - file_context = nil - else - file_context = @context - end - - - @values["sections"] = @context.sections.map do |section| - - secdata = { - "sectitle" => section.title, - "secsequence" => section.sequence, - "seccomment" => markup(section.comment) - } - - cl = build_class_list(0, @context, section, file_context) - @values["classlist"] = cl unless cl.empty? - - mdl = build_method_detail_list(section) - secdata["method_list"] = mdl unless mdl.empty? - - al = build_alias_summary_list(section) - secdata["aliases"] = al unless al.empty? - - co = build_constants_summary_list(section) - @values["constants"] = co unless co.empty? - - secdata - end - - @values - end - - def write_on(f) - value_hash - - template = RDoc::TemplatePage.new(@template::BODY, - @template::FILE_PAGE, - @template::METHOD_LIST) - - template.write_html_on(f, @values) - end - - def file_attribute_values - full_path = @context.file_absolute_name - short_name = File.basename(full_path) - - @values["title"] = CGI.escapeHTML("File: #{short_name}") - - if @context.diagram - @values["diagram"] = diagram_reference(@context.diagram) - end - - @values["short_name"] = CGI.escapeHTML(short_name) - @values["full_path"] = CGI.escapeHTML(full_path) - @values["dtm_modified"] = @context.file_stat.mtime.to_s - - if @options.webcvs - @values["cvsurl"] = cvs_url( @options.webcvs, @values["full_path"] ) - end - end - - def <=>(other) - self.name <=> other.name - end - + # Generate all the HTML + + def generate_html + # the individual descriptions for files and classes + gen_into(@files) + gen_into(@classes) + # and the index files + gen_file_index + gen_class_index + gen_method_index + gen_main_index + + # this method is defined in the template file + write_extra_pages if defined? write_extra_pages end - class HtmlMethod - - include MarkUp - - attr_reader :context - attr_reader :src_url - attr_reader :img_url - attr_reader :source_code - - @@seq = "M000000" - - @@all_methods = [] - - def self.reset - @@all_methods = [] - end - - def initialize(context, html_class, options) - @context = context - @html_class = html_class - @options = options - - # HACK ugly - @template = options.template_class - - @@seq = @@seq.succ - @seq = @@seq - @@all_methods << self - - context.viewer = self - - if (ts = @context.token_stream) - @source_code = markup_code(ts) - unless @options.inline_source - @src_url = create_source_code_file(@source_code) - @img_url = HTML.gen_url(path, 'source.png') - end - end - - AllReferences.add(name, self) - end - - ## - # Returns a reference to outselves to be used as an href= the form depends - # on whether we're all in one file or in multiple files - - def as_href(from_path) - if @options.all_one_file - "#" + path - else - HTML.gen_url(from_path, path) - end - end - - def name - @context.name - end - - def section - @context.section - end - - def index_name - "#{@context.name} (#{@html_class.name})" - end - - def parent_name - if @context.parent.parent - @context.parent.parent.full_name - else - nil - end - end - - def aref - @seq - end - - def path - if @options.all_one_file - aref - else - @html_class.path + "#" + aref - end - end - - def description - markup(@context.comment) - end - - def visibility - @context.visibility - end - - def singleton - @context.singleton - end - - def call_seq - cs = @context.call_seq - if cs - cs.gsub(/\n/, "<br />\n") - else - nil + def gen_into(list) + list.each do |item| + if item.document_self + op_file = item.path + FileUtils.mkdir_p(File.dirname(op_file)) + open(op_file, "w") { |file| item.write_on(file) } end end - def params - # params coming from a call-seq in 'C' will start with the - # method name - if p !~ /^\w/ - p = @context.params.gsub(/\s*\#.*/, '') - p = p.tr("\n", " ").squeeze(" ") - p = "(" + p + ")" unless p[0] == ?( - - if (block = @context.block_params) - # If this method has explicit block parameters, remove any - # explicit &block - - p.sub!(/,?\s*&\w+/, '') - - block.gsub!(/\s*\#.*/, '') - block = block.tr("\n", " ").squeeze(" ") - if block[0] == ?( - block.sub!(/^\(/, '').sub!(/\)/, '') - end - p << " {|#{block.strip}| ...}" - end - end - CGI.escapeHTML(p) - end - - def create_source_code_file(code_body) - meth_path = @html_class.path.sub(/\.html$/, '.src') - FileUtils.mkdir_p(meth_path) - file_path = File.join(meth_path, @seq) + ".html" - - template = RDoc::TemplatePage.new(@template::SRC_PAGE) - File.open(file_path, "w") do |f| - values = { - 'title' => CGI.escapeHTML(index_name), - 'code' => code_body, - 'style_url' => style_url(file_path, @options.css), - 'charset' => @options.charset - } - template.write_html_on(f, values) - end - HTML.gen_url(path, file_path) - end - - def self.all_methods - @@all_methods - end + end - def <=>(other) - @context <=> other.context - end + def gen_file_index + gen_an_index @files, 'Files', @template::FILE_INDEX, "fr_file_index.html" + end - ## - # Given a sequence of source tokens, mark up the source code - # to make it look purty. - - def markup_code(tokens) - src = "" - tokens.each do |t| - next unless t - # p t.class -# style = STYLE_MAP[t.class] - style = case t - when RubyToken::TkCONSTANT then "ruby-constant" - when RubyToken::TkKW then "ruby-keyword kw" - when RubyToken::TkIVAR then "ruby-ivar" - when RubyToken::TkOp then "ruby-operator" - when RubyToken::TkId then "ruby-identifier" - when RubyToken::TkNode then "ruby-node" - when RubyToken::TkCOMMENT then "ruby-comment cmt" - when RubyToken::TkREGEXP then "ruby-regexp re" - when RubyToken::TkSTRING then "ruby-value str" - when RubyToken::TkVal then "ruby-value" - else - nil - end - - text = CGI.escapeHTML(t.text) - - if style - src << "<span class=\"#{style}\">#{text}</span>" - else - src << text - end - end + def gen_class_index + gen_an_index(@classes, 'Classes', @template::CLASS_INDEX, + "fr_class_index.html") + end - add_line_numbers(src) if @options.include_line_numbers - src - end + def gen_method_index + gen_an_index(RDoc::Generator::Method.all_methods, 'Methods', + @template::METHOD_INDEX, "fr_method_index.html") + end - ## - # We rely on the fact that the first line of a source code listing has - # # File xxxxx, line dddd - - def add_line_numbers(src) - if src =~ /\A.*, line (\d+)/ - first = $1.to_i - 1 - last = first + src.count("\n") - size = last.to_s.length - real_fmt = "%#{size}d: " - fmt = " " * (size+2) - src.gsub!(/^/) do - res = sprintf(fmt, first) - first += 1 - fmt = real_fmt - res - end + def gen_an_index(collection, title, template, filename) + template = RDoc::TemplatePage.new @template::FR_INDEX_BODY, template + res = [] + collection.sort.each do |f| + if f.document_self + res << { "href" => f.path, "name" => f.index_name } end end - def document_self - @context.document_self - end - - def aliases - @context.aliases - end + values = { + "entries" => res, + 'list_title' => CGI.escapeHTML(title), + 'index_url' => main_url, + 'charset' => @options.charset, + 'style_url' => style_url('', @options.css), + } - def find_symbol(symbol, method=nil) - res = @context.parent.find_symbol(symbol, method) - if res - res = res.viewer - end - res + open filename, 'w' do |f| + template.write_html_on(f, values) end - end ## - # We're responsible for generating all the HTML files - # from the object tree defined in code_objects.rb. We - # generate: - # - # [files] an html file for each input file given. These - # input files appear as objects of class - # TopLevel - # - # [classes] an html file for each class or module encountered. - # These classes are not grouped by file: if a file - # contains four classes, we'll generate an html - # file for the file itself, and four html files - # for the individual classes. - # - # [indices] we generate three indices for files, classes, - # and methods. These are displayed in a browser - # like window with three index panes across the - # top and the selected description below - # - # 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. - - class HTML - - include MarkUp + # The main index page is mostly a template frameset, but includes the + # initial page. If the <tt>--main</tt> option was given, we use this as + # our main page, otherwise we use the first file specified on the command + # line. - ## - # Converts a target url to one that is relative to a given path + def gen_main_index + template = RDoc::TemplatePage.new @template::INDEX - def self.gen_url(path, target) - from = File.dirname(path) - to, to_file = File.split(target) + open 'index.html', 'w' do |f| + classes = @classes.sort.map { |klass| klass.value_hash } - from = from.split("/") - to = to.split("/") + values = { + 'main_page' => @main_page, + 'initial_page' => main_url, + 'style_url' => style_url('', @options.css), + 'title' => CGI.escapeHTML(@options.title), + 'charset' => @options.charset, + 'classes' => classes, + } - while from.size > 0 and to.size > 0 and from[0] == to[0] - from.shift - to.shift - end + values['inline_source'] = @options.inline_source - from.fill("..") - from.concat(to) - from << to_file - File.join(*from) + template.write_html_on f, values end + end - ## - # Generator may need to return specific subclasses depending on the - # options they are passed. Because of this we create them using a factory - - def self.for(options) - AllReferences.reset - HtmlMethod.reset - - if options.all_one_file - HTMLInOne.new(options) + ## + # Returns the url of the main page + + def main_url + @main_page = @options.main_page + @main_page_ref = nil + if @main_page + @main_page_ref = AllReferences[@main_page] + if @main_page_ref then + @main_page_path = @main_page_ref.path else - HTML.new(options) + $stderr.puts "Could not find main page #{@main_page}" end end - class <<self - protected :new + unless @main_page_path then + file = @files.find { |file| file.document_self } + @main_page_path = file.path if file end - ## - # Set up a new HTML generator. Basically all we do here is load up the - # correct output temlate - - def initialize(options) #:not-new: - @options = options - load_html_template - end - - ## - # Build the initial indices and output objects - # based on an array of TopLevel objects containing - # the extracted information. - - def generate(toplevels) - @toplevels = toplevels - @files = [] - @classes = [] - - write_style_sheet - gen_sub_directories() - build_indices - generate_html - end - - private - - ## - # Load up the HTML template specified in the options. - # If the template name contains a slash, use it literally - - def load_html_template - template = @options.template - - unless template =~ %r{/|\\} then - template = File.join('rdoc', 'generator', @options.generator.key, - template) - end - - require template - - @template = self.class.const_get @options.template.upcase - @options.template_class = @template - - rescue LoadError - $stderr.puts "Could not find HTML template '#{template}'" - exit 99 - end - - ## - # Write out the style sheet used by the main frames - - def write_style_sheet - return unless @template.constants.include? :STYLE or - @template.constants.include? 'STYLE' - - template = RDoc::TemplatePage.new @template::STYLE - - unless @options.css then - File.open(CSS_NAME, "w") do |f| - values = {} - - if @template.constants.include? :FONTS or - @template.constants.include? 'FONTS' then - values["fonts"] = @template::FONTS - end - - template.write_html_on(f, values) - end - end - end - - ## - # See the comments at the top for a description of the directory structure - - def gen_sub_directories - FileUtils.mkdir_p(FILE_DIR) - FileUtils.mkdir_p(CLASS_DIR) - rescue - $stderr.puts $!.message + unless @main_page_path then + $stderr.puts "Couldn't find anything to document" + $stderr.puts "Perhaps you've used :stopdoc: in all classes" exit 1 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) - - def build_indices - @toplevels.each do |toplevel| - @files << HtmlFile.new(toplevel, @options, FILE_DIR) - end - - RDoc::TopLevel.all_classes_and_modules.each do |cls| - build_class_list(cls, @files[0], CLASS_DIR) - end - end - - def build_class_list(from, html_file, class_dir) - @classes << HtmlClass.new(from, html_file, class_dir, @options) - from.each_classmodule do |mod| - build_class_list(mod, html_file, class_dir) - end - end - - ## - # Generate all the HTML - - def generate_html - # the individual descriptions for files and classes - gen_into(@files) - gen_into(@classes) - # and the index files - gen_file_index - gen_class_index - gen_method_index - gen_main_index - - # this method is defined in the template file - write_extra_pages if defined? write_extra_pages - end - - def gen_into(list) - list.each do |item| - if item.document_self - op_file = item.path - FileUtils.mkdir_p(File.dirname(op_file)) - File.open(op_file, "w") { |file| item.write_on(file) } - end - end - - end - - def gen_file_index - gen_an_index @files, 'Files', @template::FILE_INDEX, "fr_file_index.html" - end - - def gen_class_index - gen_an_index(@classes, 'Classes', @template::CLASS_INDEX, - "fr_class_index.html") - end - - def gen_method_index - gen_an_index(HtmlMethod.all_methods, 'Methods', @template::METHOD_INDEX, - "fr_method_index.html") - end - - def gen_an_index(collection, title, template, filename) - template = RDoc::TemplatePage.new @template::FR_INDEX_BODY, template - res = [] - collection.sort.each do |f| - if f.document_self - res << { "href" => f.path, "name" => f.index_name } - end - end - - values = { - "entries" => res, - 'list_title' => CGI.escapeHTML(title), - 'index_url' => main_url, - 'charset' => @options.charset, - 'style_url' => style_url('', @options.css), - } - - File.open(filename, "w") do |f| - template.write_html_on(f, values) - end - end - - ## - # The main index page is mostly a template frameset, but includes the - # initial page. If the <tt>--main</tt> option was given, we use this as - # our main page, otherwise we use the first file specified on the command - # line. - - def gen_main_index - template = RDoc::TemplatePage.new @template::INDEX - - open 'index.html', 'w' do |f| - classes = @classes.sort.map { |klass| klass.value_hash } - - values = { - 'main_page' => @main_page, - 'initial_page' => main_url, - 'style_url' => style_url('', @options.css), - 'title' => CGI.escapeHTML(@options.title), - 'charset' => @options.charset, - 'classes' => classes, - } - - values['inline_source'] = @options.inline_source - - template.write_html_on f, values - end - end - - ## - # Returns the url of the main page - - def main_url - @main_page = @options.main_page - @main_page_ref = nil - if @main_page - @main_page_ref = AllReferences[@main_page] - if @main_page_ref then - @main_page_path = @main_page_ref.path - else - $stderr.puts "Could not find main page #{@main_page}" - end - end - - unless @main_page_path then - file = @files.find { |file| file.document_self } - @main_page_path = file.path if file - end - - unless @main_page_path then - $stderr.puts "Couldn't find anything to document" - $stderr.puts "Perhaps you've used :stopdoc: in all classes" - exit 1 - end - - @main_page_path - end - + @main_page_path end - class HTMLInOne < HTML - - def initialize(*args) - super - end - - ## - # Build the initial indices and output objects - # based on an array of TopLevel objects containing - # the extracted information. - - def generate(info) - @toplevels = info - @files = [] - @classes = [] - @hyperlinks = {} +end - build_indices - generate_xml - end +class RDoc::Generator::HTMLInOne < RDoc::Generator::HTML - ## - # 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) + def initialize(*args) + super + end - def build_indices + ## + # Build the initial indices and output objects + # based on an array of TopLevel objects containing + # the extracted information. - @toplevels.each do |toplevel| - @files << HtmlFile.new(toplevel, @options, FILE_DIR) - end + def generate(info) + @toplevels = info + @hyperlinks = {} - RDoc::TopLevel.all_classes_and_modules.each do |cls| - build_class_list(cls, @files[0], CLASS_DIR) - end - end + build_indices + generate_xml + end - def build_class_list(from, html_file, class_dir) - @classes << HtmlClass.new(from, html_file, class_dir, @options) - from.each_classmodule do |mod| - build_class_list(mod, html_file, class_dir) - end - end + ## + # Generate: + # + # * a list of RDoc::Generator::File objects for each TopLevel object. + # * a list of RDoc::Generator::Class 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) + + def build_indices + @files, @classes = RDoc::Generator::Context.build_indices(@toplevels, + @options) + end - ## - # Generate all the HTML. For the one-file case, we generate - # all the information in to one big hash + ## + # Generate all the HTML. For the one-file case, we generate + # all the information in to one big hash - def generate_xml - values = { - 'charset' => @options.charset, - 'files' => gen_into(@files), - 'classes' => gen_into(@classes), - 'title' => CGI.escapeHTML(@options.title), - } + def generate_xml + values = { + 'charset' => @options.charset, + 'files' => gen_into(@files), + 'classes' => gen_into(@classes), + 'title' => CGI.escapeHTML(@options.title), + } - # this method is defined in the template file - write_extra_pages if defined? write_extra_pages + # this method is defined in the template file + write_extra_pages if defined? write_extra_pages - template = RDoc::TemplatePage.new @template::ONE_PAGE + template = RDoc::TemplatePage.new @template::ONE_PAGE - if @options.op_name - opfile = File.open(@options.op_name, "w") - else - opfile = $stdout - end - template.write_html_on(opfile, values) + if @options.op_name + opfile = open @options.op_name, 'w' + else + opfile = $stdout end + template.write_html_on(opfile, values) + end - def gen_into(list) - res = [] - list.each do |item| - res << item.value_hash - end - res + def gen_into(list) + res = [] + list.each do |item| + res << item.value_hash end + res + end - def gen_file_index - gen_an_index(@files, 'Files') - end + def gen_file_index + gen_an_index(@files, 'Files') + end - def gen_class_index - gen_an_index(@classes, 'Classes') - end + def gen_class_index + gen_an_index(@classes, 'Classes') + end - def gen_method_index - gen_an_index(HtmlMethod.all_methods, 'Methods') - end + def gen_method_index + gen_an_index(RDoc::Generator::Method.all_methods, 'Methods') + end - def gen_an_index(collection, title) - res = [] - collection.sort.each do |f| - if f.document_self - res << { "href" => f.path, "name" => f.index_name } - end + def gen_an_index(collection, title) + res = [] + collection.sort.each do |f| + if f.document_self + res << { "href" => f.path, "name" => f.index_name } end - - return { - "entries" => res, - 'list_title' => title, - 'index_url' => main_url, - } end + return { + "entries" => res, + 'list_title' => title, + 'index_url' => main_url, + } end end + diff --git a/lib/rdoc/generator/html/html.rb b/lib/rdoc/generator/html/html.rb index 0a0b754919..8343454d30 100644 --- a/lib/rdoc/generator/html/html.rb +++ b/lib/rdoc/generator/html/html.rb @@ -478,14 +478,14 @@ EOF <div class="name-list"> <table summary="Constants"> -<% values["constants"].each do |constants| $stderr.puts({ :constants => constants }.inspect) %> +<% values["constants"].each do |constants| %> <tr class="top-aligned-row context-row"> - <td class="context-item-name"><%= values["name"] %></td> + <td class="context-item-name"><%= constants["name"] %></td> <td>=</td> - <td class="context-item-value"><%= values["value"] %></td> + <td class="context-item-value"><%= constants["value"] %></td> <% if values["desc"] then %> <td width="3em"> </td> - <td class="context-item-desc"><%= values["desc"] %></td> + <td class="context-item-desc"><%= constants["desc"] %></td> <% end %> </tr> <% end # values["constants"] %> |