Setuptools: Document how to use setup.cfg with find_packages and the src layout

[pganssle]

When trying to create an MWE for #1436, I found it very hard to find the right syntax for using the src layout from setup.cfg. Here's what I landed on:

[options]
package_dir=
 =src
packages=find:
        where=src

It would be nice to see this in the documentation somewhere as it's a pretty common layout (and I daresay probably should be the preferred layout).

[pganssle]

Hm, actually, I don't know why I thought that was working, it seems to be failing for me now, so this is actually now a two-step ticket:

1. figure out how to create a package with a layout like this:

$ tree .
.
├── setup.cfg
├── setup.py
└── src
    └── pkg
        └── __init__.py

and a setup.py like this:

from setuptools import setup

setup()

1. Document how to do it.

If it turns out to not currently be possible, we can turn this into a bugfix ticket.

[madig]

I can't get pip/setuptools to install my package if I just use "find:". I have the minimal setup.py you pasted and this setup.cfg:

[metadata]
name=xxxyyy
version=0.0.1

[options]
package_dir=
    =src
packages=find:

Also an empty src/xxxyyy/__init__.py. Pip will install the package metadata fine, but not the actual xxxyyy/__init__.py 🤔 I'm using

pip        18.1
setuptools 40.5.0

Writing packages=xxxyyy in setup.cfg works and installs the actual package.

If I have:

[options]
package_dir=
    =src
packages=find:
    where=src

I get:

$ pip install .
Processing /private/tmp/testpy
    Complete output from command python setup.py egg_info:
    running egg_info
    creating pip-egg-info/xxxyyy.egg-info
    writing pip-egg-info/xxxyyy.egg-info/PKG-INFO
    writing dependency_links to pip-egg-info/xxxyyy.egg-info/dependency_links.txt
    writing top-level names to pip-egg-info/xxxyyy.egg-info/top_level.txt
    writing manifest file 'pip-egg-info/xxxyyy.egg-info/SOURCES.txt'
    error: package directory 'src/find:' does not exist

[madig]

Got it, setup.cfg must look like this:

[metadata]
name=xxxyyy
version=0.0.1

[options]
package_dir=
    =src
packages=find:

[options.packages.find]
where=src

This also works with pip 10.0.1 and setuptools 39.0.1.

[pganssle]

Thanks for digging into this @madig!

[madig]

Next stop: putting in a piece of documentation somewhere.