I've just read through the Distribute doc for the first time and I have a few comments.
First, I just want to say that the state of python packaging is a sad morass. It's not easy for someone to sort out distutils/setuptools/distribute to figure out how to get a package built and released on pypi. Distutils is official and available, but the documentation is only slightly relevant with much time and space given to features that aren't clear, aren't relevant, or don't solve today's problems. Setuptools is messy, confusing, ill documented, and difficult to use. The Distribute documentation helps in this considerably but it could be better.
I wish that the Distribute documentation didn't refer to itself as "setuptools". This is confusing. From where I'm sitting, Distribute is a fork. It may have started life once upon a time in a distant past that I don't care about as a fork of setuptools but as of today, it's a separate package which just happens to provide a superset of the setuptools features along with a setuptools compatible replacement interface. To say that one can use a Distribute script to install "setuptools" is a misnomer. It suggests that the original setuptools is being installed rather than installing Distribute, (which just happens to provide functional replacements for setuptools). That's not what I want. I want Distribute and Distribute alone. I'm willing to go to some effort to make sure that people who use my package never need to know about, read about, or even think about setuptools.
Toward that end, I wish that the documentation would explain how to import Distribute specifically, in a non-setuptools compatible way. I don't need or want a setuptools compatible replacement. I have a new package and I'm completely willing to make my package wholly dependent on Distribute rather than setuptools. Even attempting to support setuptools at this point in history seems like a mistake to me. If I'm going to include distribute_setup.py in my package, then it seems to me that I'm already committed to Distribute, not setuptools. Leaving the illusion that an installer might be able to make setuptools work for my package seems misguided. I'd like to eliminate that thought.
The section on "What Your Users Should Know" sounds like the sort of information which has traditionally been released in an INSTALL file with GNU software. Is there a reusable, sample template which explains this information in a package agnostic sort of way that I can simply include in my package?
Thanks for reading.