Incorporating gem documentation into ri

J

John Wells

Guys,

I'd like to incorporation the various gem rdocs into ri, so that I am
not forced to use gem_server to view the documentation. I've found old
posts on this subject but nothing conclusive. Surely there is a way to
do this?

Any help you can provide is _greatly_ appreciated.

Thanks!
John
 
J

James Britt

John said:
Guys,

I'd like to incorporation the various gem rdocs into ri, so that I am
not forced to use gem_server to view the documentation. I've found old
posts on this subject but nothing conclusive. Surely there is a way to
do this?

Any help you can provide is _greatly_ appreciated.

I believe you can run rdoc -r ... over the gem's source code, and it
will add the docs to your ri data set.

Warning: If the gem code defines methods on core classes then your base
ri data source could get munged. Ri is not really designed for arbitrary
additions.

(I hope I'm wrong about this, but my last experience was running rdoc -r
over the standard lib source, and ending up with broken core docs
because some code had added or redefined methods in Array, String, and
so on.)
 
D

Dave Thomas

--Apple-Mail-13--935389132
Content-Transfer-Encoding: 7bit
Content-Type: text/plain;
charset=US-ASCII;
delsp=yes;
format=flowed


Warning: If the gem code defines methods on core classes then your
base ri data source could get munged. Ri is not really designed for
arbitrary additions.

(I hope I'm wrong about this, but my last experience was running
rdoc -r over the standard lib source, and ending up with broken
core docs because some code had added or redefined methods in
Array, String, and so on.)


Possibly you didn't use the --merge and --ri-system or --ri-site
options?


Dave
--Apple-Mail-13--935389132--
 
J

John Wells

Thanks guys. When I try doing this (), it goes on for awhile and then
hits this:

rrails-1.0.0/lib/rails_generator/generators/components/controller/templates/controller.rb:3:15:
Expected class name or '<<'. Got RubyToken::TkLT: "<"

Then it just sits there....never completing.

Any idea what might be causing this?

Thanks!
John
 
E

Eric Hodel

Thanks guys. When I try doing this (), it goes on for awhile and then
hits this:

rrails-1.0.0/lib/rails_generator/generators/components/controller/
templates/controller.rb:3:15:
Expected class name or '<<'. Got RubyToken::TkLT: "<"

Then it just sits there....never completing.

Any idea what might be causing this?

RDoc looks for RDoc in .rb files. Since that file is not a ruby
file, RDoc needs to be told not to attempt to scan it.

For the Rails gem, the Rakefile tells RDoc not to scan this file.
You should follow its wisdom.

The other way to prevent/include files in RDoc's search is
with .document files containing the names of files and paths to
document.
 
J

John Wells

Eric said:
RDoc looks for RDoc in .rb files. Since that file is not a ruby
file, RDoc needs to be told not to attempt to scan it.

For the Rails gem, the Rakefile tells RDoc not to scan this file.
You should follow its wisdom.

The other way to prevent/include files in RDoc's search is
with .document files containing the names of files and paths to
document.

Hmmm...you're right...this doesn't look like a true Ruby file, although
it'll be difficult to filter it out because of it's .rb extension.

How does the Rakefile know what to scan and what not? I guess that'll be
my next area of research. Would it be easier to modify gem itself to do
this task? Perhaps this should be a candidate for inclusion as an option
to gem?

Thanks!
John
 
J

John Wells

Hmmm...you're right...this doesn't look like a true Ruby file, although
it'll be difficult to filter it out because of it's .rb extension.

How does the Rakefile know what to scan and what not? I guess that'll be
my next area of research. Would it be easier to modify gem itself to do
this task? Perhaps this should be a candidate for inclusion as an option
to gem?
Success!

Apparently, someone had already thought of doing this and didn't, as
evidenced by the following lines in rubygems/doc_manager.rb:

#TODO: Why is this throwing an error?
#ri = RDoc::RDoc.new
#ri.document(['-R'] + source_dirs)

Anyway, I was successful...I'll look at making this more integrated and
submitting as a patch, but for the quick hack all it took was changing
the following line (58 in my version):

r.document(['--quiet', '--op', rdoc_dir] + @rdoc_args.flatten +
source_dirs)

to:

r.document(['--quiet', '--op', '--merge', '-r', '--ri-system', rdoc_dir]
+ @rdoc_args.flatten + source_dirs)

It worked perfectly...all Rails classes, etc, are now in ri.

Thanks guys!

John
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,743
Messages
2,569,478
Members
44,899
Latest member
RodneyMcAu

Latest Threads

Top