Ruby Documentation Redux
Apparently, in my attempt to help eliminate comment spam, I managed to disable comments from users that are not logged in (which, doesn't work too well when I have registration disabled). I received a few responses to my previous post via email, so I thought I would mention them and expand upon my frustrations with Ruby documentation.
Aníbal Rojas emailed me to point out rubymanual.org. This looks like a pretty good site, but seems to still suffer from the shortcoming of only having the core Ruby documentation and not the extensions from Rails or any other gems.
David Felstead emailed me to point out the Ruby RDoc Dashboard widget. This is a handy little widget, but still isn't a solution that I like. One shortcoming I think it has (correct me if I'm wrong) is that it appears to use the RDoc from the internet, and not the local machine. I'll explain more of why this is a problem for me in a minute.
For a while I was using ri from the command line, and one thing I liked about that is that I could easily import documentation by running rdoc --ri /path/to/src/lib. So I ran that on most of the gems I used frequently, including Rails. What I didn't like about ri is that I couldn't easily jump around the documentation. I could look up ri ClassName to find the method in the class that I was looking for, but then to get more info about that method, I had to exit, and type ri ClassName\#method. The other problem is that it would occasionally generate exceptions, especially in cases where a library or class would redefine a method. I never took the time to debug it, but usually deleting the .rdoc directory in my home directory, and re-running rdoc --ri fixed it (yes, the Windows equivalent of a reboot).
Before I switched to TextMate, I used the Ruby Development Tools plugin for Eclipse, and one thing I really liked about that was the built in RI browser. I could search through all the RI docs and easily find the methods I was looking for. This is what I wished the Dashboard widget allowed me to do. The down side is that using ri on the back-end causes the problem with exceptions that I described above, and it was really slow on the Mac (didn't seem to have that problem when I was running Linux though).
So, here's my wish-list for a documentation system in Ruby, in order of importance:
- merge core Ruby docs with installed gems and other libraries—including redefined or added methods, which would probably require some type of environment awareness (not a problem for Rails apps)
- linked cross-references
- searchable
- fast
I am Brandon Keepers, and I work at