[Python-Dev] Distribution tools: What I would like to see
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
>> 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 :)
More information about the Python-Dev