At 10:37 AM 6/29/2006 +0100, Paul Moore wrote:
>On 6/28/06, Phillip J. Eby <[EMAIL PROTECTED]> 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.)
_______________________________________________
Distutils-SIG maillist - [email protected]
http://mail.python.org/mailman/listinfo/distutils-sig
