diff options
Diffstat (limited to 'lib/rdoc/generators')
| -rw-r--r-- | lib/rdoc/generators/chm_generator.rb | 55 | ||||
| -rw-r--r-- | lib/rdoc/generators/html_generator.rb | 357 | ||||
| -rw-r--r-- | lib/rdoc/generators/ri_generator.rb | 82 | ||||
| -rw-r--r-- | lib/rdoc/generators/xml_generator.rb | 16 |
4 files changed, 248 insertions, 262 deletions
diff --git a/lib/rdoc/generators/chm_generator.rb b/lib/rdoc/generators/chm_generator.rb index 51eeda8dd1..354a444689 100644 --- a/lib/rdoc/generators/chm_generator.rb +++ b/lib/rdoc/generators/chm_generator.rb @@ -6,12 +6,13 @@ module Generators HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe" + ## # Standard generator factory + def CHMGenerator.for(options) CHMGenerator.new(options) end - def initialize(*args) super @op_name = @options.op_name || "rdoc" @@ -22,32 +23,35 @@ module Generators stat = File.stat(HHC_PATH) rescue $stderr << - "\n.chm output generation requires that Microsoft's Html Help\n" << - "Workshop is installed. RDoc looks for it in:\n\n " << - HHC_PATH << - "\n\nYou can download a copy for free from:\n\n" << - " http://msdn.microsoft.com/library/default.asp?" << - "url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp\n\n" - + "\n.chm output generation requires that Microsoft's Html Help\n" << + "Workshop is installed. RDoc looks for it in:\n\n " << + HHC_PATH << + "\n\nYou can download a copy for free from:\n\n" << + " http://msdn.microsoft.com/library/default.asp?" << + "url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp\n\n" + exit 99 end - # Generate the html as normal, then wrap it - # in a help project + ## + # Generate the html as normal, then wrap it in a help project + def generate(info) super @project_name = @op_name + ".hhp" create_help_project end - # The project contains the project file, a table of contents - # and an index + ## + # The project contains the project file, a table of contents and an index + def create_help_project create_project_file create_contents_and_index compile_project end + ## # The project file links together all the various # files that go to make up the help. @@ -56,16 +60,17 @@ module Generators values = { "title" => @options.title, "opname" => @op_name } files = [] @files.each do |f| - files << { "html_file_name" => f.path } + files << { "html_file_name" => f.path } end values['all_html_files'] = files - + File.open(@project_name, "w") do |f| template.write_html_on(f, values) end end + ## # The contents is a list of all files and modules. # For each we include as sub-entries the list # of methods they contain. As we build the contents @@ -76,37 +81,39 @@ module Generators index = [] (@files+@classes).sort.each do |entry| - content_entry = { "c_name" => entry.name, "ref" => entry.path } - index << { "name" => entry.name, "aref" => entry.path } + content_entry = { "c_name" => entry.name, "ref" => entry.path } + index << { "name" => entry.name, "aref" => entry.path } - internals = [] + internals = [] - methods = entry.build_method_summary_list(entry.path) + methods = entry.build_method_summary_list(entry.path) - content_entry["methods"] = methods unless methods.empty? + content_entry["methods"] = methods unless methods.empty? contents << content_entry - index.concat methods + index.concat methods end values = { "contents" => contents } template = TemplatePage.new(RDoc::Page::CONTENTS) File.open("contents.hhc", "w") do |f| - template.write_html_on(f, values) + template.write_html_on(f, values) end values = { "index" => index } template = TemplatePage.new(RDoc::Page::CHM_INDEX) File.open("index.hhk", "w") do |f| - template.write_html_on(f, values) - end + template.write_html_on(f, values) + end end + ## # Invoke the windows help compiler to compiler the project + def compile_project system(HHC_PATH, @project_name) end end - end + diff --git a/lib/rdoc/generators/html_generator.rb b/lib/rdoc/generators/html_generator.rb index 4348703c30..1497ed7483 100644 --- a/lib/rdoc/generators/html_generator.rb +++ b/lib/rdoc/generators/html_generator.rb @@ -1,39 +1,3 @@ -# 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. -# - require 'fileutils' require 'rdoc/options' @@ -44,24 +8,32 @@ require 'cgi' module Generators - # Name of sub-direcories that hold file and class/module descriptions + ## + # Name of sub-direcory that holds file descriptions FILE_DIR = "files" + + ## + # Name of sub-direcory that holds class descriptions + CLASS_DIR = "classes" + + ## + # Name of the RDoc CSS file + CSS_NAME = "rdoc-style.css" - ## # Build a hash of all items that can be cross-referenced. - # This is used when we output required and included names: + # 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 + # 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 @@ -79,7 +51,6 @@ module Generators end end - ## # Subclass of the SM::ToHtml class that supports looking # up words in the AllReferences list. Those that are @@ -87,6 +58,8 @@ module Generators # be hyperlinked class HyperlinkHtml < SM::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) @@ -98,6 +71,7 @@ module Generators @context = context 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 @@ -134,9 +108,10 @@ module Generators 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 @@ -155,7 +130,7 @@ module Generators end end - if (type == "http" || type == "link") && + if (type == "http" || type == "link") && url =~ /\.(gif|png|jpg|jpeg|bmp)$/ "<img src=\"#{url}\" />" @@ -164,6 +139,7 @@ module Generators 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 @@ -176,14 +152,14 @@ module Generators gen_url(url, url) end - # HEre's a hypedlink where the label is different to the URL + ## + # 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+)\[(.*?)\]/ + unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/ return text end label = $1 @@ -193,15 +169,12 @@ module Generators end - - - ##################################################################### - # + ## # Handle common markup tasks for the various Html classes - # module MarkUp + ## # Convert a string in markup format into HTML. We keep a cached # SimpleMarkup object lying around after the first time we're # called per object. @@ -217,9 +190,9 @@ module Generators | \#\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 + | \#\w+[!?=]? # #meth_name | \b\w+([_\/\.]+\w+)*[!?=]? # meth_name - )/x, + )/x, :CROSSREF) # external hyperlinks @@ -251,6 +224,7 @@ module Generators res end + ## # 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. @@ -265,6 +239,7 @@ module Generators end 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. @@ -276,34 +251,35 @@ module Generators return url + full_path end end - end + 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 include MarkUp attr_reader :context - + def initialize(context, options) @context = context @options = options end - + + ## # convenience method to build a hyperlink + def href(link, cls, name) %{<a href="#{link}" class="#{cls}">#{name}</a>} #" end - # return 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 + ## + # 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 @@ -313,10 +289,11 @@ module Generators 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. + ## + # 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 @@ -326,23 +303,26 @@ module Generators @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 << { + res << { "name" => CGI.escapeHTML(meth.name), - "aref" => "#{path_prefix}\##{meth.aref}" + "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| @@ -358,8 +338,10 @@ module Generators end values end - + + ## # Build a list of constants + def build_constants_summary_list(section) values = [] @context.constants.each do |co| @@ -373,7 +355,7 @@ module Generators end values end - + def build_requires_list(context) potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] } end @@ -382,6 +364,7 @@ module Generators 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. @@ -394,12 +377,12 @@ module Generators def potentially_referenced_list(array) res = [] array.each do |i| - ref = AllReferences[i.name] + ref = AllReferences[i.name] # if !ref # container = @context.parent # while !ref && container # name = container.name + "::" + i.name -# ref = AllReferences[name] +# ref = AllReferences[name] # container = container.parent # end # end @@ -424,6 +407,7 @@ module Generators 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 @@ -434,12 +418,12 @@ module Generators methods = @methods.sort for singleton in [true, false] - for vis in [ :public, :protected, :private ] + 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.document_self and + m.visibility == vis and m.singleton == singleton row = {} if m.call_seq @@ -459,7 +443,7 @@ module Generators alias_names << { 'name' => other.name, 'aref' => other.viewer.as_href(path) - } + } end end unless alias_names.empty? @@ -479,7 +463,7 @@ module Generators res << row end end - if res.size > 0 + if res.size > 0 outer << { "type" => vis.to_s.capitalize, "category" => singleton ? "Class" : "Instance", @@ -491,8 +475,9 @@ module Generators outer end + ## # Build the structured list of classes and modules contained - # in this context. + # in this context. def build_class_list(level, from, section, infile=nil) res = "" @@ -502,7 +487,7 @@ module Generators next unless mod.section == section next if infile && !mod.defined_in?(infile) if mod.document_self - res << + res << prefix << "Module " << href(url(mod.viewer.path), "link", mod.full_name) << @@ -516,7 +501,7 @@ module Generators next if infile && !cls.defined_in?(infile) if cls.document_self res << - prefix << + prefix << "Class " << href(url(cls.viewer.path), "link", cls.full_name) << "<br />\n" << @@ -526,7 +511,7 @@ module Generators res end - + def url(target) HTMLGenerator.gen_url(path, target) end @@ -550,8 +535,9 @@ module Generators res end - + ## # Find a symbol in ourselves or our parent + def find_symbol(symbol, method=nil) res = @context.find_symbol(symbol, method) if res @@ -560,8 +546,9 @@ module Generators res end + ## # create table of contents if we contain sections - + def add_table_of_sections toc = [] @context.sections.each do |section| @@ -572,15 +559,13 @@ module Generators } end end - + @values['toc'] = toc unless toc.empty? end - end - ##################################################################### - # + ## # Wrap a ClassModule context class HtmlClass < ContextUser @@ -607,8 +592,10 @@ module Generators AllReferences.add(name, self) end - # return the relative file name to store this class in, - # which is also its url + ## + # 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['<<'] @@ -617,7 +604,6 @@ module Generators File.join(prefix, path.split("::")) + ".html" end - def name @context.full_name end @@ -664,16 +650,16 @@ module Generators 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? @@ -690,8 +676,8 @@ module Generators next unless att.section == section if att.visibility == :public || att.visibility == :protected || @options.show_all entry = { - "name" => CGI.escapeHTML(att.name), - "rw" => att.rw, + "name" => CGI.escapeHTML(att.name), + "rw" => att.rw, "a_desc" => markup(att.comment, true) } unless att.visibility == :public || att.visibility == :protected @@ -720,19 +706,19 @@ module Generators parent_class = @context.superclass if parent_class - @values["parent"] = CGI.escapeHTML(parent_class) + @values["parent"] = CGI.escapeHTML(parent_class) - if parent_name - lookup = parent_name + "::" + parent_class - else - lookup = parent_class - end + if parent_name + lookup = parent_name + "::" + parent_class + else + lookup = parent_class + end - parent_url = AllReferences[lookup] || AllReferences[parent_class] + parent_url = AllReferences[lookup] || AllReferences[parent_class] - if parent_url and parent_url.document_self - @values["par_url"] = aref_to(parent_url.path) - end + if parent_url and parent_url.document_self + @values["par_url"] = aref_to(parent_url.path) + end end files = [] @@ -759,8 +745,7 @@ module Generators 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 @@ -851,16 +836,16 @@ module Generators 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 = TemplatePage.new(RDoc::Page::BODY, @@ -872,7 +857,7 @@ module Generators 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 @@ -891,11 +876,13 @@ module Generators def <=>(other) self.name <=> other.name end + end - ##################################################################### + ## class HtmlMethod + include MarkUp attr_reader :context @@ -931,10 +918,10 @@ module Generators AllReferences.add(name, self) end - - # return 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 + + ## + # 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 @@ -970,9 +957,9 @@ module Generators def path if @options.all_one_file - aref + aref else - @html_class.path + "#" + aref + @html_class.path + "#" + aref end end @@ -1005,7 +992,7 @@ module Generators 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 @@ -1022,7 +1009,7 @@ module Generators 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) @@ -1053,7 +1040,6 @@ module Generators # 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| @@ -1088,8 +1074,8 @@ module Generators src end - # we rely on the fact that the first line of a source code - # listing has + ## + # We rely on the fact that the first line of a source code listing has # # File xxxxx, line dddd def add_line_numbers(src) @@ -1100,7 +1086,7 @@ module Generators real_fmt = "%#{size}d: " fmt = " " * (size+2) src.gsub!(/^/) do - res = sprintf(fmt, first) + res = sprintf(fmt, first) first += 1 fmt = real_fmt res @@ -1123,39 +1109,73 @@ module Generators end res 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 HTMLGenerator include MarkUp ## - # convert a target url to one that is relative to a given - # path - + # Converts a target url to one that is relative to a given path + def HTMLGenerator.gen_url(path, target) from = File.dirname(path) to, to_file = File.split(target) - + from = from.split("/") to = to.split("/") - + while from.size > 0 and to.size > 0 and from[0] == to[0] from.shift to.shift end - + from.fill("..") from.concat(to) from << to_file File.join(*from) end - # Generators may need to return specific subclasses depending - # on the options they are passed. Because of this - # we create them using a factory + ## + # Generators may need to return specific subclasses depending on the + # options they are passed. Because of this we create them using a factory def HTMLGenerator.for(options) AllReferences::reset @@ -1172,19 +1192,19 @@ module Generators protected :new end - # Set up a new HTML generator. Basically all we do here is load - # up the correct output temlate + ## + # 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. + # the extracted information. def generate(toplevels) @toplevels = toplevels @@ -1202,7 +1222,7 @@ module Generators ## # 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{/|\\} @@ -1218,8 +1238,7 @@ module Generators ## # Write out the style sheet used by the main frames - # - + def write_style_sheet template = TemplatePage.new(RDoc::Page::STYLE) unless @options.css @@ -1231,13 +1250,12 @@ module Generators end ## - # See the comments at the top for a description of the - # directory structure + # 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 + rescue $stderr.puts $!.message exit 1 end @@ -1271,7 +1289,7 @@ module Generators ## # Generate all the HTML - # + def generate_html # the individual descriptions for files and classes gen_into(@files) @@ -1281,7 +1299,7 @@ module Generators 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 @@ -1298,8 +1316,8 @@ module Generators end def gen_file_index - gen_an_index(@files, 'Files', - RDoc::Page::FILE_INDEX, + gen_an_index(@files, 'Files', + RDoc::Page::FILE_INDEX, "fr_file_index.html") end @@ -1310,12 +1328,11 @@ module Generators end def gen_method_index - gen_an_index(HtmlMethod.all_methods, 'Methods', + gen_an_index(HtmlMethod.all_methods, 'Methods', RDoc::Page::METHOD_INDEX, "fr_method_index.html") end - def gen_an_index(collection, title, template, filename) template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template) res = [] @@ -1338,10 +1355,11 @@ module Generators 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. + ## + # 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 = TemplatePage.new(RDoc::Page::INDEX) @@ -1358,7 +1376,9 @@ module Generators end end - # return the url of the main page + ## + # Returns the url of the main page + def main_url main_page = @options.main_page ref = nil @@ -1374,7 +1394,7 @@ module Generators unless ref for file in @files if file.document_self - ref = file.path + ref = file.path break end end @@ -1389,13 +1409,8 @@ module Generators ref end - end - - ###################################################################### - - class HTMLGeneratorInOne < HTMLGenerator def initialize(*args) @@ -1405,7 +1420,7 @@ module Generators ## # Build the initial indices and output objects # based on an array of TopLevel objects containing - # the extracted information. + # the extracted information. def generate(info) @toplevels = info @@ -1417,7 +1432,6 @@ module Generators generate_xml end - ## # Generate: # @@ -1448,15 +1462,15 @@ module Generators ## # Generate all the HTML. For the one-file case, we generate # all the information in to one big hash - # + def generate_xml - values = { + 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 @@ -1490,7 +1504,6 @@ module Generators gen_an_index(HtmlMethod.all_methods, 'Methods') end - def gen_an_index(collection, title) res = [] collection.sort.each do |f| @@ -1507,4 +1520,6 @@ module Generators end end + end + diff --git a/lib/rdoc/generators/ri_generator.rb b/lib/rdoc/generators/ri_generator.rb index bf22bc8dba..18db389480 100644 --- a/lib/rdoc/generators/ri_generator.rb +++ b/lib/rdoc/generators/ri_generator.rb @@ -1,39 +1,3 @@ -# 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. -# - require 'rdoc/options' require 'rdoc/template' require 'rdoc/markup/simple_markup' @@ -47,12 +11,11 @@ require 'rdoc/ri/ri_descriptions' module Generators - class RIGenerator - # Generators may need to return specific subclasses depending - # on the options they are passed. Because of this - # we create them using a factory + ## + # Generators may need to return specific subclasses depending on the + # options they are passed. Because of this we create them using a factory def RIGenerator.for(options) new(options) @@ -62,8 +25,9 @@ module Generators protected :new end - # Set up a new HTML generator. Basically all we do here is load - # up the correct output temlate + ## + # 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 @@ -72,11 +36,9 @@ module Generators @to_flow = SM::ToFlow.new end - ## - # Build the initial indices and output objects - # based on an array of TopLevel objects containing - # the extracted information. + # Build the initial indices and output objects based on an array of + # TopLevel objects containing the extracted information. def generate(toplevels) RDoc::TopLevel.all_classes_and_modules.each do |cls| @@ -163,8 +125,8 @@ module Generators private - # return a list of class and instance methods that we'll be - # documenting + ## + # Returns a list of class and instance methods that we'll be documenting def method_list(cls) list = cls.method_list @@ -185,17 +147,17 @@ module Generators end return c,i end - + def params_of(method) if method.call_seq method.call_seq else params = method.params || "" - + p = params.gsub(/\s*\#.*/, '') p = p.tr("\n", " ").squeeze(" ") p = "(" + p + ")" unless p[0] == ?( - + if (block = method.block_params) block.gsub!(/\s*\#.*/, '') block = block.tr("\n", " ").squeeze(" ") @@ -213,7 +175,7 @@ module Generators # Convert leading comment markers to spaces, but only # if all non-blank lines have them - + if comment =~ /^(?>\s*)[^\#]/ content = comment else @@ -222,12 +184,11 @@ module Generators @markup.convert(content, @to_flow) end - - # By default we replace existing classes with the - # same name. If the --merge option was given, we instead - # merge this definition into an existing class. We add - # our methods, aliases, etc to that class, but do not - # change the class's description. + ## + # By default we replace existing classes with the same name. If the + # --merge option was given, we instead merge this definition into an + # existing class. We add our methods, aliases, etc to that class, but do + # not change the class's description. def update_or_replace(cls_desc) old_cls = nil @@ -242,7 +203,7 @@ module Generators $stderr.puts "documentation. This file references a class or " $stderr.puts "module called #{cls_desc.name} which I don't" $stderr.puts "have existing documentation for." - $stderr.puts + $stderr.puts $stderr.puts "Perhaps you need to generate its documentation first" exit 1 else @@ -262,5 +223,8 @@ module Generators @ri_writer.add_class(old_desc) end end + end + end + diff --git a/lib/rdoc/generators/xml_generator.rb b/lib/rdoc/generators/xml_generator.rb index 561a9ad694..8034fac517 100644 --- a/lib/rdoc/generators/xml_generator.rb +++ b/lib/rdoc/generators/xml_generator.rb @@ -1,4 +1,3 @@ - require 'rdoc/options' require 'rdoc/markup/simple_markup' require 'rdoc/markup/simple_markup/to_html' @@ -6,16 +5,18 @@ require 'rdoc/generators/html_generator' module Generators + ## # Generate XML output as one big file class XMLGenerator < HTMLGenerator + ## # Standard generator factory + def XMLGenerator.for(options) XMLGenerator.new(options) end - def initialize(*args) super end @@ -23,7 +24,7 @@ module Generators ## # Build the initial indices and output objects # based on an array of TopLevel objects containing - # the extracted information. + # the extracted information. def generate(info) @info = info @@ -35,7 +36,6 @@ module Generators generate_xml end - ## # Generate: # @@ -66,14 +66,14 @@ module Generators ## # Generate all the HTML. For the one-file case, we generate # all the information in to one big hash - # + def generate_xml - values = { + values = { 'charset' => @options.charset, 'files' => gen_into(@files), 'classes' => gen_into(@classes) } - + # this method is defined in the template file write_extra_pages if defined? write_extra_pages @@ -107,7 +107,6 @@ module Generators gen_an_index(HtmlMethod.all_methods, 'Methods') end - def gen_an_index(collection, title) res = [] collection.sort.each do |f| @@ -126,3 +125,4 @@ module Generators end end + |