[Distutils] Integrating the packaging guide

[John Posner]

On 3/21/2010 11:52 AM, John Posner wrote:
>
>> Thanks for joining and welcome to the team. And Don't Panic ;-)

Not panicking, exactly ...

I've looked over the entire Hitchhiker's Guide. After a very nice Quick 
Start and pretty good initial sections in "Introduction to Packaging", 
things start to get more stream-of-consciousness-y and (to me) 
confusing. This seems to reflect the real world -- the "Current State of 
Packaging" diagram shows that this area of Python functionality is in a 
state of flux.

Here's a bunch of questions -- not necessarily orthogonal to each other 
-- concerning the Guide. I'm posting to the entire SIG, to see if 
there's consensus out there.

1. What is the intended relationship between the Hitchhiker's Guide, a 
short document, and these much lengthier documents:

For *distutils* --

Distributing Python Modules (http://docs.python.org/distutils/index.html)
Installing Python Modules (http://docs.python.org/install/index.html)

For *setuptools* --

Building and Distributing Packages with setuptools 
(http://peak.telecommunity.com/DevCenter/setuptools)

For *distribute* --

Welcome to Distribute’s documentation! 
(http://packages.python.org/distribute/)

2. In the many areas where disutils/setuptools/distribute provide 
overlapping functionality, should the Hitchhiker's Guide promote *the 
one best way* to accomplish a task, or should it compare and contrast 
the various ways?

3. Should the Hitchhiker's Guide be an overview document, with 
cross-refs to large sections of the disutils/setuptools/distribute 
documents? Or should it be a detailed document, with (many more) 
cross-refs to detail sections of the disutils/setuptools/distribute 
documents?

Thanks for helping me get up to speed ...

-John