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

[Jim Gagne]

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

[Shai Rosenfeld]

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

--
Posted via http://www.ruby-forum.com/.

[Chris Lowis]

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

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

[Shai Rosenfeld]

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

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

[Shai Rosenfeld]

> [~/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)

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

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