[Python-Dev] Distribution tools: What I would like to see
Phillip J. Eby
pje at telecommunity.com
Sun Nov 26 23:36:27 CET 2006
At 01:21 PM 11/26/2006 -0800, Mike Orr wrote:
>A comprehensive third-party manual that integrates the documentation
>would be a good place to start. Even the outline of such a manual
>would be a good. That would give a common baseline of understanding
>for package users, package developers, and core developers.
A number of people have written quick-start or how-to guides for
setuptools, although I haven't been keeping track.
I have noticed, however, that a signficant number of help requests for
setuptools can be answered by internal links to one of its manuals -- and
when a topic comes up that isn't in the manual, I usually add it.
The "diff" issue is certainly there, of course, as is the fact that there
are multiple manuals. However, I don't think the answer is fewer manuals,
in fact it's likely to be having *more*. What exists right now is a
developer's guide and reference for setuptools, a reference for the
pkg_resources API, and an all-purpose handbook for easy_install. Each of
these could use beginner's introductions or tutorials that are deliberately
short on details, but which provide links to the relevant sections of the
My emphasis on the existing manuals was aimed at early adopters, who were
likely to be familiar with at least some of distutils' hazards and
difficulties, and thus would learn most quickly (and be most motivated) by
seeing what was different. Obviously, nearly everybody in that camp has
either already switched or decided they're not switching due to investment
in other distutils-wrapping technologies and/or incompatible
philosophies. So, the manuals are no longer adequate for the next wave of
Anyway, I would be happy to link from the manuals and Cheeseshop page to
quality tutorials that focus on one or more aspects of developing,
packaging, or distributing Python projects using setuptools.
More information about the Python-Dev