rdoc 2.3.0 → 2.4.0

data/lib/rdoc/generator/darkfish.rb

@@ -1,7 +1,8 @@
 #!ruby
+# vim: noet ts=2 sts=8 sw=2
 
 require 'rubygems'
-gem 'rdoc', '>= 2.3'
+gem 'rdoc', '>= 2.4' unless defined? $rdoc_rakefile
 
 require 'pp'
 require 'pathname'
@@ -10,8 +11,8 @@ require 'erb'
 require 'yaml'
 
 require 'rdoc/rdoc'
-require 'rdoc/generator/xml'
-require 'rdoc/generator/html'
+require 'rdoc/generator'
+require 'rdoc/generator/markup'
 
 #
 #  Darkfish RDoc HTML Generator
@@ -54,7 +55,7 @@ require 'rdoc/generator/html'
 #  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 #  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #  
-class RDoc::Generator::Darkfish < RDoc::Generator::XML
+class RDoc::Generator::Darkfish
 
 	RDoc::RDoc.add_generator( self )
 
@@ -62,13 +63,13 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 
 	# Subversion rev
 	SVNRev = %$Rev: 52 $
-	
+
 	# Subversion ID
 	SVNId = %$Id: darkfish.rb 52 2009-01-07 02:08:11Z deveiant $
 
 	# Path to this file's parent directory. Used to find templates and other
 	# resources.
-	GENERATOR_DIR = Pathname.new( __FILE__ ).expand_path.dirname
+	GENERATOR_DIR = File.join 'rdoc', 'generator'
 
 	# Release Version
 	VERSION = '1.1.6'
@@ -96,43 +97,55 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 
 	### Initialize a few instance variables before we start
 	def initialize( options )
-		@template = nil
-		@template_dir = GENERATOR_DIR + 'template/darkfish'
-		
-		@files      = []
-		@classes    = []
-		@hyperlinks = {}
+		@options = options
+		@options.diagram = false
 
-		@basedir = Pathname.pwd.expand_path
+		template = @options.template || 'darkfish'
+
+		template_dir = $LOAD_PATH.map do |path|
+			File.join path, GENERATOR_DIR, 'template', template
+		end.find do |dir|
+			File.directory? dir
+		end
 
-		options.inline_source = true
-		options.diagram = false
+		raise RDoc::Error, "could not find template #{template.inspect}" unless
+			template_dir
 
-		super
+		@template_dir = Pathname.new File.expand_path(template_dir)
+
+		@files      = nil
+		@classes    = nil
+
+		@basedir = Pathname.pwd.expand_path
 	end
-	
-	
+
 	######
 	public
 	######
 
 	# The output directory
 	attr_reader :outputdir
-	
-	
+
+
 	### Output progress information if debugging is enabled
 	def debug_msg( *msg )
-		return unless $DEBUG
+		return unless $DEBUG_RDOC
 		$stderr.puts( *msg )
 	end
-	
-	
+
+	def class_dir
+		CLASS_DIR
+	end
+
+	def file_dir
+		FILE_DIR
+	end
+
 	### Create the directories the generated docs will live in if
 	### they don't already exist.
 	def gen_sub_directories
 		@outputdir.mkpath
 	end
-	
 
 	### Copy over the stylesheet into the appropriate place in the
 	### output directory.
@@ -143,92 +156,63 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 			FileUtils.cp_r( @template_dir + path, '.', :verbose => $DEBUG, :noop => $dryrun )
 		end
 	end
-	
-	
+
+
 
 	### Build the initial indices and output objects
 	### based on an array of TopLevel objects containing
-	### the extracted information. 
-	def generate( toplevels )
+	### the extracted information.
+	def generate( top_levels )
 		@outputdir = Pathname.new( @options.op_dir ).expand_path( @basedir )
-		if RDoc::Generator::Context.respond_to?( :build_indicies)
-	    	@files, @classes = RDoc::Generator::Context.build_indicies( toplevels, @options )
-		else
-	    	@files, @classes = RDoc::Generator::Context.build_indices( toplevels, @options )
-		end
+
+		@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
-		generate_xhtml( @options, @files, @classes )
+		write_style_sheet
+		generate_index
+		generate_class_files
+		generate_file_files
 
 	rescue StandardError => err
 		debug_msg "%s: %s\n  %s" % [ err.class.name, err.message, err.backtrace.join("\n  ") ]
 		raise
 	end
 
-
-	### No-opped
-	def load_html_template # :nodoc:
-	end
-
-
-	### Generate output
-	def generate_xhtml( options, files, classes )
-		files = gen_into( @files )
-		classes = gen_into( @classes )
-
-		# Make a hash of class info keyed by class name
-		classes_by_classname = classes.inject({}) {|hash, classinfo|
-			hash[ classinfo[:full_name] ] = classinfo
-			hash[ classinfo[:full_name] ][:outfile] =
-				classinfo[:full_name].gsub( /::/, '/' ) + '.html'
-			hash
-		}
-
-		# Make a hash of file info keyed by path
-		files_by_path = files.inject({}) {|hash, fileinfo|
-			hash[ fileinfo[:full_path] ] = fileinfo
-			hash[ fileinfo[:full_path] ][:outfile] = fileinfo[:full_path] + '.html'
-			hash
-		}
-
-		self.write_style_sheet
-		self.generate_index( options, files_by_path, classes_by_classname )
-		self.generate_class_files( options, files_by_path, classes_by_classname )
-		self.generate_file_files( options, files_by_path, classes_by_classname )
-	end
-
-
-
 	#########
 	protected
 	#########
 
-	### Return a list of the documented modules sorted by salience first, then by name.
+	### Return a list of the documented modules sorted by salience first, then
+	### by name.
 	def get_sorted_module_list( classes )
-		nscounts = classes.keys.inject({}) do |counthash, name|
-			toplevel = name.gsub( /::.*/, '' )
-			counthash[toplevel] ||= 0
-			counthash[toplevel] += 1
-			
+		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 toplevel 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.
-		return classes.keys.sort_by do |name| 
-			toplevel = name.gsub( /::.*/, '' )
+		# 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[ toplevel ] * -1,
-				name
+				nscounts[ top_level ] * -1,
+				klass.full_name
 			]
+		end.select do |klass|
+			klass.document_self
 		end
 	end
-	
-	
+
 	### Generate an index page which lists all the classes which
 	### are documented.
-	def generate_index( options, files, classes )
+	def generate_index
 		debug_msg "Rendering the index page..."
 
 		templatefile = @template_dir + 'index.rhtml'
@@ -237,16 +221,16 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 		template.filename = templatefile.to_s
 		context = binding()
 
-		modsort = self.get_sorted_module_list( classes )
 		output = nil
+
 		begin
 			output = template.result( context )
 		rescue NoMethodError => err
-			raise "Error while evaluating %s: %s (at %p)" % [
+			raise RDoc::Error, "Error while evaluating %s: %s (at %p)" % [
 				templatefile,
 				err.message,
 				eval( "_erbout[-50,50]", context )
-			]
+			], err.backtrace
 		end
 
 		outfile = @basedir + @options.op_dir + 'index.html'
@@ -260,40 +244,30 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 		end
 	end
 
-
-
-	### Generate a documentation file for each class present in the
-	### given hash of +classes+.
-	def generate_class_files( options, files, classes )
+	### Generate a documentation file for each class
+	def generate_class_files
 		debug_msg "Generating class documentation in #@outputdir"
 		templatefile = @template_dir + 'classpage.rhtml'
-		outputdir = @outputdir
 
-		modsort = self.get_sorted_module_list( classes )
-
-		classes.sort_by {|k,v| k }.each do |classname, classinfo|
-			debug_msg "  working on %s (%s)" % [ classname, classinfo[:outfile] ]
-			outfile    = outputdir + classinfo[:outfile]
-			rel_prefix = outputdir.relative_path_from( outfile.dirname )
-			svninfo    = self.get_svninfo( classinfo )
+		@classes.each do |klass|
+			debug_msg "  working on %s (%s)" % [ klass.full_name, klass.path ]
+			outfile    = @outputdir + klass.path
+			rel_prefix = @outputdir.relative_path_from( outfile.dirname )
+			svninfo    = self.get_svninfo( klass )
 
 			debug_msg "  rendering #{outfile}"
 			self.render_template( templatefile, binding(), outfile )
 		end
 	end
 
-
-	### Generate a documentation file for each file present in the
-	### given hash of +files+.
-	def generate_file_files( options, files, classes )
+	### Generate a documentation file for each file
+	def generate_file_files
 		debug_msg "Generating file documentation in #@outputdir"
 		templatefile = @template_dir + 'filepage.rhtml'
 
-		modsort = self.get_sorted_module_list( classes )
-
-		files.sort_by {|k,v| k }.each do |path, fileinfo|
-			outfile     = @outputdir + fileinfo[:outfile]
-			debug_msg "  working on %s (%s)" % [ path, outfile ]
+		@files.each do |file|
+			outfile     = @outputdir + file.path
+			debug_msg "  working on %s (%s)" % [ file.full_name, outfile ]
 			rel_prefix  = @outputdir.relative_path_from( outfile.dirname )
 			context     = binding()
 
@@ -306,7 +280,7 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 	### Return a string describing the amount of time in the given number of
 	### seconds in terms a human can understand easily.
 	def time_delta_string( seconds )
-		return 'less than a minute' if seconds < 1.minute 
+		return 'less than a minute' if seconds < 1.minute
 		return (seconds / 1.minute).to_s + ' minute' + (seconds/60 == 1 ? '' : 's') if seconds < 50.minutes
 		return 'about one hour' if seconds < 90.minutes
 		return (seconds / 1.hour).to_s + ' hours' if seconds < 18.hours
@@ -322,7 +296,7 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 
 	# %q$Id: darkfish.rb 52 2009-01-07 02:08:11Z deveiant $"
 	SVNID_PATTERN = /
-		\$Id:\s 
+		\$Id:\s
 			(\S+)\s					# filename
 			(\d+)\s					# rev
 			(\d{4}-\d{2}-\d{2})\s	# Date (YYYY-MM-DD)
@@ -333,15 +307,14 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 
 	### Try to extract Subversion information out of the first constant whose value looks like
 	### a subversion Id tag. If no matching constant is found, and empty hash is returned.
-	def get_svninfo( classinfo )
-		return {} unless classinfo[:sections]
-		constants = classinfo[:sections].first[:constants] or return {}
-	
-		constants.find {|c| c[:value] =~ SVNID_PATTERN } or return {}
+	def get_svninfo( klass )
+		constants = klass.constants or return {}
+
+		constants.find {|c| c.value =~ SVNID_PATTERN } or return {}
 
 		filename, rev, date, time, committer = $~.captures
 		commitdate = Time.parse( date + ' ' + time )
-		
+
 		return {
 			:filename    => filename,
 			:rev         => Integer( rev ),
@@ -352,23 +325,24 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 	end
 
 
-	### Load and render the erb template in the given +templatefile+ within the specified 
-	### +context+ (a Binding object) and write it out to +outfile+. Both +templatefile+ and 
-	### +outfile+ should be Pathname-like objects.
+	### Load and render the erb template in the given +templatefile+ within the
+	### specified +context+ (a Binding object) and write it out to +outfile+.
+	### Both +templatefile+ and +outfile+ should be Pathname-like objects.
+
 	def render_template( templatefile, context, outfile )
 		template_src = templatefile.read
 		template = ERB.new( template_src, nil, '<>' )
 		template.filename = templatefile.to_s
 
 		output = begin
-			template.result( context )
-		rescue NoMethodError => err
-			raise "Error while evaluating %s: %s (at %p)" % [
-				templatefile.to_s,
-				err.message,
-				eval( "_erbout[-50,50]", context )
-			]
-		end
+							 template.result( context )
+						 rescue NoMethodError => err
+							 raise RDoc::Error, "Error while evaluating %s: %s (at %p)" % [
+								 templatefile.to_s,
+								 err.message,
+								 eval( "_erbout[-50,50]", context )
+							 ], err.backtrace
+						 end
 
 		unless $dryrun
 			outfile.dirname.mkpath
@@ -387,7 +361,7 @@ end # Roc::Generator::Darkfish
 
 ### Time constants
 module TimeConstantMethods # :nodoc:
-	
+
 	### Number of seconds (returns receiver unmodified)
 	def seconds
 		return self
@@ -398,7 +372,7 @@ module TimeConstantMethods # :nodoc:
 	def minutes
 		return self * 60
 	end
-	alias_method :minute, :minutes  
+	alias_method :minute, :minutes
 
 	### Returns the number of seconds in <receiver> hours
 	def hours
@@ -437,14 +411,14 @@ module TimeConstantMethods # :nodoc:
 	alias_method :year, :years
 
 
-	### Returns the Time <receiver> number of seconds before the 
+	### Returns the Time <receiver> number of seconds before the
 	### specified +time+. E.g., 2.hours.before( header.expiration )
 	def before( time )
 		return time - self
 	end
-	
 
-	### Returns the Time <receiver> number of seconds ago. (e.g., 
+
+	### Returns the Time <receiver> number of seconds ago. (e.g.,
 	### expiration > 2.hours.ago )
 	def ago
 		return self.before( ::Time.now )

data/lib/rdoc/generator/markup.rb

@@ -0,0 +1,194 @@
+require 'rdoc/code_objects'
+require 'rdoc/generator'
+require 'rdoc/markup/to_html_crossref'
+
+##
+# Handle common HTML markup tasks for various CodeObjects
+
+module RDoc::Generator::Markup
+
+  ##
+  # Generates a relative URL from this object's path to +target_path+
+
+  def aref_to(target_path)
+    RDoc::Markup::ToHtml.gen_relative_url path, target_path
+  end
+
+  ##
+  # Generates a relative URL from +from_path+ to this object's path
+
+  def as_href(from_path)
+    RDoc::Markup::ToHtml.gen_relative_url from_path, path
+  end
+
+  ##
+  # Handy wrapper for marking up this object's comment
+
+  def description
+    markup @comment
+  end
+
+  ##
+  # RDoc::Markup formatter object
+
+  def formatter
+    return @formatter if defined? @formatter
+
+    show_hash = RDoc::RDoc.current.options.show_hash
+    this = RDoc::Context === self ? self : @parent
+    @formatter = RDoc::Markup::ToHtmlCrossref.new this.path, this, show_hash
+  end
+
+  ##
+  # Convert a string in markup format into HTML.
+
+  def markup(str, remove_para = false)
+    return '' unless str
+
+    # Convert leading comment markers to spaces, but only if all non-blank
+    # lines have them
+    if str =~ /^(?>\s*)[^\#]/ then
+      content = str
+    else
+      content = str.gsub(/^\s*(#+)/) { $1.tr '#', ' ' }
+    end
+
+    res = formatter.convert content
+
+    if remove_para then
+      res.sub!(/^<p>/, '')
+      res.sub!(/<\/p>$/, '')
+    end
+
+    res
+  end
+
+  ##
+  # Build a webcvs URL starting for the given +url+ with +full_path+ appended
+  # as the destination path.  If +url+ contains '%s' +full_path+ will be
+  # sprintf'd into +url+ instead.
+
+  def cvs_url(url, full_path)
+    if /%s/ =~ url then
+      sprintf url, full_path
+    else
+      url + full_path
+    end
+  end
+
+end
+
+class RDoc::AnyMethod
+
+  include RDoc::Generator::Markup
+
+  ##
+  # Prepend +src+ with line numbers.  Relies on the first line of a source
+  # code listing having:
+  #
+  #    # File xxxxx, line dddd
+
+  def add_line_numbers(src)
+    if src =~ /\A.*, line (\d+)/ then
+      first = $1.to_i - 1
+      last  = first + src.count("\n")
+      size = last.to_s.length
+
+      line = first
+      src.gsub!(/^/) do
+        res = if line == first then
+                " " * (size + 2)
+              else
+                "%#{size}d: " % line
+              end
+
+        line += 1
+        res
+      end
+    end
+  end
+
+  ##
+  # Turns the method's token stream into HTML
+
+  def markup_code
+    return '' unless @token_stream
+
+    src = ""
+
+    @token_stream.each do |t|
+      next unless t
+      #        style = STYLE_MAP[t.class]
+      style = case t
+              when RDoc::RubyToken::TkCONSTANT then "ruby-constant"
+              when RDoc::RubyToken::TkKW       then "ruby-keyword kw"
+              when RDoc::RubyToken::TkIVAR     then "ruby-ivar"
+              when RDoc::RubyToken::TkOp       then "ruby-operator"
+              when RDoc::RubyToken::TkId       then "ruby-identifier"
+              when RDoc::RubyToken::TkNode     then "ruby-node"
+              when RDoc::RubyToken::TkCOMMENT  then "ruby-comment cmt"
+              when RDoc::RubyToken::TkREGEXP   then "ruby-regexp re"
+              when RDoc::RubyToken::TkSTRING   then "ruby-value str"
+              when RDoc::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
+
+    add_line_numbers src if RDoc::RDoc.current.options.include_line_numbers
+
+    src
+  end
+
+end
+
+class RDoc::Attr
+
+  include RDoc::Generator::Markup
+
+end
+
+class RDoc::Constant
+
+  include RDoc::Generator::Markup
+
+end
+
+class RDoc::Context
+
+  include RDoc::Generator::Markup
+
+end
+
+class RDoc::Context::Section
+
+  include RDoc::Generator::Markup
+
+end
+
+class RDoc::TopLevel
+
+  ##
+  # Returns a URL for this source file on some web repository.  Use the -W
+  # command line option to set.
+
+  def cvs_url
+    url = RDoc::RDoc.current.options.webcvs
+
+    if /%s/ =~ url then
+      url % @absolute_name
+    else
+      url + @absolute_name
+    end
+  end
+
+end
+