I recently updated my Rannotate application. The interface has been
completely redone and there are lots of new features. The basic idea is
to create searchable and user annotatable documentation for the Ruby on
Rails API (think php.net).
Rannotate is a Rails application and RDoc YAML generator that work
together to provide user submitted notes for rdoc generated
documentation. It is modeled after the successful online PHP
documentation at www.php.net.
This is not just for the Ruby on Rails API, it can be used to generate
online searchable and annotatable documentation for any Ruby project!
I recently updated my Rannotate application. The interface has been
completely redone and there are lots of new features. The basic
idea is
to create searchable and user annotatable documentation for the
Ruby on
Rails API (think php.net).
Very nice - the PHP and MySQL documentation is, in my opinion, much
better than the Rails (or even Ruby) documentation because the
annotations people leave on php.net and mysql.com are often more
valuable than the original documentation. If developers then remember
to fold user suggestions into the core docs, you end up with
something much better, more readable and more useable. It’s like a
wiki but it makes sense.
If anybody looking after http://api.rubyonrails.org is reading this,
you really want to consider switching away from default rdoc output
to this Rannotate output: it’ll put things on track in a big way and
cut down n00b mailing list traffic within weeks.
I was actually going to do something very similar to this myself this
weekend to get myself more familiar with rdoc, so you just gave me
the weekend off, thanks!
This is not just for the Ruby on Rails API, it can be used to generate
online searchable and annotatable documentation for any Ruby project!
That’s great too - I’ll spend some time this weekend looking how to
customise the template for my own projects so the look and feel fits
the rest of my site(s) and start whacking stuff out there. Great
stuff Conor, thanks a lot.
I don’t mean to spam, but this project is really first rate. The Rails
documentation at api.rubyonrails.org could really benefit from this kind
of
system.
---------- Forwarded message ----------
From: Conor H. [email protected]
Date: May 16, 2006 10:48 AM
Subject: [Rails] [ANN] Ruby on Rails Searchable and Annotatable Docs
To: [email protected]
I recently updated my Rannotate application. The interface has been
completely redone and there are lots of new features. The basic idea is
to create searchable and user annotatable documentation for the Ruby on
Rails API (think php.net).
Rannotate is a Rails application and RDoc YAML generator that work
together to provide user submitted notes for rdoc generated
documentation. It is modeled after the successful online PHP
documentation at www.php.net.
This is not just for the Ruby on Rails API, it can be used to generate
online searchable and annotatable documentation for any Ruby project!
Thanks! I actually did run the Ruby API docs through this and was
hosting them at http://ruby.outertrack.com . I need to do it again, I
just haven’t had time during this release. I’ll see if I can do it
today.
I emailed DHH yesterday to see if he would be interested in using this
for api.rubyonrails.org. I think it needs some testing first, so
everyone feel free to test it and send me bug reports
PS: If anyone noticed a bug where you can’t submit notes for child
classes and modules, well, it should be fixed now.
–
Conor
Justin B. wrote:
Impressive work. Have you considered putting the Ruby API docs through
this? The maintainers of http://www.ruby-doc.org might be interested in
using this project too. It’s much nicer looking than their “API wiki”
which
no one ever seems to use.
I emailed DHH yesterday to see if he would be interested in using this
for api.rubyonrails.org. I think it needs some testing first, so
everyone feel free to test it and send me bug reports
Impressive work. Have you considered putting the Ruby API docs through
this? The maintainers of http://www.ruby-doc.org might be interested in
using this project too. It’s much nicer looking than their “API wiki”
which
no one ever seems to use.
together to provide user submitted notes for rdoc generated
documentation. It is modeled after the successful online PHP
documentation at www.php.net.
This is greatly needed and a nice job to boot.
The thing that I like best is you can increase the font size and the
code in format scales correctly. At api.rubyonrails.com I have to
trade off visibility for legibility.
Now we can all start annotating.
Feature request: On the Methods page, http://rails.outertrack.com/list/methods, could you add a list of
anchors at the top of the page so you could go directly to the section
that corresponds to the first letter. Something like this:
Methods: A B C D E F G H … Z
so that if I want to look at has_many, I can click on the “H” and get
pretty close. You might need to put each letter in it’s own row of the
table to get that to work correctly. That might also be a good thing.
Great idea. I added the alphabet navigation and you should be able to
see it now. I kept the 2 column table for now though, I’ll experiment
with making it one column.
And yes, everyone should add lots of annotations while you are browsing
around the site. The only way it will be useful is if everyone tries to
annotate as much as they can.
–
Conor
Ray B. wrote:
Conor H. wrote:
together to provide user submitted notes for rdoc generated
documentation. It is modeled after the successful online PHP
documentation at www.php.net.
This is greatly needed and a nice job to boot.
The thing that I like best is you can increase the font size and the
code in format scales correctly. At api.rubyonrails.com I have to
trade off visibility for legibility.
Now we can all start annotating.
Feature request: On the Methods page, http://rails.outertrack.com/list/methods, could you add a list of
anchors at the top of the page so you could go directly to the section
that corresponds to the first letter. Something like this:
Methods: A B C D E F G H … Z
so that if I want to look at has_many, I can click on the “H” and get
pretty close. You might need to put each letter in it’s own row of the
table to get that to work correctly. That might also be a good thing.
The server has unfortunately been down for a little while because of
hosting issues, but it is back up now and I hope it stays that way!
–
Conor
Justin B. wrote:
Impressive work. Have you considered putting the Ruby API docs through
this? The maintainers of http://www.ruby-doc.org might be interested in
using this project too. It’s much nicer looking than their “API wiki”
which
no one ever seems to use.
Well, that’s in the where do I get it section, but the URL doesn’t
exist in your repository.
Moving down the page, I found another URL and was able to check
the project out.
In step 1 of your installation instructions,
Step 1:
Put the yaml_generator.rb file from the rdoc_extension directory
into your rdoc generator directory which is: [RUBY_DIR]\lib\ruby\1.8
\rdoc\generators\
There is no yaml_generator.rb in the rdoc_extension directory.
Instead there is a db_generator.rb …
insight:~/Projects/third-party/rannotate $ ls rdoc_extension/
db_generator.rb templates
I assume that you are now generating inserts to the database
directly? So no YAML generator is required any longer? If so …
I tried copying the files in there to my RUBY_HOME/1.8/rdoc folder
and executing rdoc as you mentioned …
read': No such file or directory - /opt/local/lib/ruby/1.8/rdoc/ generators/template/db/db (Errno::ENOENT) from /opt/local/lib/ruby/1.8/rdoc/generators/ db_generator.rb:174:in load_template’
from /opt/local/lib/ruby/1.8/rdoc/generators/
db_generator.rb:53:in generate' from /opt/local/lib/ruby/1.8/rdoc/rdoc.rb:263:in document’
from /opt/local/bin/rdoc:63
I looked into your rdoc_extension/templates folder and gave up when I
saw a .rhtml file since I realized that the file in RUBY_HOME/1.8/
rdoc/generators/template/* were all .rb and not .rhtml file, moreover
the backtrace is looking for db/db …
Well, that’s in the where do I get it section, but the URL doesn’t
exist in your repository.
Moving down the page, I found another URL and was able to check
the project out.
In step 1 of your installation instructions,
Step 1:
Put the yaml_generator.rb file from the rdoc_extension directory
into your rdoc generator directory which is: [RUBY_DIR]\lib\ruby\1.8
\rdoc\generators\
There is no yaml_generator.rb in the rdoc_extension directory.
Instead there is a db_generator.rb …
insight:~/Projects/third-party/rannotate $ ls rdoc_extension/
db_generator.rb templates
I assume that you are now generating inserts to the database
directly? So no YAML generator is required any longer? If so …
I tried copying the files in there to my RUBY_HOME/1.8/rdoc folder
and executing rdoc as you mentioned …
rdoc --fmt=yaml --opname=appname-0.2.3 directory
It didn’t recognize the yaml generator. I tried
rdoc --fmt=db --opname=appname-0.2.3 directory
and got
Generating DB…
/opt/local/lib/ruby/1.8/rdoc/generators/db_generator.rb:174:in read': No such file or directory - /opt/local/lib/ruby/1.8/rdoc/ generators/template/db/db (Errno::ENOENT) from /opt/local/lib/ruby/1.8/rdoc/generators/ db_generator.rb:174:in load_template’
from /opt/local/lib/ruby/1.8/rdoc/generators/
db_generator.rb:53:in generate' from /opt/local/lib/ruby/1.8/rdoc/rdoc.rb:263:in document’
from /opt/local/bin/rdoc:63
I looked into your rdoc_extension/templates folder and gave up when I
saw a .rhtml file since I realized that the file in RUBY_HOME/1.8/
rdoc/generators/template/* were all .rb and not .rhtml file, moreover
the backtrace is looking for db/db …
Yes, it is just a stylesheet edit, all the font sizes are set to
relative values. What browser/platform/resolution are you using?
Firefox 1.5.0.3 http://1.5.0.3, Windows XP, 1152 x 864, 19" monitor
The file listings and the code are hard for me to read.
Same here. That’s normally not a huge problem, but it doesn’t scale
nicely with ctrl + beccause the menu on the left expands beyond its
container and over the content. http://rails.outertrack.com/module/ActiveRecord is a good example of
this. Oh if we could only still use tables for layout
On Fri, May 19, 2006 at 09:54:33AM +0200, Jeroen H. wrote:
} Brian B. wrote:
} >Yes, it is just a stylesheet edit, all the font sizes are set to
} >
} > relative values. What browser/platform/resolution are you using?
} >
} >
} >Firefox 1.5.0.3 http://1.5.0.3, Windows XP, 1152 x 864, 19"
monitor
} >
} >The file listings and the code are hard for me to read.
}
} Same here. That’s normally not a huge problem, but it doesn’t scale
} nicely with ctrl + beccause the menu on the left expands beyond its
} container and over the content.
} http://rails.outertrack.com/module/ActiveRecord is a good example of
} this. Oh if we could only still use tables for layout
This is a common CSS mistake. Text-containing regions should either have
a
width of auto, should have a width measured in exes or ems, or (in rare
cases) have overflow-x set to scroll. Measuring widths in pixels or
points
or inches or any other unit not related to the font size is just asking
for
trouble. Sadly, it is the common case.
