[Distutils] Best practices for creating eggs?

[Phillip J. Eby]

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
>ago.
>
>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.)