[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