Forum: Ruby on Rails [ANN] Ruby on Rails Searchable and Annotatable Docs

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Conor H. (Guest)
on 2006-05-16 21:48
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
Paul R. (Guest)
on 2006-05-16 22:46
(Received via mailing list)
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. :-)

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.
Justin B. (Guest)
on 2006-05-16 22:59
(Received via mailing list)
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/.
Justin B. (Guest)
on 2006-05-16 23:02
(Received via mailing list)
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
Conor H. (Guest)
on 2006-05-16 23:20
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.
>
> Justin
Jean-François (Guest)
on 2006-05-16 23:58
(Received via mailing list)
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 :)

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

      -- Jean-François.
Sébastien Gruhier (Guest)
on 2006-05-17 00:04
(Received via mailing list)
Wow this is really kool
great job
Seb

Le 16 mai 06 à 19:48, Conor H. a écrit :
Kevin O. (Guest)
on 2006-05-17 00:57
(Received via mailing list)
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
Michael T. (Guest)
on 2006-05-17 01:29
(Received via mailing list)
This same thing has been on my todo list.  Thanks.  It looks great.

Michael
Ray B. (Guest)
on 2006-05-17 01:33
(Received via mailing list)
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 <tt> 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
Conor H. (Guest)
on 2006-05-17 01:55
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 <tt> 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
Brian B. (Guest)
on 2006-05-17 03:33
(Received via mailing list)
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
Conor H. (Guest)
on 2006-05-17 03:37
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
Dominique Rose-Rosette (Guest)
on 2006-05-17 12:51
(Received via mailing list)
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
<body id="rails_outertrack_com">, 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
Conor H. (Guest)
on 2006-05-17 18:40
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
Brian B. (Guest)
on 2006-05-17 19:06
(Received via mailing list)
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
Guido S. (Guest)
on 2006-05-18 23:27
(Received via mailing list)
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.

5) Moving down the page, I found another URL and was able to check
the project out.
6) 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 ...

I'm running on OS X 10.4.6 ...

Hope this helps!

-- G.
Conor H. (Guest)
on 2006-05-18 23:37
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.
>
> 5) Moving down the page, I found another URL and was able to check
> the project out.
> 6) 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 ...
>
> I'm running on OS X 10.4.6 ...
>
> Hope this helps!
>
> -- G.
Jeroen H. (Guest)
on 2006-05-19 11:57
(Received via mailing list)
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 ;-)

Jeroen
Gregory S. (Guest)
on 2006-05-19 17:08
(Received via mailing list)
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.

} Jeroen
--Greg
Conor H. (Guest)
on 2006-05-19 18:28
> 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.

I'm not a CSS/HTML designer by any measure. I needed a two column layout
where the right column could expand and the left hand column can too.
Wasn't sure how to achieve that. If you (or any other CSS wizard) can
send me a layout that does that, I'll implement it pronto!

cheers.

--
Conor
Gregory S. (Guest)
on 2006-05-19 19:06
(Received via mailing list)
On Fri, May 19, 2006 at 04:28:43PM +0200, Conor H. wrote:
} > 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.
}
} I'm not a CSS/HTML designer by any measure. I needed a two column
layout
} where the right column could expand and the left hand column can too.
} Wasn't sure how to achieve that. If you (or any other CSS wizard) can
} send me a layout that does that, I'll implement it pronto!

I don't want it to sound like I was insulting you, because I certainly
didn't mean to. In your CSS, you have widths, measured in pixels (or
points?), set for these columns, right? I haven't looked at the source
of
the page, actually, so I am making assumptions. Anyway, change those
widths
to be measured in ems. I recommend using the Firefox EditCSS extension
<https://addons.mozilla.org/extensions/moreinfo.php...
to play with it live. Tweak the widths (in ems) to get them to look the
same as they did before. Then change the font size; the column widths
should stay in proportion, but grow with the font.

} cheers.
} Conor
--Greg
Conor H. (Guest)
on 2006-05-19 19:09
> I don't want it to sound like I was insulting you, because I certainly
> didn't mean to. In your CSS, you have widths, measured in pixels (or
> points?), set for these columns, right? I haven't looked at the source
> of
> the page, actually, so I am making assumptions. Anyway, change those
> widths
> to be measured in ems. I recommend using the Firefox EditCSS extension
> <https://addons.mozilla.org/extensions/moreinfo.php...
> to play with it live. Tweak the widths (in ems) to get them to look the
> same as they did before. Then change the font size; the column widths
> should stay in proportion, but grow with the font.

No worries, not insulted. I know where my strengths are, and CSS is not
one of them (yet :) I'll try the the ems width.

--
Conor
This topic is locked and can not be replied to.