[ANN] Ruby on Rails Searchable and Annotatable Docs


#1

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).

Check it out at - http://rails.outertrack.com

  • What is Rannotate?

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!

The Rubyforge project is at - http://rannotate.rubyforge.org


#2

On 16 May 2006, at 18:48, Conor H. wrote:

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).

Check it out at - http://rails.outertrack.com

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. :slight_smile:

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!

The Rubyforge project is at - http://rannotate.rubyforge.org

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.


Paul R.


#3

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. removed_email_address@domain.invalid
Date: May 16, 2006 10:48 AM
Subject: [Rails] [ANN] Ruby on Rails Searchable and Annotatable Docs
To: removed_email_address@domain.invalid

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).

Check it out at - http://rails.outertrack.com

  • What is Rannotate?

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!

The Rubyforge project is at - http://rannotate.rubyforge.org


Posted via http://www.ruby-forum.com/.


#4

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 :slight_smile:

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.

Justin


#5

Hello Conor,

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 :slight_smile:

Just a small bug link : http://http//rannotate.rubyforge.org
in the Rannonate Project link in the sidebar.

  -- Jean-François.

#6

Wow this is really kool
great job
Seb

Le 16 mai 06 à 19:48, Conor H. a écrit :


#7

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.

Justin


#8

On Tuesday, May 16, 2006, at 7:48 PM, Conor H. wrote:

together to provide user submitted notes for rdoc generated


Rails mailing list
removed_email_address@domain.invalid
http://lists.rubyonrails.org/mailman/listinfo/rails

This might make a spiffy engine.

_Kevin


#9

This same thing has been on my todo list. Thanks. It looks great.

Michael


#10

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.

Thanks.

Ray


#11

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.

Thanks.

Ray


#12

Yes, it is just a stylesheet edit, all the font sizes are set to
relative values. What browser/platform/resolution are you using?

The font is set in the stylesheet as:
FONT: 1em “Lucida Grande”, Helvetica, sans-serif;


Conor

Brian B. wrote:

Cool. May be very useful.

I second the font-size comment though. I can hardly read it in my
browser
without Crtl++ first. Is this just a stylesheet edit?

Brian


#13

Le Mercredi 17 Mai 2006 01:37, Conor H. a écrit :

Yes, it is just a stylesheet edit, all the font sizes are set to
relative values. What browser/platform/resolution are you using?

The font is set in the stylesheet as:
FONT: 1em “Lucida Grande”, Helvetica, sans-serif;

What about adding a site specific id attribute to the body tag,
something like

, so that anyone who so wishes might target the site in his/her browser's user-defined stylesheet ?

e.g :

body#rails_outertrack_com {
font-size: 14px /* Be kind to these li’l eyes of yours, baby */
}

Dominique Rose-Rosette


#14

Cool. May be very useful.

I second the font-size comment though. I can hardly read it in my
browser
without Crtl++ first. Is this just a stylesheet edit?

Brian


#15

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, Windows XP, 1152 x 864, 19" monitor

The file listings and the code are hard for me to read.

Brian


#16

I ran the ruby docs through Rannotate and they are now hosted at:
http://ruby.outertrack.com

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.

Justin


#17

Hi!

I checked out your latest SVN code and had the following problems:-

  1. Permissions for script/* are not executable …

  2. Permissions for public/dispatch.* are not executable either …

  3. The shebang line in your scripts didn’t work for me even though I
    have a ruby sitting at that location (/usr/bin/ruby)

  4. Installation instructions from your site say to

    svn checkout https://matiaspelenur.com/svn/rannotate/branches/no-
    frames rannotate

Well, that’s in the where do I get it section, but the URL doesn’t
exist in your repository.

  1. Moving down the page, I found another URL and was able to check
    the project out.

  2. 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:inload_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:indocument’
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 …

I’m running on OS X 10.4.6 …

Hope this helps!

– G.


#18

Thanks Guido.

I think most of these problems stem from the fact that the URL is wrong
for the SVN checkout, the - should be a _.

svn checkout https://matiaspelenur.com/svn/rannotate/branches/no_frames
rannotate

The version of the code you end up with is a very old version without
the yaml generator.

Can you email me at conor . hunt AT gmail DOT com and we’ll work to fix
the docs?

cheers.


Conor

Guido S. wrote:

Hi!

I checked out your latest SVN code and had the following problems:-

  1. Permissions for script/* are not executable …
  2. Permissions for public/dispatch.* are not executable either …
  3. The shebang line in your scripts didn’t work for me even though I
    have a ruby sitting at that location (/usr/bin/ruby)
  4. Installation instructions from your site say to

svn checkout https://matiaspelenur.com/svn/rannotate/branches/no-
frames rannotate

Well, that’s in the where do I get it section, but the URL doesn’t
exist in your repository.

  1. Moving down the page, I found another URL and was able to check
    the project out.
  2. 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:inload_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:indocument’
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 …

I’m running on OS X 10.4.6 …

Hope this helps!

– G.


#19

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 :wink:

Jeroen


#20

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 :wink:

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.

} Jeroen
–Greg