RDoc 2.2.0 requirement

Looks like Rails 3 currently depends on RDoc 2.2.0 exactly, even
though the latest version is 2.5.x. Why this specific version?

There are plans for improving the documentation. They range from a
better template, to rethinking the API in some fundamental way.

While these are in the oven we needed to take a decision about what to
use for 3.0, which is imminent, since the current API is generated
with RDoc 1.x and that lacks backslash support and other features the
API is now using.

We generated the API with 2.5 in a testing domain and just weren't
convinced. The site will change, but it will change to something else.

So the choice for this particular iteration has been the most modern
RDoc that does not use Darkfish.

Have you considered SDoc? Imho it's the nicest overall documentation
template so far. The search works incredibly well. You can see it in
action here: http://railsapi.com/doc/rails-v2.3.8/


It's a really nice template. Very clear.

We'll take it into account re the other thread about documentation.

That template gets rid of the methods and file listing. That's an idea
in the background since I think they are mostly useless in practice.
When you process the docs you get a list of things, but that does not
mean they need to end up in the interface.

Indeed, depending on how docs evolve I'd like to experiment with
getting rid of everything and leaving just a search box and the main
area (does anybody do this?). Specially if we get entry points to the
main parts of the framework somehow, so newcomers have some anchors to
start browsing.