# How do I find and view all those RDoc files scattered on my

**URL:** <https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889>\
**Category:** Rails\
**Created:** [July 9, 2007, 2:47am UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889 "2007-07-09T02:47:05Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![Jim\_Gagne](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/dbc845/32.png) [@Jim\_Gagne](https://www.ruby-forum.com/u/Jim_Gagne)\
**Post date:** [July 9, 2007, 2:47am UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889/1 "2007-07-09T02:47:05Z")

</div>

Every time I download and install a MacPort, Ruby gem, or similar  
software, the installer makes RI and RDoc files. They’re apt to be  
called “index.html”. I’ve never been able to find a way to access  
these files. Searching for “index.html” on my hard drive produces a  
list of hundreds of files, most of which are useless. Moreover, many  
installs go to a part of the hard drive where only root has read  
permissions. So I’m seeing only a fraction of the RDocs on my system.

Aarrghh!!

Any suggestions on how to access – and most importantly organize –  
these files?

—Jim Gagne—

---

<div class="post-metadata">

**Author:** ![Jim\_Gagne](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/dbc845/32.png) [@Jim\_Gagne](https://www.ruby-forum.com/u/Jim_Gagne)\
**Post date:** [July 9, 2007, 9:20am UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889/2 "2007-07-09T09:20:06Z")

</div>

Jim Gagne wrote:

> Every time I download and install a MacPort, Ruby gem, or similar  
> software, the installer makes RI and RDoc files. They’re apt to be  
> called “index.html”. I’ve never been able to find a way to access  
> these files. Searching for “index.html” on my hard drive produces a  
> list of hundreds of files, most of which are useless. Moreover, many  
> installs go to a part of the hard drive where only root has read  
> permissions. So I’m seeing only a fraction of the RDocs on my system.
> 
> Aarrghh!!
> 
> Any suggestions on how to access – and most importantly organize –  
> these files?
> 
> —Jim Gagne—

you can create your own rdoc files, if you run rdoc. it creates the doc  
files (index.html).

[http://rdoc.sourceforge.net/doc/index.html](http://rdoc.sourceforge.net/doc/index.html)

---

<div class="post-metadata">

**Author:** ![Jim\_Gagne](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/dbc845/32.png) [@Jim\_Gagne](https://www.ruby-forum.com/u/Jim_Gagne)\
**Post date:** [July 9, 2007, 5:44pm UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889/3 "2007-07-09T17:44:34Z")

</div>

> Any suggestions on how to access – and most importantly organize –  
> these files?

From a command line run  
$ gem\_server

Then browse to [http://localhost:8808/](http://localhost:8808/) . This, at least on my machine,  
gives me a browseable interface to the documentation all of the gems I  
have installed. I’m not sure if this will apply to software installed  
with ports though.

Regards,

Chris

---

<div class="post-metadata">

**Author:** ![Jim\_Gagne](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/dbc845/32.png) [@Jim\_Gagne](https://www.ruby-forum.com/u/Jim_Gagne)\
**Post date:** [July 10, 2007, 9:58am UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889/4 "2007-07-10T09:58:26Z")

</div>

> Running the rake doc:rails also generates an error:  
> jimgagne% rake doc:rails  
> (in /Users/jimgagne/Documents/Rails/testproject)  
> rake aborted!  
> Don’t know how to build task ‘vendor/rails/railties/CHANGELOG’

the error you got is telling you that it can’t build the task that  
doc:rails is trying to do (it is trying to create rdocs out of a vendor  
directory, which exists in rails projects … if you create a new rails  
project and run this command in the RAILS\_ROOT directory, you shouldn’t  
get an error.

> jimgagne% rake doc:rails  
> rake doc:app

where are you running the commands from? it seems like these errors are  
cause by bad paths. you have to run the rake doc:task command from the  
correct directory for it to work…

---

<div class="post-metadata">

**Author:** ![Jim\_Gagne](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/dbc845/32.png) [@Jim\_Gagne](https://www.ruby-forum.com/u/Jim_Gagne)\
**Post date:** [July 11, 2007, 6:55am UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889/5 "2007-07-11T06:55:50Z")

</div>

> the error you got is telling you that it can’t build the task that  
> doc:rails is trying to do (it is trying to create rdocs out of a vendor  
> directory, which exists in rails projects … if you create a new rails  
> project and run this command in the RAILS\_ROOT directory, you shouldn’t  
> get an error.
> 
> where are you running the commands from? it seems like these errors are  
> cause by bad paths. you have to run the rake doc:task command from the  
> correct directory for it to work…

I wish that was the problem. Tried it again, got same result:

1. Create a new dummy rails project and cd into its directory:

[~/Documents/Rails] jimgagne% rails example  
create  
create app/controllers  
create app/helpers  
. . . . (etc., etc.)  
create log/development.log  
create log/test.log  
[~/Documents/Rails] jimgagne% cd example

1. Try to run rake doc:rails  
[~/Documents/Rails/example] jimgagne% rake doc:rails  
(in /Users/jimgagne/Documents/Rails/example)  
rake aborted!  
Don’t know how to build task ‘vendor/rails/railties/CHANGELOG’

So I’m NOT in the wrong directory, and there aren’t any weird files  
there screwing things up.

What’s going on??  
—Jim Gagne—

---

<div class="post-metadata">

**Author:** ![Jim\_Gagne](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/dbc845/32.png) [@Jim\_Gagne](https://www.ruby-forum.com/u/Jim_Gagne)\
**Post date:** [July 11, 2007, 9:25am UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889/6 "2007-07-11T09:25:28Z")

</div>

> [~/Documents/Rails/example] jimgagne% rake doc:rails  
> …  
> Don’t know how to build task ‘…rails…CHANGELOG’

the error is basicly saying:  
“i don’t know how to build the task rake doc:rails because when i run  
the “rails” task (rake doc:TASK is the command form) there is something  
wrong with the CHANGELOG file in the vendor/rails directory”  
(when you run the doc:RAILS task, you are basically telling rake (=ruby  
make) to create documents of the ruby code that is “rails”. the code  
itself lies within the RAILS\_ROOT/vendor/rails [in your case this would  
be the example directory].

but you don’t want this (i think). do the EXACT same precedure u’v done  
above, but instead of running rake doc:rails, run rake doc:app

and see what happens. (it may be worth creating a controller or  
something just to get some code into doc:app)

---

<div class="post-metadata">

**Author:** ![Jim\_Gagne](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/dbc845/32.png) [@Jim\_Gagne](https://www.ruby-forum.com/u/Jim_Gagne)\
**Post date:** [July 10, 2007, 4:37am UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889/7 "2007-07-10T04:37:24Z")

</div>

> From a command line run  
> $ gem\_server

Here’s the error I get whenever I run this command:  
jimgagne% gem\_server  
/opt/local/lib/ruby/site\_ruby/1.8/rubygems/custom\_require.rb:27:in  
`gem_original_require': no such file to load -- sources (LoadError) from /opt/local/lib/ruby/site_ruby/1.8/rubygems/ custom_require.rb:27:in`require’  
from /opt/local/lib/ruby/gems/1.8/gems/rubygems-update-0.9.4/  
lib/rubygems/source\_info\_cache.rb:6  
from /opt/local/lib/ruby/site\_ruby/1.8/rubygems/  
custom\_require.rb:32:in `gem_original_require' from /opt/local/lib/ruby/site_ruby/1.8/rubygems/ custom_require.rb:32:in`require’  
from /opt/local/lib/ruby/gems/1.8/gems/rubygems-update-0.9.4/  
lib/rubygems/remote\_installer.rb:12  
from /opt/local/lib/ruby/site\_ruby/1.8/rubygems/  
custom\_require.rb:32:in `gem_original_require' from /opt/local/lib/ruby/site_ruby/1.8/rubygems/ custom_require.rb:32:in`require’  
from /opt/local/lib/ruby/site\_ruby/1.8/rubygems.rb:112:in  
`manage_gems' from /opt/local/lib/ruby/site_ruby/1.8/rubygems/server.rb:2 from /usr/bin/gem_server:3:in`require’  
from /usr/bin/gem\_server:3

Running the rake doc:rails also generates an error:  
jimgagne% rake doc:rails  
(in /Users/jimgagne/Documents/Rails/testproject)  
rake aborted!  
Don’t know how to build task ‘vendor/rails/railties/CHANGELOG’

Any thoughts?  
—Jim Gagne—

---

<div class="post-metadata">

**Author:** ![Jim\_Gagne](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/dbc845/32.png) [@Jim\_Gagne](https://www.ruby-forum.com/u/Jim_Gagne)\
**Post date:** [July 12, 2007, 7:19pm UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889/8 "2007-07-12T19:19:52Z")

</div>

I’ve done some digging around in Rake, and I figured out what’s wrong.  
It’s not a bug, it’s a feature. And I remember reading something about  
it in other posts, which never before made sense.

On my machine, the rake files for rails live in the following  
directory:  
/opt/local/lib/ruby/gems/1.8/gems/rails-1.2.3/lib/tasks/

Its contents are databases.rake, documentation.rake, framework.rake,  
etc. The file we want is databases.rake, under the initial block:  
namespace :doc do

A little ways down is the following code (first few lines):  
desc “Generate documentation for the Rails framework”  
Rake::RDocTask.new(“rails”) { |rdoc|  
rdoc.rdoc\_dir = ‘doc/api’  
rdoc.template = “#{ENV[‘template’]}.rb” if ENV[‘template’]  
rdoc.title = “Rails Framework Documentation”  
rdoc.options \<\< ‘–line-numbers’ \<\< ‘–inline-source’  
rdoc.rdoc\_files.include(‘README’)

The problem is that NONE of my rails projects has a vendor/rails  
directory. Turns out you get this only by running the following rake  
task:  
rake rails:freeze:edge  
(Note: there’s a way to specify which version of rails you want, which  
I don’t entirely understand)

That loads the whole 9.1 MB rails system into vendor/rails. THEN rails  
doc:rails works fine. It creates the doc/api directory (5.8 MB).  
Migrate there with Open File from the browser, open index.html, and  
presto! There’s the Rails API (with the columns of listings along the  
top).

To dump the 9.1 MB vendor/rails directory, run rake rails:unfreeze

SO: we’ve solved how to generate a local copy of the Rails API. Any  
ideas about gem\_server???  
—Jim Gagne—

---

<div class="post-metadata">

**Author:** ![Jim\_Gagne](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/dbc845/32.png) [@Jim\_Gagne](https://www.ruby-forum.com/u/Jim_Gagne)\
**Post date:** [July 26, 2007, 12:46am UTC](https://www.ruby-forum.com/t/how-do-i-find-and-view-all-those-rdoc-files-scattered-on-my/108889/9 "2007-07-26T00:46:08Z")

</div>

> Any ideas about gem\_server???

I solved this persistent bug by uninstalling and reinstalling gem. Now  
gem\_server and rake:freeze:gems work fine.

—Jim Gagne—