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

[Phillip J. Eby]

At 02:13 PM 7/26/2007 -0500, Dave Peterson wrote:
>In further discussions at Enthought, we're now thinking that creating a
>'docs' dir as a top-level under python itself makes sense, and then the
>installation of eggs could copy docs and/or examples there in a manner
>similar to how it handles scripts into the platforms scripts dir.   It
>would make sense that they should be put in dirs named with a format
>like <project name>-<version> so that the user could differentiate the
>docs for each project they installed.  If this was done, it seems like
>it wouldn't be too hard for Stan, and other rpm builders, to either
>create symbolic links or copy these to /usr/share/doc in order to
>maintain compatibility with the LSB.

This isn't a bad idea, although I think that there are some hurdles 
that need to be worked out.  My general thought is that, were 
easy_install to support documentation, it would need to take an 
option to determine the documentation base directory, and have a 
--no-docs install option.

One issue is that under most RPM systems, package names are more like 
'python-foobar-1.2', and 'foobar' may not even be the exact distutils 
name of the package.  So, installing the docs to the correct location 
in the general case may be more complex.  Note, however, that 
bdist_rpm offers a --doc-files option, which of course can be 
configured via setup.cfg.  I have no idea how it works, though, so 
don't ask me.  :)


>One other thought we've been throwing around is an idea of adding
>something to easy-install so that users can still get a minimal binary
>distribution if they want, and then, if they want docs, run a command like:
>     easy_install --get-docs enthought.traits
>where easy_install would then introspect the enthought.traits egg and
>figure out how to retrieve the docs and install them into ../python/docs.

Actually, if the default is for easy_install to install 
documentation, then simply rerunning easy_install should suffice 
(easy_install on an already-installed package makes the package 
active and installs scripts, so installing docs should work the same way.)