rdoc

[Oleg Puchinin]

Hello !
I want have HTML'd documentation for ruby 1.9.x, but rdoc go awhile. What is wrong ?
$ rm -fr ./doc
$ /opt/rubysvn/bin/rdoc

Oleg.

 

[James Britt]

Hello !
I want have HTML'd documentation for ruby 1.9.x, but rdoc go awhile. What is wrong ?
$ rm -fr ./doc
$ /opt/rubysvn/bin/rdoc

I've the same problem. I run rdoc from ruby 1.9 over the 1.9 source,
and an hour later it's still hasn't finished, but it's busy eating up
memory.

I've tried running the 1.8.6 rdoc over the 1.9 sources, and it fails
over some rdoc syntax error.


How long *should* it take to gen the 1.9 rdocs?


--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.neurogami.com - Smart application development

 

[Ryan Davis]

I've the same problem. I run rdoc from ruby 1.9 over the 1.9
source, and an hour later it's still hasn't finished, but it's busy
eating up memory.

I've tried running the 1.8.6 rdoc over the 1.9 sources, and it fails
over some rdoc syntax error.

How long *should* it take to gen the 1.9 rdocs?

install rdoc2

 

[Roger Pack]

install rdoc2

Let me know if anybody has success with this. I haven't been able to
get *any* rdoc to correctly parse 1.9 yet.

I only get this:


...
working on Base64 (Base64.html)
rendering C:/dev/ruby/downloads/doc/Base64.html
working on BasicObject (BasicObject.html)
rendering C:/dev/ruby/downloads/doc/BasicObject.html
RDoc::Error: Error while evaluating
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/template/darkfish/classpage.rhtml:
undefined method `path' for nil:NilClass (at
"er\">Parent</h3>\n\t\t\t\t\n\t\t\t\t<p class=\"link\"><a href=\"")
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/template/darkfish/classpage.rhtml:65:in
`generate_class_files'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb:269:in
`generate_class_files'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb:262:in
`each'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb:262:in
`generate_class_files'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb:186:in
`generate'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/rdoc.rb:324:in
`document'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/bin/rdoc:15
c:/ruby18/bin/rdoc:19:in `load'
c:/ruby18/bin/rdoc:19

building just its ri results in:

Generating RI...
undefined method `full_name' for nil:NilClass
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/ri.rb:59:in
`generate_class_info'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/ri.rb:44:in
`process_class'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/ri.rb:39:in
`generate'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/ri.rb:38:in
`each'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/ri.rb:38:in
`generate'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/rdoc.rb:324:in
`document'
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/bin/rdoc:15
c:/ruby18/bin/rdoc:19:in `load'
c:/ruby18/bin/rdoc:19

Thanks.
-r

 

[Marvin Gülker]

Let me know if anybody has success with this. I haven't been able to
get *any* rdoc to correctly parse 1.9 yet.

Hi,
I had no problems to generate RDoc for my 1.9.1p243 Ruby, but I didn't
let it document the Ruby installation directory, but the unpackaged
sources tarball. Is there any difference?
My RDoc version is 2.3.0 and I'm using the hanna template. By the way, I
did this with the 1.9 RDoc gem.

Marvin

 

[James Britt]

Hi,
I had no problems to generate RDoc for my 1.9.1p243 Ruby, but I didn't
let it document the Ruby installation directory, but the unpackaged
sources tarball. Is there any difference?

A very big difference, since the idea is to run rdoc over source code,
not compiled binaries.

I've been running rdoc over the 1.9 source tree, and if I omit the lib
and ext dirs it runs very quickly, but if I try to rdoc everything it
just eats memory, and after an hour or 2 I just kill it.

My RDoc version is 2.3.0 and I'm using the hanna template. By the way, I
did this with the 1.9 RDoc gem.

I'm trying to use the rdoc the ships with 1.9, which (presumably) should
work fine.

ruby 1.9.1p243 (2009-07-16 revision 24175) [i386-darwin9.7.0]



--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.neurogami.com - Smart application development

 

[Marvin Gülker]

A very big difference, since the idea is to run rdoc over source code,
not compiled binaries.

I think you've misunderstood. I did not run RDoc over a precompiled
Ruby, but over the sources of Ruby from
ftp://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.1-p243.tar.gz. And even if
I'm not very experienced in C, I don't believe that "array.c" is a
compiled binary.

Marvin

 

[James Britt]

I think you've misunderstood. I did not run RDoc over a precompiled
Ruby, but over the sources of Ruby from
ftp://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.1-p243.tar.gz. And even if
I'm not very experienced in C, I don't believe that "array.c" is a
compiled binary.

Yes, I know that.

You wrote,

" ... but I didn't let it document the Ruby installation directory, but
the unpackaged sources tarball. Is there any difference?"

I was pointing out the difference.


--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.neurogami.com - Smart application development

 

[Roger Pack]

Hi,
I had no problems to generate RDoc for my 1.9.1p243 Ruby, but I didn't
let it document the Ruby installation directory, but the unpackaged
sources tarball. Is there any difference?
My RDoc version is 2.3.0 and I'm using the hanna template. By the way, I
did this with the 1.9 RDoc gem.

Ah yes good point. With hanna and rdocs it does work, now that you
mention it. Where it blows up is using darkfish and/or generating the
ri.

With regard to it eating memory, mine does that [most of the time is
spent in GC since the process is so large]. It eventually terminates.

-r

 

[Nikolai Lugovoi]

I've been running rdoc over the 1.9 source tree, and if I omit the lib and
ext dirs it runs very quickly, but if I try to rdoc everything it just eats
memory, and after an hour or 2 I just kill it.

My RDoc version is 2.3.0 and I'm using the hanna template. By the way, I
did this with the 1.9 RDoc gem.

I'm trying to use the rdoc the ships with 1.9, which (presumably) should
work fine.

ruby 1.9.1p243 (2009-07-16 revision 24175) [i386-darwin9.7.0]

Hi, I see same problem using rdoc from ruby 1.9.2dev (2009-09-13 trunk
24877) -- memory got about 2 gigs after 25 or so minutes, so i killed
process.

And then, just of curiosity, I tried to reduce some sort operations,
and as result I got it well running, I think:

with patch: about ~120Mb memory used
Generating HTML...

Files: 522
Classes: 1370
Modules: 575
Methods: 7896
Elapsed: 357.5s

diff --git a/lib/rdoc/generator.rb b/lib/rdoc/generator.rb
index 86196b4..ca4144a 100644
--- a/lib/rdoc/generator.rb
+++ b/lib/rdoc/generator.rb
@@ -203,7 +203,7 @@ module RDoc::Generator

@methods = list.collect do |m|
RDoc::Generator::Method.new m, self, @options
- end
+ end.sort
end

##
@@ -212,7 +212,7 @@ module RDoc::Generator
def build_method_summary_list(path_prefix = "")
collect_methods unless @methods

- @methods.sort.map do |meth|
+ @methods.map do |meth|
{
"name" => CGI.escapeHTML(meth.name),
"aref" => "##{meth.aref}"
@@ -320,7 +320,7 @@ module RDoc::Generator
def build_method_detail_list(section)
outer = []

- methods = @methods.sort.select do |m|
+ methods = @methods.select do |m|
m.document_self and m.section == section
end

@@ -543,6 +543,9 @@ module RDoc::Generator
@template::METHOD_LIST)

template.write_html_on(f, @values)
+ @values['file_list'] = nil
+ @values['class_list'] = nil
+ @values['method_list'] = nil
end

def value_hash
@@ -785,6 +788,10 @@ module RDoc::Generator
@template::METHOD_LIST)

template.write_html_on(f, @values)
+
+ @values['file_list'] = nil
+ @values['class_list'] = nil
+ @values['method_list'] = nil
end

def file_attribute_values
diff --git a/lib/rdoc/generator/html.rb b/lib/rdoc/generator/html.rb
index 60e0c17..0d7b49d 100644
--- a/lib/rdoc/generator/html.rb
+++ b/lib/rdoc/generator/html.rb
@@ -212,17 +212,20 @@ class RDoc::Generator::HTML
class_list = {}
method_list = {}
prev_op_dir = nil
+ sf = @files.sort
+ sc = @classes.sort
+ sm = RDoc::Generator::Method.all_methods.sort

- list.each do |item|
+ list.sort.each do |item|
next unless item.document_self

op_file = item.path
op_dir = File.dirname(op_file)

if(op_dir != prev_op_dir)
- file_list = index_to_links op_file, @files
- class_list = index_to_links op_file, @classes
- method_list = index_to_links op_file,
RDoc::Generator::Method.all_methods
+ file_list = index_to_links op_file, sf, true
+ class_list = index_to_links op_file, sc, true
+ method_list = index_to_links op_file, sm, true
end
prev_op_dir = op_dir

@@ -323,8 +326,8 @@ class RDoc::Generator::HTML
end
end

- def index_to_links(output_path, collection)
- collection.sort.map do |f|
+ def index_to_links(output_path, collection, sorted = false)
+ (sorted ? collection : collection.sort).map do |f|
next unless f.document_self
{ "href" => RDoc::Markup::ToHtml.gen_relative_url(output_path, f.path),
"name" => f.index_name }

 

[James Britt]

Hi, I see same problem using rdoc from ruby 1.9.2dev (2009-09-13 trunk
24877) -- memory got about 2 gigs after 25 or so minutes, so i killed
process.

And then, just of curiosity, I tried to reduce some sort operations,
and as result I got it well running, I think:

Interesting. Thanks, I may try this.




--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.neurogami.com - Smart application development

 

[James Britt]

And then, just of curiosity, I tried to reduce some sort operations,
and as result I got it well running, I think:

I tried this, and it looks good.

Except for one thing (so far):

Once again, tag.rb in the yaml code, has a stopdoc directive that borks
the rdoc'ing of Module; it completely eliminates it.

This has been reported at least twice, with a patch, but it keeps
returning.

Do people committing code simply not bother checking the actual results
of the rdoc in the source files?



--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.neurogami.com - Smart application development

 

[Ryan Davis]

I tried this, and it looks good.

Except for one thing (so far):

Once again, tag.rb in the yaml code, has a stopdoc directive that
borks the rdoc'ing of Module; it completely eliminates it.

This has been reported at least twice, with a patch, but it keeps
returning.

Do people committing code simply not bother checking the actual
results of the rdoc in the source files?

Huh. I've actually committed the fix before iirc.

Point me in the right direction and I'll do it again. Or throw me a
patch offlist.

 

[James Britt]

Huh. I've actually committed the fix before iirc.

Yes, I know; it's amazing that it keeps returning.

Point me in the right direction and I'll do it again. Or throw me a
patch offlist.

lib/yaml/tags.rb

Around line 53:


class Module
# :stopdoc:




That :stopdoc: needs to go or be changed to something else, as it kills
the rdoc'ing of Module.


Thanks,




James

 

[Ryan Davis]

Yes, I know; it's amazing that it keeps returning.



lib/yaml/tags.rb

OK. Fixed up with the following patch. It'd be nice if we found
someone to take over syck (at least for ruby-core if not in general)
and to fold this patch in:

Index: tag.rb
===================================================================
--- tag.rb (revision 25048)
+++ tag.rb (working copy)
@@ -58,7 +58,7 @@
# taguris.
def yaml_as( tag, sc = true )
verbose, $VERBOSE = $VERBOSE, nil
- class_eval <<-"end;", __FILE__, __LINE__+1
+ class_eval <<-"END", __FILE__, __LINE__+1
attr_writer :taguri
def taguri
if respond_to? :to_yaml_type
@@ -73,7 +73,7 @@
end
end
def self.yaml_tag_subclasses?; #{ sc ? 'true' :
'false' }; end
- end;
+ END
YAML::tag_class tag, self
ensure
$VERBOSE = verbose
@@ -88,4 +88,5 @@
def yaml_tag_read_class( name )
name
end
+ # :startdoc:
end

 

[Roger Pack]

Generating RI...
undefined method `full_name' for nil:NilClass
c:/ruby18/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/ri.rb:59:in
`generate_class_info'

Appears if you checkout rdoc from SVN trunk (and apply a patch [1])
it works (with darkfish).
Thanks rdoc guys!
-r
[1]
http://github.com/rdp/rdoc/commit/1ff68c953fa7f6eae067a38d06c5d6bf06602e18

 

[Roger Pack]

--- a/lib/rdoc/generator.rb

+++ b/lib/rdoc/generator.rb
@@ -203,7 +203,7 @@ module RDoc::Generator

@methods = list.collect do |m|
RDoc::Generator::Method.new m, self, @options
- end
+ end.sort
end

It appears that many of these optimizations was applied in rdoc v 2.3.0
(1.9 comes with 2.2.2 installed by default).
I also took the liberty of trying to make a "faster" 2.3.0 here:
http://github.com/rdp/rdoc2
if it's useful for anybody.

By version 2.4.3 things have changed quite a bit so I'm not sure if
there are optimizations to be made or not.
Thanks!

-r