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

Talin talin at acm.org
Mon Nov 27 04:11:18 CET 2006

Mike Orr wrote:

On 11/26/06, Phillip J. Eby <pje at telecommunity.com> wrote:

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. Hmm, I may have a couple topics for you after I check my notes.

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 pkgresources API, and an all-purpose handbook for easyinstall. 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. I could see a comprehensive manual running forty pages, and most readers only caring about a small fraction of it. So you have a point. Maybe more impotant than one book is having "one place to go", a TOC of articles that are all independent yet written to complement each other. But Talin's point is still valid. Users have questions like, "How do I structure my package so it takes advantage of all the gee-whiz cheeseshop features? Where do I put my tests? Should I use unittest, py.test, or nose? How will users see my README and my docs if they easyinstall my package? What are all those files in the EGG-INFO directory? What's that word 'distribution' in some of the function signatures? How do I use entry points, they look pretty complicated?" Some of these questions are multi-tool or are outside the scope of setuptools; some span both the Peak docs and the Python docs. People need an answer that starts with their question, rather than an answer that's a section in a manual describing a particular tool.

You said it way better than I did - I feel totally validated now :)

-- Talin

More information about the Python-Dev mailing list