[Pkg-ruby-extras-maintainers] Re: howto package a library with docs, examples and tests ?

[Lucas Nussbaum]

On 17/11/05 at 08:58 +0100, Lucas Nussbaum wrote:
> Hi,
> 
> Yesterday, I worked on the packaging of the XMPP4R library. It is a
> rather large library which includes docs, examples, and unit tests.
> 
> I think we should come up with a common policy on how we should package
> libraries :
> 
> - should examples, rdoc documentation, ri documentation, unit tests be
>   packaged ?
> 
> - should they be packaged in only one other package (-dev ? -doc ?) or
>   several others ? (-examples, -doc, -tests) ?
> 
> - How do one generate documentation for ri ?
> 
> - I think that it would be a good idea to package unit tests, because
>   that would allow for automatic testing of packages after installation.
> For example, rake was recently broken in sid : it was ok when it was
> uploaded, but the upgrade from ruby 1.8.2 to ruby 1.8.3 broke it.
> This could have been detected by some unit tests run by a cron job.
> (Also, it would ease the work of developers who work on ruby packaging
> in ubuntu, by making it very easy to track down issues introduced by a new
> package :-)
> 
> - What should we include in the rdoc files ? public methods only ?
>   inline source ? diagrams ? (they are very cool!) I usually generate my
> HTML doc with rdoc --all --diagram --fileboxes --inline-source
> --line-numbers. But this creates a 1.8M -doc package for libxmpp4r-ruby,
> while the library itself is only 36K...
> 
> My libxmpp4r-ruby package in the pkg-ruby-extras SVN repository does
> multipackaging and generates rdoc at package build time. We an use it as
> a basis for discussion.

Replying to myself, and Ccing
pkg-ruby-extras-maintainers at lists.alioth.debian.org

After thinking about it for a while, I came to the conclusion that we
have to consider the user's point of view. There are two kinds of
library users :
- those only using software that relies on this library. Those don't
  care about rdoc documentation, etc.
- those developing software using this library. Those want as much help
  as possible.

Therefore, I think ruby libraries should be packaged using two binary
packages :
- libxxxxx-ruby1.8: contains only /usr/lib/ruby/1.8/xxxx/* and the
copyright/changelog stuff.
- libxxxxx-ruby1.8-dev: contains examples, unit tests, rdoc
  documentation, ri documentation.

About unit tests: it would be great to have a common architecture to
deal with our unit tests. This way, one could run a script on a regular
basis to check that all his installed packages still work correctly.

About ri documentation: is there a debian package already generating
some of it, except the ri1.8 package itself ?

About rdoc documentation: it tends to be *big*. Here are some number
while generating XMPP4R's documentation :

Options: --all --diagram --fileboxes --inline-sources --line-numbers
Time: 84s
Size: 4756k

Options: --diagram --fileboxes --inline-sources --line-numbers (removed
--all)
Time: 81s
Size: 4642k
(Expected, since I don't use many private methods)

Options: --diagram  --inline-sources --line-numbers (removed --all
--fileboxes)
Time: 65s
Size: 3220k
Removing --fileboxes decreases the size of diagrams slightly.

Options: --inline-sources --line-numbers (removed --all --diagram
--fileboxes)
Time: 17s
Size: 1000k
Diagrams seem to take a lot of space.

Options:  (removed --all --diagram --fileboxes --inline-sources
--line-numbers)
Time: 17s
Size: 2096k
When source is not inlined, it uses much more space.
 
So it seems that the biggest contribution to the rdoc doc is diagrams.
Looking at them, it seems most of them are redundant (they are the same
except for the title). Maybe one could look at the rdoc code and see if
a patch is possible ?

I've updated libxmpp4r to split files according to the above policy.
-- 
| Lucas Nussbaum
| lucas at lucas-nussbaum.net   http://www.lucas-nussbaum.net/ |
| jabber: lucas at nussbaum.fr             GPG: 1024D/023B3F4F |