Re: [Distutils] Best practices for creating eggs?
At 10:37 AM 6/29/2006 +0100, Paul Moore wrote:
On 6/28/06, Phillip J. Eby <pje@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.)
On 6/29/06, Phillip J. Eby <pje@telecommunity.com> wrote:
Note that I said above that I always put the documentation in an sdist form;
Noted. The distinction I'm trying to make is that with bdist_wininst, it's part of the binary installer - a single install gets the module and its documentation, with no decisions needed by me. I've no experience with other formats, so I'm afraid I can't compare this with bdist_rpm, bdist_deb (spot-checking bdist_msi, it looks like that packages the docs, as well). However, the package author clearly got existing distutils mechanisms to include the docs, so it's possible. I'm not trying to say this is a huge failing, just pointing out that it's something that existing formats do, that eggs might be interested in supporting.
You can then decide what to do with any docs in it.
Having to make a decision at all rather than them "just being there" is the (small) barrier I'm pointing out :-)
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.
Agreed. But in the absence of a standard, supporting package authors' existing approaches, which work with other distutils mechanisms, seems like a reasonable requirement. Paul.
participants (2)
-
Paul Moore -
Phillip J. Eby