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…
Adding the Ruby core library should be simple I believe. It has RDoc
documentation available and as soon as I figure out how to generate
that rdoc I will add it to my site. Anyone know what packages RDoc
needs to be pointed at?
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.
I like the single frame myself, but I’ll put a button in there to have
a frame/no frame switch for you 
Each method has it’s own [notes]
link now. So I was thinking that would be good enough. Not only that,
but every section of a class/file/module has it’s own notes.
Another point of recommendation is that of the URL search, whereby I can
type www.php.net/date and it will bring me up to the date functionality page
with comments.
The search functionality you are asking for exists in two ways:
http://rails.outertrack.com/doc/link/classes/ActionController::Base
will bring you directly to the ActionController::Base class, or,
http://rails.outertrack.com/doc/search/ActionController::Base will
search for it.
I take your suggestion though and this will be improved using routes
(it’s a one line code change) so that it is even simpler:
http://rails.outertrack.com/ActionController::Base will bring you
directly to the page for that class if there is only one match for the
search, otherwise it will show you the search results.
Thanks for the feedback Nathan!
–
Conor
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…
Adding the Ruby core library should be simple I believe. It
has RDoc documentation available and as soon as I figure out
how to generate that RDoc I will add it to my site. Anyone
know what packages RDoc needs to be pointed at?
Here is a list of the two URL’s, not sure where RDoc would need to be
pointed at though:
http://www.ruby-doc.org/core/
http://www.ruby-doc.org/stdlib/
One of the primary reasons I have for having a specific page for each of
the
methods is that when people see an empty comment box, thy are almost
possessed to put something in it So having a whole bunch of empty
comment
boxes below the method description with source code example would
encourage
more comments.
will search for it.
I take your suggestion though and this will be improved using
routes (it’s a one line code change) so that it is even simpler:
http://rails.outertrack.com/ActionController::Base will bring
you directly to the page for that class if there is only one
match for the search, otherwise it will show you the search results.
This would work, but even simpler would be
http://rails.outertrack.com/actioncontroller and it me a list of all the
sub
modules below it, and if I went for something like
http://rails.outertrack.com/actioncontroller_base it would understand
that
the _ is a logical separator for the sub-module.
Not sure about this is, but I don’t think the :'s themselves
untranslated
are URI compliant based on the spec, so abstracting them out would be
better
for search engines and such who will likely be eager to index the
comments.
Another thing that gets me is the overview pages, how the method list is
horizontal instead of vertical like the PHP docs. I find it very
difficult
to read through the RDoc’s method lists as they are only space
separated.
Having an overview page of the entire modules methods in vertical list
form
would be most useful as far as readability goes.
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
This URL contains the core libraries API for 1.8.3 in
rannotate format.
http://ruby.outertrack.com/
I generated it by running rdoc in the ruby directory. There
were .documentation RDoc files already there, I modified them
a bit so that more extensive documentation is generated.
This is excellent. I was more referring to have a
rubyandrails.outertrack.com that combines both ruby.outertrack.com and
rails.outertrack.com into one single resource so I don’t need to switch
between the two.
the submodules right now, and going to
by doing the translation themselves. Do search engines do the
same thing?
I am not an expert at the internals of search engines, but when I look
at
the URL:
http://rails.outertrack.com/doc/modules/ActionController%3A%3ACaching%3A%3AF
ragments
http://api.rubyonrails.com/classes/ActionController/Caching/Fragments.html
The second is a lot more likely to be index more effectively by search
engines as it doesn’t contain any special characters. As you probably
know,
XSS uses such tactics as encoding the tag into the URL for
variables to parse and insert into the page, where people can grab the
cookies from unsuspecting users. So based on that, I would have to go
with
the fact that without it, would be much better.
Removing the frames will also greatly increase the search engine
optimization. In addition to using a .html extension (even if its
dynamic)
as search engines prefer to index static pages.
Another thing that gets me is the overview pages, how the
method list
is horizontal instead of vertical like the PHP docs. I find it very
difficult to read through the RDoc’s method lists as they
are only space separated.
Having an overview page of the entire modules methods in
vertical list
form would be most useful as far as readability goes.
Can you show me an example of this?
The guys working on RDoc must have known I didn’t like it horizontal
list
The latest version is fixed now and has a vertical list style. Just
checked
it not even two days ago and it was horizontal, so this is a mute point
now.
Also, any word on getting this into the api.rubyonrails.com ? Have a
hard
time remembering your outertrack.com domain 
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
I like the other ideas, but I would suggest not combining rails and
ruby into one huge annotated API–Or at least make it very clear what
the dividing line between the two areas is, perhaps with a different
background color or something. I think it’s important for people who
are new to know what functionality is rails-specific and what is
general to all ruby.
Carl
Thanks Leon, I’ve sent an email to David Hansson, so we’ll see what he
has to say.
I need lots of bug testing on different platforms, so if you have some
time please add notes, browse around, try the search and see what bugs
you can find.
Thanks.
–
Conor
Hey Conor,
When you get the no-frames version up, I will take a peek and come up
with a
cool interface for the doc system. Be happy to help make it look a
little
more appealing and user friendly
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
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.
I like the single frame myself, but I’ll put a button in there to have
a frame/no frame switch for you 
Each method has it’s own [notes]
link now. So I was thinking that would be good enough. Not only that,
but every section of a class/file/module has it’s own notes.
Just like the other posters, I like your annotated documentation system
a lot. As a point of feedback, navigation could use a little more care.
Maybe tinkering with the CSS would make the pages look and feel less
rough (e.g. heading font sizes appear too big, to my eye at least).
Php’s documentaton site could act as a role model here. The search
facility will be the most-used function of the site, so that needs extra
attention - it’s quite nice already though.
Please consider also: Having a framed version, even conditionally, will
result in isolated content frames (without the corresponding menu)
ending up in google. Even though frames make some thing easier, they’re
mostly harmful.
Thanks!
Paulus
This URL contains the core libraries API for 1.8.3 in rannotate format.
http://ruby.outertrack.com/
I generated it by running rdoc in the ruby directory. There were
.documentation RDoc files already there, I modified them a bit so that
more extensive documentation is generated.
This would work, but even simpler would be
http://rails.outertrack.com/actioncontroller and it me a list of all the sub
modules below it, and if I went for something like
http://rails.outertrack.com/actioncontroller_base it would understand that
the _ is a logical separator for the sub-module.
I’ll have a look at this. I might just stick with the way I have
because searching for actioncontroller will return all the submodules
right now, and going to /actioncontroller::base will work too (it
might not be URI compliant but the browsers translate it fine.)
Not sure about this is, but I don’t think the :'s themselves untranslated
are URI compliant based on the spec, so abstracting them out would be better
for search engines and such who will likely be eager to index the comments.
No idea how search engines handle it. Browsers handle it fine by doing
the translation themselves. Do search engines do the same thing?
Another thing that gets me is the overview pages, how the method list is
horizontal instead of vertical like the PHP docs. I find it very difficult
to read through the RDoc’s method lists as they are only space separated.
Having an overview page of the entire modules methods in vertical list form
would be most useful as far as readability goes.
Can you show me an example of this?
–
Conor
Regarding the autocomplete feature. Makes sense, but I’m wondering if
there
is a way to “cache” the list of classes/methods/filenames locally with
javascript and have the autocomplete query that instead of hitting the
db.
I’m pretty sure its doable, just not sure if its worth the trouble of
coding
it up
To make a DIV scrollable, all you gotta do is give it a fixed height and
then set overflow: auto; for example:
.. long list ..
The only caveat to this approach is you have to set the heigt of the DIV
manually. A work around would be to determine the height of the browser
window (using javascript) and dynamically set the height of the DIV to
correspond to that calculated height. This way the DIV will always be
the
same height as the browser window. OR just use frames 
I’m not familiar with scrollable DIVs, but I’ll have a look. I used a
frame because I didn’t want to load all that data multiple times, a
non framed version would have to have some type of collapsed hierarchy
at the side.
All the information is stored in a database, but we didn’t want to
make the search field auto-complete because we were worried about the
number of database queries it would generate.
–
Conor
I agree. I think this is a great tool. I do agree that it would be
cool to offer a non-frames version as well, but all in good time.
Thanks for all your efforts with this Conor. It is very useful. The
search feature is really cool and quite snappy.
1 (one) vote from me for it to replace http://api.rubyonrails.org/ when
tested as stable…
Probably you are using it under a platform that I have not tested yet.
Unfortunately I’m not a designer (at all). I’ll do the best I can in
the next release to make the CSS look similar under different
platforms though.
If anyone out there is a designer and has some CSS skills it would be
great if you had a few hours and could take a look at the site and
improve the CSS.
Isolated content frames are a problem, although there can easily be a
link to show the index frame if it is missing. I’m not sure if it is a
good idea to display the huge list of files, classes or methods for
each page. I think without frames I’d probably only show
classes/modules in a collapsable hierarchy and allow you to search the
other types.
–
Conor
A nice alternative to frames would be to use a scrollable DIV. The
problem
with that and the main reason I think frames were used is because that
long
list has to be reloaded on every page request, making the page size much
larger than it needs to be. I don’t mind the frames, as long as each
individual page can still be indexed and searched by google easily. If a
user happens to come upon the page outside of frames, the page could
detect
this and refresh the page inside frames again. I think this is what the
MSDN
site does.
Just curious, is all that information stored in a database somewhere? If
so,
why not make the search fields into an auto-complete text field using
the
javascript helpers in rails. I think its a one liner.
Great resource nonetheless… I use this as a replacement to the regular
Rails/Ruby API sites now.
I’m not familiar with scrollable DIVs, but I’ll have a look, thanks. I
used a
frame because I didn’t want to load all that data multiple times, a
non framed version would have to have some type of collapsed hierarchy
at the side.
All the information is stored in a database, but we didn’t want to
make the search field auto-complete because we were worried about the
number of database queries it would generate.
–
Conor
On 11/18/05, Conor H. [email protected] wrote:
All the information is stored in a database, but we didn’t want to
make the search field auto-complete because we were worried about the
number of database queries it would generate.
That would be a real issue on a site that got a lot of traffic, which
undoubtedly this will, given its usefulness. I think the search is
great as is. Autocomplete IMO would mostly be a gee-whiz feature.
All,
I installed the latest version Rails in order to get the updates for the
SQL Server adaptor. Here is the log of the update:
Successfully installed rails-0.14.3.2969
Successfully installed activesupport-1.2.3.2969
Successfully installed activerecord-1.13.0.2969
Successfully installed actionpack-1.11.0.2969
Successfully installed actionmailer-1.1.3.2969
Successfully installed actionwebservice-0.9.3.2969
Installing RDoc documentation for activesupport-1.2.3.2969…
Installing RDoc documentation for activerecord-1.13.0.2969…
lib/active_record.rb:73:64: Skipping require of dynamic string:
“active_record/c
onnection_adapters/#{adapter}_adapter”
Installing RDoc documentation for actionpack-1.11.0.2969…
lib/action_controller/assertions.rb:4:69: Skipping require of dynamic
string: “#
{File.dirname(FILE)}/vendor/html-scanner/html/document”
Installing RDoc documentation for actionmailer-1.1.3.2969…
Installing RDoc documentation for actionwebservice-0.9.3.2969…
Gems: [rails] updated
When I ran it against my one table named interior_selections that has a
primary key of selection_id [below is the source for it]
class InteriorSelection < ActiveRecord::Base
set_table_name “interior_selections”
set_primary_key “selection_id”
end
Here is the error message I get:
Execute
OLE error code:80040E14 in Microsoft OLE DB Provider for SQL Server
Incorrect syntax near the keyword ‘TOP’.
HRESULT error code:0x80020009
Exception occurred.
C:/ruby/lib/ruby/site_ruby/1.8/DBD/ADO/ADO.rb:135:in execute' C:/ruby/lib/ruby/site_ruby/1.8/dbi/dbi.rb:1049:inexecute’
C:/ruby/lib/ruby/site_ruby/1.8/dbi/dbi.rb:640:in execute' C:/ruby/lib/ruby/site_ruby/1.8/dbi/dbi.rb:671:inselect_all’
C:/ruby/lib/ruby/gems/1.8/gems/activerecord-1.13.0.2969/lib/active_record/connection_adapters/sqlserver_adapter.rb:322:in
add_limit_offset!' C:/ruby/lib/ruby/gems/1.8/gems/activerecord-1.13.0.2969/lib/active_record/base.rb:937:inadd_limit!’
C:/ruby/lib/ruby/gems/1.8/gems/activerecord-1.13.0.2969/lib/active_record/base.rb:930:in
construct_finder_sql' C:/ruby/lib/ruby/gems/1.8/gems/activerecord-1.13.0.2969/lib/active_record/base.rb:411:infind’
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/pagination.rb:174:in
find_collection_for_pagination' C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/pagination.rb:192:inpaginator_and_collection_for’
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/pagination.rb:124:in
paginate' #{RAILS_ROOT}/app/controllers/interior_selection_controller.rb:11:inlist’
#{RAILS_ROOT}/app/controllers/interior_selection_controller.rb:3:in
index' C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/base.rb:845:insend’
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/base.rb:845:in
perform_action_without_filters' C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/filters.rb:332:inperform_action_without_benchmark’
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/benchmarking.rb:69:in
perform_action_without_rescue' C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/benchmarking.rb:69:inmeasure’
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/benchmarking.rb:69:in
perform_action_without_rescue' C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/rescue.rb:82:inperform_action’
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/base.rb:369:in
send' C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/base.rb:369:inprocess_without_session_management_support’
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/session_management.rb:116:in
process' C:/ruby/lib/ruby/gems/1.8/gems/rails-0.14.3.2969/lib/dispatcher.rb:38:indispatch’
C:/ruby/lib/ruby/gems/1.8/gems/rails-0.14.3.2969/lib/webrick_server.rb:121:in
handle_dispatch' C:/ruby/lib/ruby/gems/1.8/gems/rails-0.14.3.2969/lib/webrick_server.rb:87:inservice’
C:/ruby/lib/ruby/1.8/webrick/httpserver.rb:104:in service' C:/ruby/lib/ruby/1.8/webrick/httpserver.rb:65:inrun’
C:/ruby/lib/ruby/1.8/webrick/server.rb:155:in start_thread' C:/ruby/lib/ruby/1.8/webrick/server.rb:144:instart’
C:/ruby/lib/ruby/1.8/webrick/server.rb:144:in start_thread' C:/ruby/lib/ruby/1.8/webrick/server.rb:94:instart’
C:/ruby/lib/ruby/1.8/webrick/server.rb:89:in each' C:/ruby/lib/ruby/1.8/webrick/server.rb:89:instart’
C:/ruby/lib/ruby/1.8/webrick/server.rb:79:in start' C:/ruby/lib/ruby/1.8/webrick/server.rb:79:instart’
C:/ruby/lib/ruby/gems/1.8/gems/rails-0.14.3.2969/lib/webrick_server.rb:73:in
`dispatch’
Thanks in advance,
Ron