I’ve been working hard to improve the Rails API documentation and I’d
like to announce the release of version 2 of Rannotate.My goal is to
emulate (and improve upon) the PHP style online documentation at
www.php.net. I think websites speak louder than words so check out
rannotate in action here:
http://rails.outertrack.com/
Rannotate consists of a custom RDoc generator and a Rails application.
The RDoc generator creates a database out of your files and the rails
application generates the documentation you see on the fly, allowing
for searching, user annotations and many more great things to come.
Read more about it here:
http://rannotate.rubyforge.org
I know there are plenty of bugs. I haven’t been able to try it out on
many platforms. I think most things should be working but please
submit bugs and suggestions using the rubyforge trackers.
http://rubyforge.org/tracker/?group_id=1051
Coming in following versions:
History - show diffs between different versions of the documentation
to see what changed between versions of a class, module, file,
method…
RSS Feeds - rss feeds for notes for all parts of the documentation
Bug Fixes - lots of them (with your help)
Thanks go to Matias Pelenur for his contributions to this release,
many bug fixes and chunks of code for the search.
–
Conor
Great work Conar, truly one area that Rails and Ruby needs improvement
on
for us PHP converts.
One point to mention is I would like to see a convergence of both Rails
and
Ruby (Core and Standard Library) documentation in one site. As someone
still
getting familiar with the library of Rails and the foundation of Ruby, I
find it that sometimes when I search for a method, such as inspect, I am
only to find afterwards that it’s apart of Ruby and not Rails itself.
So,
with that in mind, having a unified documentation system for both, with
indication on whether its Rails or Ruby within the docs would be
excellent.
To be honest though, it really doesn’t matter if it says its Rails or
Ruby,
coming from a Rails perspective as both are available in their entirety
for
Rails developers.
One key point for a usability standpoint would be that of removing the
frames (I am sure you are already on this), and providing the same
method/function per page that PHP has. Whereby, when you click on a
method
it gives you a complete breakdown of that method and usage. This is
espcially important when encouraging user submitted comments for usage
examples as the PHP docs are completely saturated with.
Another point of recommendation is that of the URL search, whereby I can
type PHP: date - Manual and it will bring me up to the date functionality
page
with comments. This has been deployed by MySQL successfully as well,
based
on the user feedback from the community of PHP and I find it personally
extremely useful.
Warmest regards,
Nathan.
Nathaniel S. H. Brown Toll Free 1.877.4.INIMIT
Inimit Innovations Phone 604.724.6624
www.inimit.com Fax 604.444.9942
It would also be nice if you could add notes per method as opposed to
per module.
regards,
Paulie
conor.hunt+rails wrote:
I’ve been working hard to improve the Rails API documentation and I’d
like to announce the release of version 2 of Rannotate.My goal is to
emulate (and improve upon) the PHP style online documentation at
www.php.net. I think websites speak louder than words so check out
rannotate in action here:
http://rails.outertrack.com/
Nice initiative but it seems the website is not accessible. Is it
temporary or has it been moved ?