Documentation is confusing.
Actually, it's more like if would prefer throwing myself through the nearest windows instead of reading distribute doc. Sadly I work on the ground floor.
For instance, consider this page : http://packages.python.org/distribute/setuptools.html . The name setup_tool is employed more often the the actual project name, Distribute. When it come to installation, pip is never mentioned.
Python's packaging landscape is a mess. And the Distribute project add to this mess. Every time I try to dive into the Distribute documentation, a sentiment of despair grow and I wonder "Why got can't them call a spade a spade".
"Distributing a setuptool-based project" chapter propose to use distribute_setup to allow user to install my package without having setuptool by isntalling it for him. Wait what ? Is that a setuptool page or a distribute one ? Does distribute_setup really fetch a setuptool package from pypi or a Distribute one ?
After one minute of reading, I'm not even sure any more that I'm still on the Distribute web page.
I'm going crazy. The only thing I feel when trying to package a python program is "I need to stop Python for ever". Why do you use "setuptool" instead of "distribute", "easy_install" instead of "pip" ? Why do you hate so much the python packager beginner ? Why don't you want create a clear separation between setuptool and distribute ?