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

[Stanley A. Klein]

On Thu, July 26, 2007 12:46 pm, Phillip J. Eby wrote:
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.


This relates to a question I asked this list earlier this month (but
didn't get a response).  For Linux systems the Linux Standards Base
references the Unix Filesystem Hierarchy Standard (that applies to all
Unix systems as well).  The FHS specifies that documentation files (other
than specially formatted items like man pages) go into

/usr/share/doc/package_name_and_version

These sometimes include examples, demos, and similar files.  For example,
the docs on my FC5 system for inkscape go in
/usr/share/doc/inkscape-0.45.1.  In that case the doc files are a typical
minimal set:

/usr/share/doc/inkscape-0.45.1/AUTHORS
/usr/share/doc/inkscape-0.45.1/COPYING
/usr/share/doc/inkscape-0.45.1/ChangeLog
/usr/share/doc/inkscape-0.45.1/NEWS
/usr/share/doc/inkscape-0.45.1/README

and the examples, tutorials, clipart, and many miscellaneous files are in
/usr/share/inkscape.  The actual executables are in /usr/bin.

In some cases the documentation is created as a separate package.  For
example, Python does this for its html-based docs and on my FC5 system,
the python html docs are in /usr/share/doc/python-docs-2.4.3/.  Similar
considerations go to configuration files that are supposed to go into
/etc.  There are a number of other rules, and they are generally observed
by systems that use rpm and deb packaging such as Fedora and Ubuntu.

I couldn't figure out how to make this happen when using bdist_rpm, which
is why I asked the earlier question.  It seems to me that the only way
using current Python packaging features would be to put the docs somewhere
in the Python site-packages hierarchy and do a post-install scripted move
to where they belong under the LSB/FHS rules.  It would be preferable to
get them to go where they belong without the need for post-install
scripting.


Stan Klein