[Python-Dev] Distribution tools: What I would like to see

[Phillip J. Eby]

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.