Is there a reason why rake doc:rails doesn't use the (to my eyes, nicer) sdoc template used for api.rubyonrails.org?
Happy to throw together a patch if the reasons are purely historical
Fred
+1 from here.
This is interesting. A while ago I was asking exactly the opposite: to replace api.rubyonrails.org by the version generated with "rake doc:rails".
The reason is that it is currently very hard to point someone to some specific bit of the API since it uses frames.
Another disadvantage of using frames is that it is not cache-friendly. I tried o F5/Ctrl+F5/Shift+F5 in my Chrome browser to get the updated version of the Rails api but it didn't updated the frame page.
Only the index itself was updated.
I don't think api.rubyonrails.org should use frames. Now you want to introduce the same problems to the version generated with "rake doc:rails"? Please, don't do that.
Cheers, Rodrigo.
Regardless of the points you personally don’t like about the current API, the Rails documentation should ideally be consistent in those places where it has control.
It is OK that the gem installer uses Darkfish, it is OK that some websites use YARD or their own generators, but doc:rails should match api.rubyonrails.org in my opinion whatever their content is.
It is very likely that for Rails 4 we have a different generator though.
This is interesting. A while ago I was asking exactly the opposite: to replace api.rubyonrails.org by the version generated with "rake doc:rails".
The reason is that it is currently very hard to point someone to some specific bit of the API since it uses frames.
Another disadvantage of using frames is that it is not cache-friendly. I tried o F5/Ctrl+F5/Shift+F5 in my Chrome browser to get the updated version of the Rails api but it didn't updated the frame page.
Only the index itself was updated.
I don't think api.rubyonrails.org should use frames. Now you want to introduce the same problems to the version generated with "rake doc:rails"? Please, don't do that.
Regardless of the points you personally don't like about the current API, the Rails documentation should ideally be consistent in those places where it has control.
It is OK that the gem installer uses Darkfish, it is OK that some websites use YARD or their own generators, but doc:rails should match api.rubyonrails.org in my opinion whatever their content is.
It is very likely that for Rails 4 we have a different generator though.
Any ideas what will be used for R4?
Not sure yet. The goal is to provide better ancestry chains.
What I’d like to do is to compute the ancestry chains first, then run the generator of choice up to the point where it has built its structures, replace/rearrange them with our data, and let it continue. I know that can be done with YARD, and I am also exploring RDoc.
