From 6d1266a879a94a6f76106e1bbdfa3576b6612a69 Mon Sep 17 00:00:00 2001 From: drbrain Date: Tue, 27 Nov 2012 08:54:03 +0000 Subject: [PATCH] * 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 | 7 +++ common.mk | 4 +- lib/rdoc/any_method.rb | 2 +- lib/rdoc/attr.rb | 2 +- lib/rdoc/class_module.rb | 2 +- lib/rdoc/comment.rb | 2 +- lib/rdoc/constant.rb | 2 +- lib/rdoc/generator/markup.rb | 4 +- .../template/darkfish/_sidebar_in_files.rhtml | 2 +- lib/rdoc/markup/document.rb | 2 +- lib/rdoc/options.rb | 35 +++++++++++++++ lib/rdoc/parser/ruby.rb | 8 ++-- lib/rdoc/rdoc.rb | 6 ++- lib/rdoc/store.rb | 8 ++-- lib/rdoc/top_level.rb | 26 ++++++----- test/rdoc/test_rdoc_options.rb | 13 ++++++ test/rdoc/test_rdoc_parser_ruby.rb | 6 +-- test/rdoc/test_rdoc_rdoc.rb | 44 +++++++++++++++++++ test/rdoc/test_rdoc_store.rb | 15 +++++++ test/rdoc/test_rdoc_top_level.rb | 14 ++++++ 20 files changed, 169 insertions(+), 35 deletions(-) diff --git a/ChangeLog b/ChangeLog index c5b6d1a985..3ea832658e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Tue Nov 27 17:43:46 2012 Eric Hodel + + * 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 * test/rdoc/test_rdoc_ri_paths.rb: Fixed duplicate path bug which diff --git a/common.mk b/common.mk index 3429f821b0..fb55427d52 100644 --- a/common.mk +++ b/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 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 @@

Defined In

    <% klass.in_files.each do |tl| %> -
  • <%= h tl.absolute_name %> +
  • <%= h tl.relative_name %> <% end %>
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 @@ -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 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 diff --git a/test/rdoc/test_rdoc_options.rb b/test/rdoc/test_rdoc_options.rb index be95580ee4..14ccd0de0f 100644 --- a/test/rdoc/test_rdoc_options.rb +++ b/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] diff --git a/test/rdoc/test_rdoc_parser_ruby.rb b/test/rdoc/test_rdoc_parser_ruby.rb index b25a36301e..8168cd3f45 100644 --- a/test/rdoc/test_rdoc_parser_ruby.rb +++ b/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'), diff --git a/test/rdoc/test_rdoc_rdoc.rb b/test/rdoc/test_rdoc_rdoc.rb index b0a0fadc49..5ed7ce77b0 100644 --- a/test/rdoc/test_rdoc_rdoc.rb +++ b/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 diff --git a/test/rdoc/test_rdoc_store.rb b/test/rdoc/test_rdoc_store.rb index 1b87ca6036..1bf42bc92c 100644 --- a/test/rdoc/test_rdoc_store.rb +++ b/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 diff --git a/test/rdoc/test_rdoc_top_level.rb b/test/rdoc/test_rdoc_top_level.rb index 61f4362d09..9c7a3db66f 100644 --- a/test/rdoc/test_rdoc_top_level.rb +++ b/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