From: Rodrigo Almeida <rsalmeidafl@...>
Date: 2008-03-30T06:20:52+09:00
Subject: Improvements to RDoc (ideas for GSoC)

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

My idea is not to force every RDoc generated to look like above, but
improve current RDoc system so that the layout above can be achieved
by simply using a special template. Currently, RDoc templates are Ruby
Modules which define a lot of string constants, containing
placeholders, which results in template construction and readability
being far from ideal. The already suggested idea of changing RDoc to
use ERb templates would be really appropriate here, we could really
use some inspiration from rails and use partials to render the
different elements in the page, and have a main template file that
puts everything together.

For implementing code-unrelated documentation, one idea would be to
define a default folder (let's say, /add_doc), which, if present on
the source code root folder, would be parsed by RDoc and added to the
documentation table of contents. Each file inside this dir should call
a title directive on its first line, to define that page's title. So,
the TOC above could be generated by the following file structure:

/add_doc/intro.rdoc
/add_doc/concepts.rdoc
/add_doc/concepts/acl.rdoc
/add_doc/concepts/privileges.rdoc
(...)

Currently RDoc already can be extended to add support for other forms
of markup (see doc for RDoc::Page), but this could be improved, as to
accept additional markup tags and modifiers in an easy way. Let's say
I used to work with java and wanted to comment a method like in the
example below.

# Method description here
#
# ::params::
#       url: an absolute URL giving the base location of the image
#       name: the location of the image, relative to the url argument
# ::return::
#       the image at specified URL
# ::see::
#       Image
#
def load_image(url, name) #:takes: String, String; #:returns: Image

It should be viable for someone to come up with an RDoc extension that
can generate the JavaDoc-like output from the comments above without
excessive digging into RDoc's source.

Those are my preliminary ideas, any feedback on those would be really
appreciated.