PHWinfo - Afficher un message

30/03/2008, 05h08

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/

30/03/2008, 05h08	#5
Ken Bloom Messages: n/a Hébergeur:	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/