[Distutils] Missing documentation for proper handling of PEP420 namespace packages in setup.py

[Christoph Schmitt]

I am using the newest versions of setuptools (15.0) and pip (6.1.1) with 
Python 3.4. I wanted to satisfy the following two requirements at the 
same time, but had some trouble:
A) creating and installing two source distribution tarballs which have 
the same top level namespace package (no __init__.py for namespace 
package) with setuptools and pip
B) having other packages within the same namespace package outside of 
<python>/site-packages in the PYTHONPATH (not managed by pip/setuptools)

Since Python >= 3.3 supports namespace packages out of the box (PEP420) 
this seemed to me like a straightforward task. However, it turned out to 
be not. Either, setuptools would not find my modules, pip would not 
install them properly or requirement B) was broken. The solution that 
worked for me, was to omit the namespace_packages=['whatever_namespace'] 
declaration in setup.py (to prevent the creation of *-nspkg.pth  files 
by pip) and not to use find_packages, which does not comply with PEP420 
(no packages found).

This solution is somewhat counter-intuitive and I am not sure, whether 
it is an intended/valid configuration of a setup.py file. Definitely, it 
is not clear from the documentation (which has a section about namespace 
packages btw.). Since I read into 
https://bitbucket.org/pypa/setuptools/issue/97 I now know that 
convenient support PEP420 is not easy to achieve for setuptools 
(regarding find_packages). However it would have been very helpful, if 
the documentation explained how to handle PEP420-compliant namespace 
packages (without any __init__.py) in setup.py. At least I would have 
expected a hint that there are caveats regarding PEP420 with a link to 
issue 97.

I also created a minimal example to reproduce the issue, which I can 
provide if anyone is interested.

Kind regards,
Christoph Schmitt