rdoc 3.12.2 → 4.0.0.preview2

data/lib/rdoc/extend.rb

@@ -0,0 +1,117 @@
+##
+# A Module extension in a class with \#extend
+
+class RDoc::Extend < RDoc::CodeObject
+
+  ##
+  # Name of extension module
+
+  attr_accessor :name
+
+  ##
+  # Creates a new Extend for +name+ with +comment+
+
+  def initialize(name, comment)
+    super()
+    @name = name
+    self.comment = comment
+    @module = nil # cache for module if found
+  end
+
+  ##
+  # Extends are sorted by name
+
+  def <=> other
+    return unless self.class === other
+
+    name <=> other.name
+  end
+
+  def == other # :nodoc:
+    self.class === other and @name == other.name
+  end
+
+  alias eql? ==
+
+  ##
+  # Full name based on #module
+
+  def full_name
+    m = self.module
+    RDoc::ClassModule === m ? m.full_name : @name
+  end
+
+  def hash # :nodoc:
+    [@name, self.module].hash
+  end
+
+  def inspect # :nodoc:
+    "#<%s:0x%x %s.extend %s>" % [
+      self.class,
+      object_id,
+      parent_name, @name,
+    ]
+  end
+
+  ##
+  # Attempts to locate the extend module object.  Returns the name if not
+  # known.
+  #
+  # The scoping rules of Ruby to resolve the name of an extension module are:
+  # - first look into the children of the current context;
+  # - if not found, look into the children of extension modules,
+  #   in reverse extend order;
+  # - if still not found, go up the hierarchy of names.
+  #
+  # This method has <code>O(n!)</code> behavior when the module calling
+  # extend is referencing nonexistent modules.  Avoid calling #module until
+  # after all the files are parsed.  This behavior is due to ruby's constant
+  # lookup behavior.
+
+  def module
+    return @module if @module
+
+    # search the current context
+    return @name unless parent
+    full_name = parent.child_name(@name)
+    @module = @store.modules_hash[full_name]
+    return @module if @module
+    return @name if @name =~ /^::/
+
+    # search the includes before this one, in reverse order
+    searched = parent.extends.take_while { |i| i != self }.reverse
+    searched.each do |i|
+      ext = i.module
+      next if String === ext
+      full_name = ext.child_name(@name)
+      @module = @store.modules_hash[full_name]
+      return @module if @module
+    end
+
+    # go up the hierarchy of names
+    up = parent.parent
+    while up
+      full_name = up.child_name(@name)
+      @module = @store.modules_hash[full_name]
+      return @module if @module
+      up = up.parent
+    end
+
+    @name
+  end
+
+  ##
+  # Sets the store for this class or module and its contained code objects.
+
+  def store= store
+    super
+
+    @file = @store.add_file @file.full_name if @file
+  end
+
+  def to_s # :nodoc:
+    "extend #@name in: #{parent}"
+  end
+
+end
+

data/lib/rdoc/generator.rb

@@ -18,7 +18,8 @@
 # Before option processing in +rdoc+, RDoc::Options will call ::setup_options
 # on the generator class with an RDoc::Options instance.  The generator can
 # use RDoc::Options#option_parser to add command-line options to the +rdoc+
-# tool.  See OptionParser for details on how to add options.
+# tool.  See RDoc::Options@Custom+Options for an example and see OptionParser
+# for details on how to add options.
 #
 # You can extend the RDoc::Options instance with additional accessors for your
 # generator.
@@ -26,12 +27,16 @@
 # == Generator Instantiation
 #
 # After parsing, RDoc::RDoc will instantiate a generator by calling
-# #initialize with an RDoc::Options instance.
+# #initialize with an RDoc::Store instance and an RDoc::Options instance.
 #
-# RDoc will then call #generate on the generator instance and pass in an Array
-# of RDoc::TopLevel instances, each representing a parsed file.  You can use
-# the various class methods on RDoc::TopLevel and in the RDoc::CodeObject tree
-# to create your desired output format.
+# The RDoc::Store instance holds documentation for parsed source code.  In
+# RDoc 3 and earlier the RDoc::TopLevel class held this data.  When upgrading
+# a generator from RDoc 3 and earlier you should only need to replace
+# RDoc::TopLevel with the store instance.
+#
+# RDoc will then call #generate on the generator instance.  You can use the
+# various methods on RDoc::Store and in the RDoc::CodeObject tree to create
+# your desired output format.
 
 module RDoc::Generator
 

data/lib/rdoc/generator/darkfish.rb

@@ -73,6 +73,12 @@ class RDoc::Generator::Darkfish
 
   DESCRIPTION = 'HTML generator, written by Michael Granger'
 
+  ##
+  # The relative path to style sheets and javascript.  By default this is set
+  # the same as the rel_prefix.
+
+  attr_accessor :asset_rel_path
+
   ##
   # The path to generate files into, combined with <tt>--op</tt> from the
   # options for a full path.
@@ -80,27 +86,75 @@ class RDoc::Generator::Darkfish
   attr_reader :base_dir
 
   ##
-  # Initialize a few instance variables before we start
+  # Classes and modules to be used by this generator, not necessarily
+  # displayed.  See also #modsort
 
-  def initialize options
-    @options = options
+  attr_reader :classes
 
-    @template_dir = Pathname.new options.template_dir
-    @template_cache = {}
+  ##
+  # No files will be written when dry_run is true.
+
+  attr_accessor :dry_run
 
-    @files      = nil
-    @classes    = nil
+  ##
+  # When false the generate methods return a String instead of writing to a
+  # file.  The default is true.
 
-    @base_dir = Pathname.pwd.expand_path
+  attr_accessor :file_output
 
-    @json_index = RDoc::Generator::JsonIndex.new self, options
-  end
+  ##
+  # Files to be displayed by this generator
+
+  attr_reader :files
+
+  ##
+  # The JSON index generator for this Darkfish generator
+
+  attr_reader :json_index
+
+  ##
+  # Methods to be displayed by this generator
+
+  attr_reader :methods
+
+  ##
+  # Sorted list of classes and modules to be displayed by this generator
+
+  attr_reader :modsort
+
+  ##
+  # The RDoc::Store that is the source of the generated content
+
+  attr_reader :store
 
   ##
   # The output directory
 
   attr_reader :outputdir
 
+  ##
+  # Initialize a few instance variables before we start
+
+  def initialize store, options
+    @store   = store
+    @options = options
+
+    @asset_rel_path = ''
+    @base_dir       = Pathname.pwd.expand_path
+    @dry_run        = @options.dry_run
+    @file_output    = true
+    @template_dir   = Pathname.new options.template_dir
+    @template_cache = {}
+
+    @classes = nil
+    @context = nil
+    @files   = nil
+    @methods = nil
+    @modsort = nil
+
+    @json_index = RDoc::Generator::JsonIndex.new self, options
+  end
+
   ##
   # Output progress information if debugging is enabled
 
@@ -139,7 +193,7 @@ class RDoc::Generator::Darkfish
 
   def write_style_sheet
     debug_msg "Copying static files"
-    options = { :verbose => $DEBUG_RDOC, :noop => @options.dry_run }
+    options = { :verbose => $DEBUG_RDOC, :noop => @dry_run }
 
     FileUtils.cp @template_dir + 'rdoc.css', '.', options
 
@@ -147,7 +201,7 @@ class RDoc::Generator::Darkfish
       next if File.directory? path
       next if File.basename(path) =~ /^\./
 
-        dst = Pathname.new(path).relative_path_from @template_dir
+      dst = Pathname.new(path).relative_path_from @template_dir
 
       # I suck at glob
       dst_dir = dst.dirname
@@ -161,21 +215,15 @@ class RDoc::Generator::Darkfish
   # Build the initial indices and output objects based on an array of TopLevel
   # objects containing the extracted information.
 
-  def generate top_levels
-    @outputdir = Pathname.new(@options.op_dir).expand_path(@base_dir)
+  def generate
+    setup
 
-    @files = top_levels.sort
-    @classes = RDoc::TopLevel.all_classes_and_modules.sort
-    @methods = @classes.map { |m| m.method_list }.flatten.sort
-    @modsort = get_sorted_module_list(@classes)
-
-    # Now actually write the output
     write_style_sheet
     generate_index
     generate_class_files
     generate_file_files
     generate_table_of_contents
-    @json_index.generate top_levels
+    @json_index.generate
 
     copy_static
 
@@ -187,15 +235,13 @@ class RDoc::Generator::Darkfish
     raise
   end
 
-  protected
-
   ##
   # Copies static files from the static_path into the output directory
 
   def copy_static
     return if @options.static_path.empty?
 
-    fu_options = { :verbose => $DEBUG_RDOC, :noop => @options.dry_run }
+    fu_options = { :verbose => $DEBUG_RDOC, :noop => @dry_run }
 
     @options.static_path.each do |path|
       unless File.directory? path then
@@ -221,38 +267,31 @@ class RDoc::Generator::Darkfish
   # Return a list of the documented modules sorted by salience first, then
   # by name.
 
-  def get_sorted_module_list(classes)
-    nscounts = classes.inject({}) do |counthash, klass|
-      top_level = klass.full_name.gsub(/::.*/, '')
-      counthash[top_level] ||= 0
-      counthash[top_level] += 1
-
-      counthash
-    end
-
-    # Sort based on how often the top level namespace occurs, and then on the
-    # name of the module -- this works for projects that put their stuff into
-    # a namespace, of course, but doesn't hurt if they don't.
-    classes.sort_by do |klass|
-      top_level = klass.full_name.gsub( /::.*/, '' )
-      [nscounts[top_level] * -1, klass.full_name]
-    end.select do |klass|
+  def get_sorted_module_list classes
+    classes.select do |klass|
       klass.display?
-    end
+    end.sort
   end
 
   ##
   # Generate an index page which lists all the classes which are documented.
 
   def generate_index
+    setup
+
     template_file = @template_dir + 'index.rhtml'
     return unless template_file.exist?
 
     debug_msg "Rendering the index page..."
 
     out_file = @base_dir + @options.op_dir + 'index.html'
+    rel_prefix = @outputdir.relative_path_from out_file.dirname
+    search_index_rel_prefix = rel_prefix
+    search_index_rel_prefix += @asset_rel_path if @file_output
+
     # suppress 1.9.3 warning
-    rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
+    asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
+
     @title = @options.title
 
     render_template template_file, out_file do |io| binding end
@@ -264,10 +303,38 @@ class RDoc::Generator::Darkfish
     raise error
   end
 
+  ##
+  # Generates a class file for +klass+
+
+  def generate_class klass, template_file = nil
+    setup
+
+    current = klass
+
+    template_file ||= @template_dir + 'class.rhtml'
+
+    debug_msg "  working on %s (%s)" % [klass.full_name, klass.path]
+    out_file   = @outputdir + klass.path
+    rel_prefix = @outputdir.relative_path_from out_file.dirname
+    search_index_rel_prefix = rel_prefix
+    search_index_rel_prefix += @asset_rel_path if @file_output
+
+    # suppress 1.9.3 warning
+    asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
+    svninfo          = svninfo          = get_svninfo(current)
+
+    @title = "#{klass.type} #{klass.full_name} - #{@options.title}"
+
+    debug_msg "  rendering #{out_file}"
+    render_template template_file, out_file do |io| binding end
+  end
+
   ##
   # Generate a documentation file for each class and module
 
   def generate_class_files
+    setup
+
     template_file = @template_dir + 'class.rhtml'
     template_file = @template_dir + 'classpage.rhtml' unless
       template_file.exist?
@@ -278,15 +345,8 @@ class RDoc::Generator::Darkfish
 
     @classes.each do |klass|
       current = klass
-      debug_msg "  working on %s (%s)" % [klass.full_name, klass.path]
-      out_file   = @outputdir + klass.path
-      # suppress 1.9.3 warning
-      rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
-      svninfo    = svninfo    = self.get_svninfo(klass)
-      @title = "#{klass.type} #{klass.full_name} - #{@options.title}"
 
-      debug_msg "  rendering #{out_file}"
-      render_template template_file, out_file do |io| binding end
+      generate_class klass, template_file
     end
   rescue => e
     error = RDoc::Error.new \
@@ -300,6 +360,8 @@ class RDoc::Generator::Darkfish
   # Generate a documentation file for each file
 
   def generate_file_files
+    setup
+
     page_file     = @template_dir + 'page.rhtml'
     fileinfo_file = @template_dir + 'fileinfo.rhtml'
 
@@ -308,17 +370,30 @@ class RDoc::Generator::Darkfish
       page_file.exist? or fileinfo_file.exist?
 
     return unless
-      page_file.exist? or fileinfo_file.exist? or template_file.exist?
+      page_file.exist? or fileinfo_file.exist? or filepage_file.exist?
+
     debug_msg "Generating file documentation in #{@outputdir}"
 
     out_file = nil
+    current = nil
 
     @files.each do |file|
+      current = file
+
+      if file.text? and page_file.exist? then
+        generate_page file
+        next
+      end
+
       template_file = nil
       out_file = @outputdir + file.path
       debug_msg "  working on %s (%s)" % [file.full_name, out_file]
+      rel_prefix = @outputdir.relative_path_from out_file.dirname
+      search_index_rel_prefix = rel_prefix
+      search_index_rel_prefix += @asset_rel_path if @file_output
+
       # suppress 1.9.3 warning
-      rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
+      asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
 
       unless filepage_file then
         if file.text? then
@@ -345,18 +420,105 @@ class RDoc::Generator::Darkfish
     raise error
   end
 
+  ##
+  # Generate a page file for +file+
+
+  def generate_page file
+    setup
+
+    template_file = @template_dir + 'page.rhtml'
+
+    out_file = @outputdir + file.path
+    debug_msg "  working on %s (%s)" % [file.full_name, out_file]
+    rel_prefix = @outputdir.relative_path_from out_file.dirname
+    search_index_rel_prefix = rel_prefix
+    search_index_rel_prefix += @asset_rel_path if @file_output
+
+    # suppress 1.9.3 warning
+    current          = current          = file
+    asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
+
+    @title = "#{file.page_name} - #{@options.title}"
+
+    debug_msg "  rendering #{out_file}"
+    render_template template_file, out_file do |io| binding end
+  end
+
+  ##
+  # Generates the 404 page for the RDoc servlet
+
+  def generate_servlet_not_found path
+    setup
+
+    template_file = @template_dir + 'servlet_not_found.rhtml'
+    return unless template_file.exist?
+
+    debug_msg "Rendering the servlet root page..."
+
+    rel_prefix = rel_prefix = ''
+    search_index_rel_prefix = rel_prefix
+    search_index_rel_prefix += @asset_rel_path if @file_output
+
+    # suppress 1.9.3 warning
+    asset_rel_prefix = asset_rel_prefix = ''
+
+    @title = 'Not Found'
+
+    render_template template_file do |io| binding end
+  rescue => e
+    error = RDoc::Error.new \
+      "error generating servlet_not_found: #{e.message} (#{e.class})"
+    error.set_backtrace e.backtrace
+
+    raise error
+  end
+
+  ##
+  # Generates the servlet root page for the RDoc servlet
+
+  def generate_servlet_root installed
+    setup
+
+    template_file = @template_dir + 'servlet_root.rhtml'
+    return unless template_file.exist?
+
+    debug_msg 'Rendering the servlet root page...'
+
+    rel_prefix = '.'
+    asset_rel_prefix = rel_prefix
+    search_index_rel_prefix = asset_rel_prefix
+    search_index_rel_prefix += @asset_rel_path if @file_output
+
+    @title = 'Local RDoc Documentation'
+
+    render_template template_file do |io| binding end
+  rescue => e
+    error = RDoc::Error.new \
+      "error generating servlet_root: #{e.message} (#{e.class})"
+    error.set_backtrace e.backtrace
+
+    raise error
+  end
+
   ##
   # Generate an index page which lists all the classes which are documented.
 
   def generate_table_of_contents
+    setup
+
     template_file = @template_dir + 'table_of_contents.rhtml'
     return unless template_file.exist?
 
     debug_msg "Rendering the Table of Contents..."
 
     out_file = @outputdir + 'table_of_contents.html'
+    rel_prefix = @outputdir.relative_path_from out_file.dirname
+    search_index_rel_prefix = rel_prefix
+    search_index_rel_prefix += @asset_rel_path if @file_output
+
     # suppress 1.9.3 warning
-    rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
+    asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
+
     @title = "Table of Contents - #{@options.title}"
 
     render_template template_file, out_file do |io| binding end
@@ -368,6 +530,22 @@ class RDoc::Generator::Darkfish
     raise error
   end
 
+  ##
+  # Prepares for generation of output from the current directory
+
+  def setup
+    return if instance_variable_defined? :@outputdir
+
+    @outputdir = Pathname.new(@options.op_dir).expand_path @base_dir
+
+    return unless @store
+
+    @classes = @store.all_classes_and_modules.sort
+    @files   = @store.all_files.sort
+    @methods = @classes.map { |m| m.method_list }.flatten.sort
+    @modsort = get_sorted_module_list @classes
+  end
+
   ##
   # Return a string describing the amount of time in the given number of
   # seconds in terms a human can understand easily.
@@ -453,7 +631,7 @@ class RDoc::Generator::Darkfish
   def render file_name
     template_file = @template_dir + file_name
 
-    template = template_for template_file, false, ERB
+    template = template_for template_file, false, RDoc::ERBPartial
 
     template.filename = template_file.to_s
 
@@ -468,10 +646,13 @@ class RDoc::Generator::Darkfish
   #
   # An io will be yielded which must be captured by binding in the caller.
 
-  def render_template template_file, out_file # :yield: io
-    template = template_for template_file
+  def render_template template_file, out_file = nil # :yield: io
+    io_output = out_file && !@dry_run && @file_output
+    erb_klass = io_output ? RDoc::ERBIO : ERB
+
+    template = template_for template_file, true, erb_klass
 
-    unless @options.dry_run then
+    if io_output then
       debug_msg "Outputting to %s" % [out_file.expand_path]
 
       out_file.dirname.mkpath
@@ -489,7 +670,9 @@ class RDoc::Generator::Darkfish
 
       debug_msg "  would have written %d characters to %s" % [
         output.length, out_file.expand_path
-      ]
+      ] if @dry_run
+
+      output
     end
   end
 
@@ -510,20 +693,25 @@ class RDoc::Generator::Darkfish
   ##
   # Retrieves a cache template for +file+, if present, or fills the cache.
 
-  def template_for file, page = true, klass = nil
+  def template_for file, page = true, klass = ERB
     template = @template_cache[file]
 
     return template if template
 
-    klass = @options.dry_run ? ERB : RDoc::ERBIO unless klass
-
     template = if page then
                  assemble_template file
                else
                  file.read
                end
 
-    template = klass.new template, nil, '<>'
+    erbout = if page then
+               'io'
+             else
+               file_var = File.basename(file).sub(/\..*/, '')
+               "_erbout_#{file_var}"
+             end
+
+    template = klass.new template, nil, '<>', erbout
     @template_cache[file] = template
     template
   end