Rdoc

Oleg_P · September 2, 2009, 11:23am

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.

Oleg_P · September 12, 2009, 6:29am

Oleg P. wrote:

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 B.

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

Oleg_P · September 12, 2009, 9:15am

On Sep 11, 2009, at 21:28 , James B. wrote:

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

Oleg_P · September 12, 2009, 3:51pm

Ryan D. wrote:

On Sep 11, 2009, at 21:28 , James B. wrote:

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

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:ingenerate_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:ineach’
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:ingenerate’
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:inload’
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:ingenerate_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:ingenerate’
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:ingenerate’
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:inload’
c:/ruby18/bin/rdoc:19

Thanks.
-r

Oleg_P · September 12, 2009, 5:36pm

Roger P. wrote:

Ryan D. wrote:

On Sep 11, 2009, at 21:28 , James B. wrote:

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

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

Oleg_P · September 12, 2009, 6:09pm

Marvin Gülker wrote:

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 B.

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

Oleg_P · September 12, 2009, 8:33pm

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

Oleg_P · September 12, 2009, 7:23pm

James B. wrote:

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

Oleg_P · September 12, 2009, 9:03pm

Marvin Gülker wrote:

James B. wrote:

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.

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 B.

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

Oleg_P · September 12, 2009, 11:49pm

On Sat, Sep 12, 2009 at 7:08 PM, James B. [email protected]
wrote:

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 }

Oleg_P · September 13, 2009, 5:20am

Nikolai L. wrote:

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 B.

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

Oleg_P · September 13, 2009, 8:59am

On Sep 12, 2009, at 20:19 , James B. wrote:

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.

Oleg_P · September 13, 2009, 12:01am

Nikolai L. wrote:

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 B.

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

Oleg_P · September 24, 2009, 11:11pm

On Sep 13, 2009, at 09:14 , James B. wrote:

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

Oleg_P · October 23, 2009, 10:59pm

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

Oleg_P · September 13, 2009, 6:14pm

Ryan D. wrote:

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

Oleg_P · October 24, 2009, 1:03am

— 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

Rdoc

Index: tag.rb

:startdoc: