[Pkg-ruby-extras-maintainers] Documentation generation

[Paul van Tilburg]

On Fri, Dec 09, 2005 at 08:35:38PM +0000, Esteban Manchado Velázquez wrote:
>     Now that we have some beginning of a naming convention, I would like to
> solve the documentation generation issue.
> 
>     I've looked at Lucas' package, and he simply uses "rake doc". Yesterday,
> hacking around with the CDBS class, I added documentation package support, and
> I also implemented it with a rake call.
> 
>     But, I don't think generating documentation from the CDBS class, via rake,
> is a good idea, because:
> 
> 1) We're then relying on upstream having a Rakefile with a special task to
> generate the documentation we want.

Agreed.  I've seen documentation being build in dozens of ways already.

> 2) We will be using, then, upstream documentation generation options, instead
> of the ones we decide to use.
> 
> So, after a little thought, I think we should better call rdoc directly, with
> the options we decide (I think Lucas had a proposal in some thread). The
> options, of course, will be overridable via make variables or something
> similar.

Yes, well, we could use a wrapper.  I wrote something about that on the
Wiki already:
http://pkg-ruby-extras.alioth.debian.org/cgi-bin/wiki/index.cgi?DocumentationGeneration
Anyway, it's still kinda calling rdoc directly.  My original version of the
CDBS class supported generating or installing RI (to the site RI 1.8 dir)
and HTML (to /usr/share/doc/<pkg>/rdoc/ for consistency) and that seemed
to work well.

>     Another problem is that I don't know in what directories RI searchs for
> the documentation. Anyone knows? At least for Ruby core documentation, it's
> put in version-dependent directories. If we can't use a version-independent
> one, I think we can just generate RI only for the default version, what do you
> think?

That should be enough. If not, we could always patch RI :)

>     And finally, how is the user supposed to access rdoc documentation?
> Opening /usr/share/doc/libfoo-ruby-doc/rdoc/index.html in a web browser? Are
> we going to somehow register rdoc documentation in dhelp/doc-base? I think we
> should...

That might be a good idea.  I've been pondering creating a rubydoc[1]
tool ala texdoc/perldoc, but in Ruby it's a mess...  documentation
coming with debs, tars, gems, it's ALL over the place and no consistent
way of locating it.  That said, it doesn't seem people want to solve
this problem in general, so we might focussing on getting this in Debian
right at least.  (Going against the by now prejudice that Ruby in Debian
is a mess because of that really old split-up of the stdlib).

Paul

1: Just created the interface[2], thought about the architecture
   but couldn't find a way to make it work.
2: http://target.luon.net/~paul/tmp/rubydoc.rb.help

-- 
Student @ Eindhoven                         | email: paulvt at debian.org
University of Technology, The Netherlands   | JID: paul at luon.net
>>> Using the Power of Debian GNU/Linux <<< | GnuPG key ID: 0x50064181
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.alioth.debian.org/pipermail/pkg-ruby-extras-maintainers/attachments/20051211/a7b7b61d/attachment.pgp