As I mentioned earlier today, there some ideas to take the API to a next level. I think Ruby on Rails is a fucking awesome software, and it should have a fucking awesome API.
Yehuda is working on a different way to organize content. Rizwan Reza is exploring the idea of supporting user comments, there was also a guy in Baltimore that volunteered to have a look into that.
But there are also other ideas that I think are interesting at least to be investigated, if any of you want to work on any of them that would be totally great!
First of all an axiom:
It is OK that we build our own doc tool ad-hoc for Rails, be creative!
Four existing ideas, they may conflict with each other but we will sort it out if the case arrives:
== User-Centered API
Most of the modularity in the Rails code base is there by design. But an end-user does not really care whether AC::Base has been broken in these many modules. If you go to AC::Base you should have all the public interface right there.
Accomplishing this is difficult with parsing, since there are inherited hooks going on, autoloads, code like
MODULES.each do |mod| include mod end
etc. The wild idea is to go and load recursively all the Rails lib directories (except perhaps for a few exceptions with side-effects). With all Rails libs executed, all hooks executed, etc. introspect in memory, and build meaningful docs. You can delegate docstring extraction to an existing parser.
== Linking Tests to the API
The API should be written in English, but sometimes it would be handy to be able to consult right there the tests for a given method. You know, a block with tests that is hidden by default, akin to the current code block.
Here you need to investigate a way to link tests and methods, and be able to insert them in the API.
== Testing Rails Guides
Rails Guides are really really great, but they need to be maintained. If they had code coverage that would be included with the Rails test suite and people would be aware of content being outdated by a patch. That would help a lot, and hey, having tested documentation isn't an exciting idea by itself? Yehuda, José, and Sam Ruby have done stuff in that line for books (with different approximations). If you'd like to take a stab at this it would be a good idea to have at least a look at their solutions.
== Awesome Theme
This depends heavily on the rest, but anyway it is very important. For the API to be fucking awesome, it has to *look* fucking awesome. The idea here is to have a gorgeous theme, possibly based on the color palette and overall style of Rails Guides, and Rails Contributors for consistency's sake.