summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-11-27 08:54:03 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-11-27 08:54:03 +0000
commit6d1266a879a94a6f76106e1bbdfa3576b6612a69 (patch)
tree5c88a98d9e588861138e63be7d45353627dcab43
parent7de9e2dfdeefeefe6c3d4ff9ebafa8c947eca33f (diff)
* 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
-rw-r--r--ChangeLog7
-rw-r--r--common.mk4
-rw-r--r--lib/rdoc/any_method.rb2
-rw-r--r--lib/rdoc/attr.rb2
-rw-r--r--lib/rdoc/class_module.rb2
-rw-r--r--lib/rdoc/comment.rb2
-rw-r--r--lib/rdoc/constant.rb2
-rw-r--r--lib/rdoc/generator/markup.rb4
-rw-r--r--lib/rdoc/generator/template/darkfish/_sidebar_in_files.rhtml2
-rw-r--r--lib/rdoc/markup/document.rb2
-rw-r--r--lib/rdoc/options.rb35
-rw-r--r--lib/rdoc/parser/ruby.rb8
-rw-r--r--lib/rdoc/rdoc.rb6
-rw-r--r--lib/rdoc/store.rb8
-rw-r--r--lib/rdoc/top_level.rb26
-rw-r--r--test/rdoc/test_rdoc_options.rb13
-rw-r--r--test/rdoc/test_rdoc_parser_ruby.rb6
-rw-r--r--test/rdoc/test_rdoc_rdoc.rb44
-rw-r--r--test/rdoc/test_rdoc_store.rb15
-rw-r--r--test/rdoc/test_rdoc_top_level.rb14
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 <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
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 @@
<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
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