The Ruby on Rails API Switches to SDoc
Posted by fxn August 29, 2011 @ 02:29 PM
The Ruby on Rails API is switching to SDoc starting with 3.1.
SDoc is a RDoc format created by Володя Колесников (@voloko) that has been powering railsapi.com for a long time.
Among other things, SDoc provides a search box with fuzzy match completion, tree browsing, keyboard navigation, and a really nice template.
You can already see the upgrade in the edge API.
We'd like to thank very much Володя for his work updating SDoc for the official API. Thanks man!
And how exactly do you pronounce Володя ?
It’s funny you did not transliterate his name – Volodya (Vladimir) Kolesnikov.
Володя – красавчег! Так держать!
He does not transliterate in his own GitHub account, doing so here would be a liberty I am not going to take.
Any chance of getting user-commenting added too please? That’s about the only thing I miss from php.net (mostly for the example usages that people post in them).
@AstonJ unlikely.
“Володя Колесников” is not developer, it’s name of the new Russian nuclear bomb
I am using SDoc for a long time and this formal move to it is some good news. However I find it quite difficult to read stuff on customized edge API theme: http://cl.ly/9gSp Apparently it needs some CSS tweaking to make it more readable.
It looks good on my laptop, But is somewhat clunky on android.
(not that I frequently check the rails api on my tablet, but in terms of having a future proof solution…)
Nice addition. I have been using railsapi exclusively for some time. It’s way easier to read than RDoc and friendlier for new devs coming to Rails.
I agree with @AstonJ; comments would be a nice addition.
@medwezys @MatthewRudy please do not hesitate to suggest CSS tweaks to the rails template. Some details are indeed being polished.
Cool, looks much nicer and friendlier!!
This deserves a link to a video of a Russian nuclear icebreaker: http://www.youtube.com/watch?v=VVtDX46cTJQ
+1 on comments.
Rather than comments, perhaps it would be possible to link directly through to the ‘edit’ page for docrails on github? That could be nice for when people want to quickly correct a typo or something.
This is cool!!! :) awesome
@Xavier – do you know why comments are unlikely? Could you use Disqus or similar if it’s a technical/time issue?
@AstonJ not totally against it, but Rails releases are frequent, and don’t like the idea of migrating comments from release to release. They would have such a short live that I don’t think it is worth the trouble.
Also, I think comments are a X solution to an Y problem. If something can be explained better, expanded… whatever, that should generally go as a patch through docrails. That workflow works well with upgrades.
Cool! I hope this will give more attention to SDoc itself.
I applaude this!
@Xavier – I see your point – it could get messy.
An alternative could be an official Ruby on Rails forum, where a topic could be posted for each API entry (and linked to), or it could just be used to discuss things.
We don’t really have any active Rails forums – which is a shame as they are very useful and fantastic for forging communities.
(I’ve been running forums for years so could help here.)
Awsome – I’ve been using railsapi.com for the reason of that SDoc is so swift and easy to overview. I’ll probably still use railsapi.com as it allows searching Ruby, Rack and many customs gems, but yet happy core docs picked SDoc!
Why not YARD? YARD also parses RDoc, provides a Search Box, Class/Module tree view, method listing, a nice default template, and allows for custom templates. YARD also allows for Doxygen/JavaDoc style annotation tags.
http://rubydoc.info/gems/activesupport/frames Why not YARD?
The SDoc theme on edge really clashes with my API browsing MO. Instead of knowing what method I want and quickly being able to scroll there with the mouse I now either have to know in which class the method currently resides, or start using the search box and then having to remember to clear it when I want to go looking for something else. Lots more work for a little eye candy. :(
Whats the RDoc theme of the current api.rubyonrails.org called? I look into rolling my own then :)
Been using RailsAPI for awhile offline and like it a lot – this is great news.
I’ve often opened sections of the API documentation in new tabbed windows. This doesn’t seem to work with the new generated doc here: http://edgeapi.rubyonrails.org/
This is an improvement, but I also have to wonder why YARD wasn’t chosen. It looks great and is being used for http://rubydoc.info/.
Володя, респект и уважуха ;)
Володя, молодец!:)
@srd The current API uses the Horo template, which is extracted as a gem. Check the Rakefile at the root of the project to see how to use it.
@postmodern @Jimmy YARD is in the radar, not discarded.
But it would be another kind of switch. Among other things in particular the core team should commit to use annotations. Technically not required, but that’d be the point. If we ever want annotations, that’d be a logical change, while that’s not the case, YARD is still a valid option but less justified in my opinion.
SDoc on the other hand has a set of useful features and a really nice design for my taste. Definitely, SDoc is an excellent choice to upgrade the Horo template, and was for me the most natural next step in the evolution of the API.
See also the rubyonrails-docs ML for some discussion about this.
But as I said, it is not discarded. It could (or could not) happen that YARD is adopted in the future. Time will say.
My impression is that frames are not compliant with HTML 5 and their use has been generally discouraged for quite some time now. My question is why do all these doc templates still use framesets?
Since we’re talking about documentation for cutting-edge web technologies here, shouldn’t they be expected to follow the best practices vigorously when it comes to frontend design?
Let me know if I’m missing something.
According to http://www.w3schools.com/html5/tag_iframe.asp frames are still there. Frames are ok if they used for the right purpose, like in this documentation or youtube/vimeo videos, not like in old web’s.
Linking to w3schools does not help:
http://w3fools.com/
Anyway, I know that frames are still supported in HTML 4, what I’m saying is that the markup used in official resources like these should not be “okay”, but should reflect the absolute pinnacle of current web technology. I don’t see how frames fit into that.
By the way, there’s a difference between iFrames (still supported in HTML 5) and framesets (not supported at all in HTML 5).
@M.S. Absolutely, HTML5 would be awesome for the API. We are not using something else because we choose to, but because nobody, not even you, wrote an HTML5 template like that. You can change that if you feel so strong about it.
Thanks for clarifying, I just wanted to check that people are aware of it. I may work on it if when I have some time.
The problem of how to handle comments in documentation seems to be solved nicely at http://apidock.com
THANKS A LOT guys! I’ve been using SDoc for a while and now I’m addicted to it… =P
Nice except you can’t scroll the sidebar on an iPad…
Nice except you can’t scroll the sidebar on an iPad…
Nice…except that unlike railsapi.com, I can’t view the Rails and Ruby standard library APIs in one big list. That’s a big disadvantage.
Victor, you can scroll the sidebar on an iPad, but you need to scroll using two fingers instead of one.
Got your point here, wait for the next updates.