[Distutils] Best practices on distributing documentation and examples with eggs?

[Phillip J. Eby]

At 03:02 AM 7/26/2007 -0500, Dave Peterson wrote:
>Over on the enthought-dev mailing list we're having a bit of a
>discussion on what the best way to distribute documenation and examples
>is for projects that we distribute binary eggs for.   The general
>consensus is that it would be very nice indeed if there was a way to
>generate a tarball, or platform install, of just documentation and
>examples so that people wouldn't need to download a full, presumably
>significantly larger, source tarball.   Another option would be that
>eggs included the documentation and examples and that, during the
>installation of the egg, those docs and examples were relocated to a
>common location (outside of the zip) to make access by users more
>convenient.  This latter idea is similar to how Ruby Gems deal with docs.
>
>I don't claim to be a distutils or setuptools guru, so it shouldn't be
>too surprising that I can't seem to find anything about a setuptools or
>distutils command to do either of these.   Am I missing something?

There are a few different ways you could do this.  The easiest would 
be to put a docs subdirectory either inside one of your packages or 
inside your .egg-info directory, then use the pkg_resources resource 
or metadata APIs to list and extract them.  One advantage to using 
something like .egg-info/docs would be that this could perhaps be 
recognized by some sort of "standard" tools in the future.

>If not, does it seem like something that might be worthy of putting into
>setuptools?

It might be worth establishing convention(s) for, yes.  Tools could 
then be developed around them, including perhaps changes to easy_install.