[Python-Dev] Distribution tools: What I would like to see (original) (raw)

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 comprehensive manuals.

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 developers.

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 mailing list