* 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

ChangeLog

@@ -1,3 +1,10 @@
+Tue Nov 27 17:43:46 2012  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/rdoc/*:  Added --root option for building documentation outside
+	  the source directory.
+	* test/rdoc/*:  ditto
+	* common.mk (rdoc):  Added --root to rdoc rule
+
 Tue Nov 27 16:24:45 2012  Eric Hodel  <drbrain@segment7.net>
 
 	* test/rdoc/test_rdoc_ri_paths.rb:  Fixed duplicate path bug which

common.mk

@@ -408,11 +408,11 @@ post-install-doc::
 
 rdoc: PHONY main
 	@echo Generating RDoc documentation
-	$(Q) $(XRUBY) "$(srcdir)/bin/rdoc" --encoding=UTF-8 --no-force-update --all --ri --op "$(RDOCOUT)" --debug $(RDOCFLAGS) "$(srcdir)"
+	$(Q) $(XRUBY) "$(srcdir)/bin/rdoc" --root "$(srcdir)" --encoding=UTF-8 --no-force-update --all --ri --op "$(RDOCOUT)" --debug $(RDOCFLAGS) "$(srcdir)"
 
 rdoc-coverage: PHONY main
 	@echo Generating RDoc coverage report
-	$(Q) $(XRUBY) "$(srcdir)/bin/rdoc" --encoding=UTF-8 --all --quiet -C $(RDOCFLAGS) "$(srcdir)"
+	$(Q) $(XRUBY) "$(srcdir)/bin/rdoc" --root "$(srcdir)" --encoding=UTF-8 --all --quiet -C $(RDOCFLAGS) "$(srcdir)"
 
 nodoc: PHONY
 

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,

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

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,

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

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,

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
 

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>

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

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
@@ -104,6 +106,12 @@ class RDoc::Options
     write_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.
@@ -230,6 +238,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
 
@@ -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
 
@@ -673,6 +697,17 @@ Usage: #{opt.program_name} [options] [names...]
         @markup = value
       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

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
 

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
 

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

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

test/rdoc/test_rdoc_options.rb

@@ -430,6 +430,19 @@ rdoc_include:
     assert_equal 'tomdoc', @options.markup
   end
 
+  def test_parse_root
+    assert_equal Pathname(Dir.pwd), @options.root
+
+    out, err = capture_io do
+      @options.parse %W[--root #{Dir.tmpdir}]
+    end
+
+    assert_empty out
+    assert_empty err
+
+    assert_equal Pathname(Dir.tmpdir), @options.root
+  end
+
   def test_parse_template
     out, err = capture_io do
       @options.parse %w[--template darkfish]

test/rdoc/test_rdoc_parser_ruby.rb

@@ -1026,7 +1026,7 @@ EOF
 
     stream = [
       tk(:COMMENT, 0, 1, 1, nil,
-         "# File #{@top_level.absolute_name}, line 1"),
+         "# File #{@top_level.relative_name}, line 1"),
       RDoc::Parser::Ruby::NEWLINE_TOKEN,
       tk(:SPACE,   0, 1, 1, nil, ''),
     ]
@@ -1199,7 +1199,7 @@ EOF
 
     stream = [
       tk(:COMMENT,     0, 1, 1,  nil,
-         "# File #{@top_level.absolute_name}, line 1"),
+         "# File #{@top_level.relative_name}, line 1"),
       RDoc::Parser::Ruby::NEWLINE_TOKEN,
       tk(:SPACE,       0, 1, 1,  nil, ''),
       tk(:IDENTIFIER,  0, 1, 0,  'add_my_method', 'add_my_method'),
@@ -1397,7 +1397,7 @@ end
 
     stream = [
       tk(:COMMENT,     0, 1, 1,  nil,
-         "# File #{@top_level.absolute_name}, line 1"),
+         "# File #{@top_level.relative_name}, line 1"),
       RDoc::Parser::Ruby::NEWLINE_TOKEN,
       tk(:SPACE,       0, 1, 1,  nil,   ''),
       tk(:DEF,         0, 1, 0,  'def', 'def'),

test/rdoc/test_rdoc_rdoc.rb

@@ -141,6 +141,50 @@ class TestRDocRDoc < RDoc::TestCase
     assert_match %r%/dev/stdin$%,       err
   end
 
+  def test_parse_file
+    pwd = Dir.pwd
+
+    @rdoc.store = RDoc::Store.new
+
+    temp_dir do |dir|
+      @rdoc.options.root = Pathname(Dir.pwd)
+
+      open 'test.txt', 'w' do |io|
+        io.puts 'hi'
+      end
+
+      test_txt = File.join dir, 'test.txt'
+
+      top_level = @rdoc.parse_file 'test.txt'
+
+      assert_equal 'test.txt', top_level.absolute_name
+      assert_equal 'test.txt', top_level.relative_name
+    end
+  end
+
+  def test_parse_file_relative
+    pwd = Dir.pwd
+
+    @rdoc.store = RDoc::Store.new
+
+    temp_dir do |dir|
+      @rdoc.options.root = Pathname(dir)
+
+      open 'test.txt', 'w' do |io|
+        io.puts 'hi'
+      end
+
+      test_txt = File.join dir, 'test.txt'
+
+      Dir.chdir pwd do
+        top_level = @rdoc.parse_file test_txt
+
+        assert_equal test_txt,   top_level.absolute_name
+        assert_equal 'test.txt', top_level.relative_name
+      end
+    end
+  end
+
   def test_parse_file_encoding
     skip "Encoding not implemented" unless Object.const_defined? :Encoding
     @rdoc.options.encoding = Encoding::ISO_8859_1

test/rdoc/test_rdoc_store.rb

@@ -127,6 +127,21 @@ class TestRDocStore < XrefTestCase
     refute_same top_level, @store.add_file('other.rb')
   end
 
+  def test_add_file_relative
+    top_level = @store.add_file 'path/file.rb', 'file.rb'
+
+    assert_kind_of RDoc::TopLevel, top_level
+    assert_equal @store, top_level.store
+
+    assert_equal 'path/file.rb', top_level.absolute_name
+    assert_equal 'file.rb',      top_level.relative_name
+
+    assert_includes @store.all_files, top_level
+
+    assert_same top_level, @store.add_file('file.rb')
+    refute_same top_level, @store.add_file('other.rb')
+  end
+
   def test_all_classes_and_modules
     expected = %w[
       C1 C2 C2::C3 C2::C3::H1 C3 C3::H1 C3::H2 C4 C4::C4 C5 C5::C1

test/rdoc/test_rdoc_top_level.rb

@@ -9,6 +9,20 @@ class TestRDocTopLevel < XrefTestCase
     @top_level.parser = RDoc::Parser::Ruby
   end
 
+  def test_initialize
+    t = RDoc::TopLevel.new 'path/file.rb'
+
+    assert_equal 'path/file.rb', t.absolute_name
+    assert_equal 'path/file.rb', t.relative_name
+  end
+
+  def test_initialize_relative
+    t = RDoc::TopLevel.new 'path/file.rb', 'file.rb'
+
+    assert_equal 'path/file.rb', t.absolute_name
+    assert_equal 'file.rb',      t.relative_name
+  end
+
   def test_add_alias
     a = RDoc::Alias.new nil, 'old', 'new', nil
     @top_level.add_alias a