* lib/rdoc/*: Added --root option for building documentation outside

  the source directory.
* test/rdoc/*:  ditto
* common.mk (rdoc):  Added --root to rdoc rule


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@37896 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

13 files changed, 71 insertions, 30 deletions

diff --git a/lib/rdoc/any_method.rb b/lib/rdoc/any_method.rb
index c3d68e87b4..b32690aa7d 100644
--- a/lib/rdoc/any_method.rb
+++ b/lib/rdoc/any_method.rb
@@ -107,7 +107,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       @block_params,
       aliases,
       @params,
-      @file.absolute_name,
+      @file.relative_name,
       @calls_super,
       @parent.name,
       @parent.class,
diff --git a/lib/rdoc/attr.rb b/lib/rdoc/attr.rb
index 0eb1c0d79b..155215ff99 100644
--- a/lib/rdoc/attr.rb
+++ b/lib/rdoc/attr.rb
@@ -106,7 +106,7 @@ class RDoc::Attr < RDoc::MethodAttr
       @visibility,
       parse(@comment),
       singleton,
-      @file.absolute_name,
+      @file.relative_name,
       @parent.full_name,
       @parent.class,
       @section.title
diff --git a/lib/rdoc/class_module.rb b/lib/rdoc/class_module.rb
index 04f0132b7d..e2bb9de68d 100644
--- a/lib/rdoc/class_module.rb
+++ b/lib/rdoc/class_module.rb
@@ -304,7 +304,7 @@ class RDoc::ClassModule < RDoc::Context
       end,
       @sections.values,
       @in_files.map do |tl|
-        tl.absolute_name
+        tl.relative_name
       end,
       parent.full_name,
       parent.class,
diff --git a/lib/rdoc/comment.rb b/lib/rdoc/comment.rb
index 25e7c966c8..2b5be44ee5 100644
--- a/lib/rdoc/comment.rb
+++ b/lib/rdoc/comment.rb
@@ -148,7 +148,7 @@ class RDoc::Comment
   end
 
   def inspect # :nodoc:
-    location = @location ? @location.absolute_name : '(unknown)'
+    location = @location ? @location.relative_name : '(unknown)'
 
     "#<%s:%x %s %p>" % [self.class, object_id, location, @text]
   end
diff --git a/lib/rdoc/constant.rb b/lib/rdoc/constant.rb
index d9fcf021ed..48b32aaf98 100644
--- a/lib/rdoc/constant.rb
+++ b/lib/rdoc/constant.rb
@@ -109,7 +109,7 @@ class RDoc::Constant < RDoc::CodeObject
       @visibility,
       alias_name,
       parse(@comment),
-      @file.absolute_name,
+      @file.relative_name,
       parent.name,
       parent.class,
       section.title,
diff --git a/lib/rdoc/generator/markup.rb b/lib/rdoc/generator/markup.rb
index 3b3546690e..788e5a485d 100644
--- a/lib/rdoc/generator/markup.rb
+++ b/lib/rdoc/generator/markup.rb
@@ -159,9 +159,9 @@ class RDoc::TopLevel
     url = @store.rdoc.options.webcvs
 
     if /%s/ =~ url then
-      url % @absolute_name
+      url % @relative_name
     else
-      url + @absolute_name
+      url + @relative_name
     end
   end
 
diff --git a/lib/rdoc/generator/template/darkfish/_sidebar_in_files.rhtml b/lib/rdoc/generator/template/darkfish/_sidebar_in_files.rhtml
index c4ae216a14..22be0c9b65 100644
--- a/lib/rdoc/generator/template/darkfish/_sidebar_in_files.rhtml
+++ b/lib/rdoc/generator/template/darkfish/_sidebar_in_files.rhtml
@@ -2,7 +2,7 @@
   <h3 class="section-header">Defined In</h3>
   <ul>
 <% klass.in_files.each do |tl| %>
-    <li><%= h tl.absolute_name %>
+    <li><%= h tl.relative_name %>
 <% end %>
   </ul>
 </nav>
diff --git a/lib/rdoc/markup/document.rb b/lib/rdoc/markup/document.rb
index 198cef9ed9..049cd3b43c 100644
--- a/lib/rdoc/markup/document.rb
+++ b/lib/rdoc/markup/document.rb
@@ -96,7 +96,7 @@ class RDoc::Markup::Document
   def file= location
     @file = case location
             when RDoc::TopLevel then
-              location.absolute_name
+              location.relative_name
             else
               location
             end
diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb
index d862b0adf3..57d457a830 100644
--- a/lib/rdoc/options.rb
+++ b/lib/rdoc/options.rb
@@ -1,4 +1,5 @@
 require 'optparse'
+require 'pathname'
 
 ##
 # RDoc::Options handles the parsing and storage of options
@@ -95,6 +96,7 @@ class RDoc::Options
     option_parser
     pipe
     rdoc_include
+    root
     static_path
     stylesheet_url
     template
@@ -105,6 +107,12 @@ class RDoc::Options
   ]
 
   ##
+  # Option validator for OptionParser that matches a directory that exists on
+  # the filesystem.
+
+  Directory = Object.new
+
+  ##
   # Option validator for OptionParser that matches a file or directory that
   # exists on the filesystem.
 
@@ -231,6 +239,13 @@ class RDoc::Options
   attr_accessor :rdoc_include
 
   ##
+  # Root of the source documentation will be generated for.  Set this when
+  # building documentation outside the source directory.  Defaults to the
+  # current directory.
+
+  attr_accessor :root
+
+  ##
   # Include the '#' at the front of hyperlinked instance method names
 
   attr_accessor :show_hash
@@ -304,6 +319,7 @@ class RDoc::Options
     @op_dir = nil
     @pipe = false
     @rdoc_include = []
+    @root = Pathname(Dir.pwd)
     @show_hash = false
     @static_path = []
     @stylesheet_url = nil # TODO remove in RDoc 4
@@ -562,6 +578,14 @@ Usage: #{opt.program_name} [options] [names...]
         end
       end
 
+      opt.accept Directory do |directory|
+        directory = File.expand_path directory
+
+        raise OptionParser::InvalidArgument unless File.directory? directory
+
+        directory
+      end
+
       opt.accept Path do |path|
         path = File.expand_path path
 
@@ -674,6 +698,17 @@ Usage: #{opt.program_name} [options] [names...]
       end
 
       opt.separator nil
+
+      opt.on("--root=ROOT", Directory,
+             "Root of the source tree documentation",
+             "will be generated for.  Set this when",
+             "building documentation outside the",
+             "source directory.  Default is the",
+             "current directory.") do |root|
+        @root = Pathname(root)
+      end
+
+      opt.separator nil
       opt.separator "Common generator options:"
       opt.separator nil
 
diff --git a/lib/rdoc/parser/ruby.rb b/lib/rdoc/parser/ruby.rb
index 0b207fae3b..0e1e012650 100644
--- a/lib/rdoc/parser/ruby.rb
+++ b/lib/rdoc/parser/ruby.rb
@@ -785,7 +785,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
       indent.set_text " " * column
 
       position_comment = TkCOMMENT.new 0, line_no, 1
-      position_comment.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
+      position_comment.set_text "# File #{@top_level.relative_name}, line #{line_no}"
       meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
 
       meth.params = ''
@@ -843,7 +843,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     indent.set_text " " * offset
 
     position_comment = TkCOMMENT.new 0, line_no, 1
-    position_comment.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
+    position_comment.set_text "# File #{@top_level.relative_name}, line #{line_no}"
     meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
 
     meth.call_seq = signature
@@ -1015,7 +1015,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     indent.set_text " " * column
 
     position_comment = TkCOMMENT.new 0, line_no, 1
-    position_comment.value = "# File #{@top_level.absolute_name}, line #{line_no}"
+    position_comment.value = "# File #{@top_level.relative_name}, line #{line_no}"
     meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
     meth.add_tokens @token_stream
 
@@ -1171,7 +1171,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     indent.set_text " " * column
 
     token = TkCOMMENT.new 0, line_no, 1
-    token.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
+    token.set_text "# File #{@top_level.relative_name}, line #{line_no}"
     meth.add_tokens [token, NEWLINE_TOKEN, indent]
     meth.add_tokens @token_stream
 
diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb
index d72e686249..eabf4fd3f7 100644
--- a/lib/rdoc/rdoc.rb
+++ b/lib/rdoc/rdoc.rb
@@ -2,6 +2,7 @@ require 'rdoc'
 
 require 'find'
 require 'fileutils'
+require 'pathname'
 require 'time'
 
 ##
@@ -345,7 +346,10 @@ option)
 
     return unless content
 
-    top_level = @store.add_file filename
+    filename_path = Pathname(filename).expand_path
+    relative_path = filename_path.relative_path_from @options.root
+
+    top_level = @store.add_file filename, relative_path.to_s
 
     parser = RDoc::Parser.for top_level, filename, content, @options, @stats
 
diff --git a/lib/rdoc/store.rb b/lib/rdoc/store.rb
index ee58a4d873..00c1010802 100644
--- a/lib/rdoc/store.rb
+++ b/lib/rdoc/store.rb
@@ -139,11 +139,11 @@ class RDoc::Store
   # Adds the file with +name+ as an RDoc::TopLevel to the store.  Returns the
   # created RDoc::TopLevel.
 
-  def add_file name
-    unless top_level = @files_hash[name] then
-      top_level = RDoc::TopLevel.new name
+  def add_file absolute_name, relative_name = absolute_name
+    unless top_level = @files_hash[relative_name] then
+      top_level = RDoc::TopLevel.new absolute_name, relative_name
       top_level.store = self
-      @files_hash[name] = top_level
+      @files_hash[relative_name] = top_level
     end
 
     top_level
diff --git a/lib/rdoc/top_level.rb b/lib/rdoc/top_level.rb
index 9cf38539de..f4952fb6ff 100644
--- a/lib/rdoc/top_level.rb
+++ b/lib/rdoc/top_level.rb
@@ -35,14 +35,16 @@ class RDoc::TopLevel < RDoc::Context
   attr_accessor :parser
 
   ##
-  # Creates a new TopLevel for +file_name+
+  # Creates a new TopLevel for the file at +absolute_name+.  If documentation
+  # is being generated outside the source dir +relative_name+ is relative to
+  # the source directory.
 
-  def initialize file_name
+  def initialize absolute_name, relative_name = absolute_name
     super()
     @name = nil
-    @relative_name = file_name
-    @absolute_name = file_name
-    @file_stat     = File.stat(file_name) rescue nil # HACK for testing
+    @absolute_name = absolute_name
+    @relative_name = relative_name
+    @file_stat     = File.stat(absolute_name) rescue nil # HACK for testing
     @diagram       = nil
     @parser        = nil
 
@@ -50,10 +52,10 @@ class RDoc::TopLevel < RDoc::Context
   end
 
   ##
-  # An RDoc::TopLevel is equal to another with the same absolute_name
+  # An RDoc::TopLevel is equal to another with the same relative_name
 
   def == other
-    self.class === other and @absolute_name == other.absolute_name
+    self.class === other and @relative_name == other.relative_name
   end
 
   alias eql? ==
@@ -106,7 +108,7 @@ class RDoc::TopLevel < RDoc::Context
   # Base name of this file
 
   def base_name
-    File.basename @absolute_name
+    File.basename @relative_name
   end
 
   alias name base_name
@@ -152,10 +154,10 @@ class RDoc::TopLevel < RDoc::Context
 
   ##
   # An RDoc::TopLevel has the same hash as another with the same
-  # absolute_name
+  # relative_name
 
   def hash
-    @absolute_name.hash
+    @relative_name.hash
   end
 
   ##
@@ -188,7 +190,7 @@ class RDoc::TopLevel < RDoc::Context
   def marshal_dump
     [
       MARSHAL_VERSION,
-      @absolute_name,
+      @relative_name,
       @parser,
       parse(@comment),
     ]
@@ -223,7 +225,7 @@ class RDoc::TopLevel < RDoc::Context
   # Base name of this file without the extension
 
   def page_name
-    basename = File.basename @absolute_name
+    basename = File.basename @relative_name
     basename =~ /\.[^.]*$/
 
     $` || basename