From: Ken Bloom <kbloom@...>
Date: 2008-03-30T12:10:08+09:00
Subject: Re: Improvements to RDoc (ideas for GSoC)

On Sat, 29 Mar 2008 16:20:52 -0500, Rodrigo Almeida wrote:

> I'm a brazilian student wishing to participate in Google Summer of Code
> this year, and work on something related to RDoc. Before I finish my
> proposal, I'd like some community feedback on the ideas below
> 
> First of all, I think documentation of any Ruby library can be split in
> two different sections: Reference, which is documenting every class and
> method on the library, in a way that's easy for one to access
> information on a specific feature, and a more general documentation,
> which is not bounded to any Ruby code directly. This part of
> documentation would include an overview of the library, tutorials and
> stuff like that. More "common" libs, like a String library, probably
> don't really need the second part, but as I was designing a ACL plugin
> for a Rails project I'm participating, I found that having a separate
> section of the documentation for explaining how ACL works, system
> concepts and some additional tutorials would be a nice add. RDoc sort of
> currently supports through files without extension like README or
> CHANGELOG, but that makes this documentation accessible only though the
> Files menu.
> 
> This leads to another important aspect. I think that RDoc shouldn't
> include that Files menu, it should be structured more like a Table of
> Contents. So, for me, the best layout would be having a left navigation
> menu, and my ACL plugin documentation menu could look something like
> that:
> 
>> Introduction
>> System Concepts
>        > What is an ACL?
>        > Privileges
>        > Selectors
>> Tutorials
>        >...
>> Reference
>        > [Object Browser-like structure]
> 
> This kind of layout is already implemented by Noobkit. See:
> http://www.noobkit.com/show/ruby/ruby.html

Perhaps you could look at my rdoc wishlist at http://
blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/295589 and consider 
something along those lines -- separate the backend from the frontend, 
and integrate rubygems into the system.

--Ken

-- 
Ken (Chanoch) Bloom. PhD candidate. Linguistic Cognition Laboratory.
Department of Computer Science. Illinois Institute of Technology.
http://www.iit.edu/~kbloom1/