[Distutils] Best practices for creating eggs?

Phillip J. Eby pje at telecommunity.com
Thu Jun 29 16:34:24 CEST 2006

At 10:37 AM 6/29/2006 +0100, Paul Moore wrote:
>On 6/28/06, Phillip J. Eby <pje at telecommunity.com> wrote:
>>I assume that most people will read the docs on the web, and that if they
>>want the documentation source, they will download the "sdist" distribution
>>that I always upload alongside of the eggs.
>I work offline sufficiently often that not having local documentation
>is frustrating. There's no standard for local docs, which is a
>nuisance, and makes for an inconsistent story between different
>packages, but I'd be concerned if setuptools made it more difficult to
>bundle local docs.
>An example - cx_Oracle provides a full set of HTML documentation which
>the bdist_wininst installer drops in C:\Python24\cx_Oracle-doc. The
>one time I tried using easy_install to convert this to an egg, the
>documentation got missed out. I've never retried the experiment,
>however, so things could well have changed, as this was quite a while
>And of course, eggs which get installed as zip files don't really
>offer anywhere to *put* documentation which is accessible (web
>browsers can't load HTML out of zip files, for example).

Note that I said above that I always put the documentation in an sdist 
form; to obtain a package's source distribution, use:

     easy_install -e -b somedir arg...

Where 'arg...' is some specification of a package, and 'somedir' is the 
parent directory of where you want the package's source to be unpacked or 
checked out.  If you requested e.g. 'cx_Oracle', you will end up with a 
'somedir/cx_oracle' directory containing the extracted source 
distribution.  You can then decide what to do with any docs in it.

A standard for how to install documentation would be great, because then 
you could run the docinstall command or whatever it's called on the source 
directory.  For that matter, easy_install could be made to do it also.

(Of course, this could presumably be included in eggs also, but I'm 
thinking of it being a separate operation from installing the eggs, just 
because it's increasingly common to be installing a package to satisfy some 
other package's dependency -- not because you actually intend to use that 
package directly.  OTOH, relatively small packages compared to their 
documentation size might just want to throw it in.)

More information about the Distutils-SIG mailing list