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

[Talin]

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