[Distutils] tests location: Use case: new comers and docs.

[Erik Bray]

On Wed, Oct 7, 2015 at 2:11 AM, Chris Barker <chris.barker at noaa.gov> wrote:
> On Tue, Oct 6, 2015 at 10:38 PM, Thomas Güttler
> <guettliml at thomas-guettler.de> wrote:
>>
>> Yes, there is not generic "one right way here".
>>
>> Yes, let's consider individual use cases.
>>
>> My use case are the docs for new comers:
>>
>>  - https://github.com/pypa/sampleproject
>>  - https://packaging.python.org/en/latest/distributing/
>>
>> That's why started the thread.
>
>
> unfortunately, that isn't  a use-case -- every newcomer has a different use
> case.

Indeed--I've helped newcomers whose very first attempt at packaging
Python code includes Cython code for simulations.  I think even for
newcomers what we should be providing is not a "this is the way to do
it" because then they get confused when that way doesn't work for
them.

Better, in the long term (and I'm happy to contribute to such an
effort if it will help) is to provide a sort of Choose Your Own
Adventure story.  It can't all go on one page because that would be a
mess, but a sort of "If you need to do this, read this.  If you need
to do this, read this.  Now if you need to include some data files
that are installed in your package read on, because there's really
only one right way to do that.  But now you have some options if you
want to include tests: ..."

> I was happy to see this thread, because I thought maybe I"d learn what i
> should teach my students - new to python.
>
> But alas - there clearly really is no consensus.
>
> What i've told newbies in the past is somethig like:
>
> """
> if you want your user to be able to install you package, and then run
> something like:
>
> import my_package
> my_package.test()
>
> then put your tests inside the package.
>
> If you are fine with only being able to run the tests from the source tree
> -- then put your tests outside the package.
> """
>
> but really, newbies have no idea how to make this decsion.
>
> Maybe we could come up with a decision tree for this -- some guidance for
> knowing what to do, when?

Exactly.  I think it could even be fun :)

How could we get started to add something like this to the packaging docs?

Erik