How do I find and view all those RDoc files scattered on my hard drive?

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

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

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

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

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

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