RubyGems - rdoc - Versions diffs - 2.0.0 - Mend

rdoc 2.0.0

Potentially problematic release.

This version of rdoc might be problematic. Click here for more details.

Files changed (62) hide show

data/History.txt +13 -0
data/Manifest.txt +61 -0
data/README.txt +34 -0
data/Rakefile +10 -0
data/bin/rdoc +22 -0
data/bin/ri +6 -0
data/lib/rdoc.rb +277 -0
data/lib/rdoc/code_objects.rb +776 -0
data/lib/rdoc/diagram.rb +338 -0
data/lib/rdoc/dot.rb +249 -0
data/lib/rdoc/generator.rb +1048 -0
data/lib/rdoc/generator/chm.rb +113 -0
data/lib/rdoc/generator/chm/chm.rb +98 -0
data/lib/rdoc/generator/html.rb +370 -0
data/lib/rdoc/generator/html/hefss.rb +414 -0
data/lib/rdoc/generator/html/html.rb +704 -0
data/lib/rdoc/generator/html/kilmer.rb +418 -0
data/lib/rdoc/generator/html/one_page_html.rb +121 -0
data/lib/rdoc/generator/ri.rb +229 -0
data/lib/rdoc/generator/xml.rb +120 -0
data/lib/rdoc/generator/xml/rdf.rb +113 -0
data/lib/rdoc/generator/xml/xml.rb +111 -0
data/lib/rdoc/markup.rb +473 -0
data/lib/rdoc/markup/attribute_manager.rb +274 -0
data/lib/rdoc/markup/formatter.rb +14 -0
data/lib/rdoc/markup/fragments.rb +337 -0
data/lib/rdoc/markup/inline.rb +101 -0
data/lib/rdoc/markup/lines.rb +152 -0
data/lib/rdoc/markup/preprocess.rb +71 -0
data/lib/rdoc/markup/to_flow.rb +185 -0
data/lib/rdoc/markup/to_html.rb +353 -0
data/lib/rdoc/markup/to_html_crossref.rb +86 -0
data/lib/rdoc/markup/to_latex.rb +328 -0
data/lib/rdoc/markup/to_test.rb +50 -0
data/lib/rdoc/options.rb +616 -0
data/lib/rdoc/parsers/parse_c.rb +775 -0
data/lib/rdoc/parsers/parse_f95.rb +1841 -0
data/lib/rdoc/parsers/parse_rb.rb +2584 -0
data/lib/rdoc/parsers/parse_simple.rb +40 -0
data/lib/rdoc/parsers/parserfactory.rb +99 -0
data/lib/rdoc/rdoc.rb +277 -0
data/lib/rdoc/ri.rb +4 -0
data/lib/rdoc/ri/cache.rb +188 -0
data/lib/rdoc/ri/descriptions.rb +150 -0
data/lib/rdoc/ri/display.rb +274 -0
data/lib/rdoc/ri/driver.rb +452 -0
data/lib/rdoc/ri/formatter.rb +616 -0
data/lib/rdoc/ri/paths.rb +102 -0
data/lib/rdoc/ri/reader.rb +106 -0
data/lib/rdoc/ri/util.rb +81 -0
data/lib/rdoc/ri/writer.rb +68 -0
data/lib/rdoc/stats.rb +25 -0
data/lib/rdoc/template.rb +64 -0
data/lib/rdoc/tokenstream.rb +33 -0
data/test/test_rdoc_c_parser.rb +261 -0
data/test/test_rdoc_markup.rb +613 -0
data/test/test_rdoc_markup_attribute_manager.rb +224 -0
data/test/test_rdoc_ri_attribute_formatter.rb +42 -0
data/test/test_rdoc_ri_default_display.rb +295 -0
data/test/test_rdoc_ri_formatter.rb +318 -0
data/test/test_rdoc_ri_overstrike_formatter.rb +69 -0
metadata +134 -0

@@ -0,0 +1,113 @@
+require 'rdoc/generator/html'
+class RDoc::Generator::CHM < RDoc::Generator::HTML
+  HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe"
+  ##
+  # Standard generator factory
+  def self.for(options)
+    new(options)
+  end
+  def initialize(*args)
+    super
+    @op_name = @options.op_name || "rdoc"
+    check_for_html_help_workshop
+  end
+  def check_for_html_help_workshop
+    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"
+  end
+  ##
+  # 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
+  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.
+  def create_project_file
+    template = RDoc::TemplatePage.new @template::HPP_FILE
+    values = { "title" => @options.title, "opname" => @op_name }
+    files = []
+    @files.each do |f|
+      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
+  # we also build an index file
+  def create_contents_and_index
+    contents = []
+    index    = []
+    (@files+@classes).sort.each do |entry|
+      content_entry = { "c_name" => entry.name, "ref" => entry.path }
+      index << { "name" => entry.name, "aref" => entry.path }
+      internals = []
+      methods = entry.build_method_summary_list(entry.path)
+      content_entry["methods"] = methods unless methods.empty?
+      contents << content_entry
+      index.concat methods
+    end
+    values = { "contents" => contents }
+    template = RDoc::TemplatePage.new @template::CONTENTS
+    File.open("contents.hhc", "w") do |f|
+      template.write_html_on(f, values)
+    end
+    values = { "index" => index }
+    template = RDoc::TemplatePage.new @template::CHM_INDEX
+    File.open("index.hhk", "w") do |f|
+      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

data/lib/rdoc/generator/chm/chm.rb ADDED

@@ -0,0 +1,98 @@
+require 'rdoc/generator/chm'
+require 'rdoc/generator/html/html'
+module RDoc::Generator::CHM::CHM
+  HTML = RDoc::Generator::HTML::HTML
+  INDEX = HTML::INDEX
+  CLASS_INDEX = HTML::CLASS_INDEX
+  CLASS_PAGE = HTML::CLASS_PAGE
+  FILE_INDEX = HTML::FILE_INDEX
+  FILE_PAGE = HTML::FILE_PAGE
+  METHOD_INDEX = HTML::METHOD_INDEX
+  METHOD_LIST = HTML::METHOD_LIST
+  FR_INDEX_BODY = HTML::FR_INDEX_BODY
+  # This is a nasty little hack, but hhc doesn't support the <?xml tag, so...
+  BODY = HTML::BODY.sub!(/<\?xml.*\?>/, '')
+  SRC_PAGE = HTML::SRC_PAGE.sub!(/<\?xml.*\?>/, '')
+  HPP_FILE = <<-EOF
+[OPTIONS]
+Auto Index = Yes
+Compatibility=1.1 or later
+Compiled file=<%= values["opname"] %>.chm
+Contents file=contents.hhc
+Full-text search=Yes
+Index file=index.hhk
+Language=0x409 English(United States)
+Title=<%= values["title"] %>
+[FILES]
+<% values["all_html_files"].each do |all_html_files| %>
+<%= all_html_files["html_file_name"] %>
+<% end # values["all_html_files"] %>
+  EOF
+  CONTENTS = <<-EOF
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<HTML>
+<HEAD>
+<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
+<!-- Sitemap 1.0 -->
+</HEAD><BODY>
+<OBJECT type="text/site properties">
+	<param name="Foreground" value="0x80">
+	<param name="Window Styles" value="0x800025">
+	<param name="ImageType" value="Folder">
+</OBJECT>
+<UL>
+<% values["contents"].each do |contents| %>
+	<LI> <OBJECT type="text/sitemap">
+		<param name="Name" value="<%= contents["c_name"] %>">
+		<param name="Local" value="<%= contents["ref"] %>">
+		</OBJECT>
+<% if contents["methods"] then %>
+<ul>
+<% contents["methods"].each do |methods| %>
+	<LI> <OBJECT type="text/sitemap">
+		<param name="Name" value="<%= methods["name"] %>">
+		<param name="Local" value="<%= methods["aref"] %>">
+		</OBJECT>
+<% end # contents["methods"] %>
+</ul>
+<% end %>
+        </LI>
+<% end # values["contents"] %>
+</UL>
+</BODY></HTML>
+  EOF
+  CHM_INDEX = <<-EOF
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<HTML>
+<HEAD>
+<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
+<!-- Sitemap 1.0 -->
+</HEAD><BODY>
+<OBJECT type="text/site properties">
+	<param name="Foreground" value="0x80">
+	<param name="Window Styles" value="0x800025">
+	<param name="ImageType" value="Folder">
+</OBJECT>
+<UL>
+<% values["index"].each do |index| %>
+	<LI> <OBJECT type="text/sitemap">
+		<param name="Name" value="<%= index["name"] %>">
+		<param name="Local" value="<%= index["aref"] %>">
+		</OBJECT>
+<% end # values["index"] %>
+</UL>
+</BODY></HTML>
+  EOF
+end

data/lib/rdoc/generator/html.rb ADDED

@@ -0,0 +1,370 @@
+require 'fileutils'
+require 'rdoc/generator'
+require 'rdoc/markup/to_html'
+##
+# 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
+  ##
+  # 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)
+    RDoc::Generator::AllReferences.reset
+    RDoc::Generator::Method.reset
+    if options.all_one_file
+      RDoc::Generator::HTMLInOne.new options
+    else
+      new options
+    end
+  end
+  class << self
+    protected :new
+  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
+    @main_page_path = nil
+  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
+      open RDoc::Generator::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 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
+  ##
+  # 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))
+        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(RDoc::Generator::Method.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),
+    }
+    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 = RDoc::Generator::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 { |context| context.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
+end
+class RDoc::Generator::HTMLInOne < RDoc::Generator::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
+    @hyperlinks = {}
+    build_indices
+    generate_xml
+  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
+  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
+    template = RDoc::TemplatePage.new @template::ONE_PAGE
+    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
+  end
+  def gen_file_index
+    gen_an_index(@files, 'Files')
+  end
+  def gen_class_index
+    gen_an_index(@classes, 'Classes')
+  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
+    end
+    return {
+      "entries" => res,
+      'list_title' => title,
+      'index_url'  => main_url,
+    }
+  end
+end