Convert PlantCV to a Namespace package

Description

A goal for the PlantCV3 project is to develop some new functionality as sub-packages that are distributed separately from the base PlantCV package (e.g. issue #203). This can be achieved by converting PlantCV to a "namespace" package. Sub-packages in a namespace package can be (but don't have to be) distributed independently of the main package. See the Packaging Namespace Packages article for more details. Our belief is that the benefit of this for some purposes is to keep the base PlantCV relatively lightweight.

To achieve this we need to make one big change that will break previously developed scripts, but it's an easy one-line fix to return scripts to an equivalently working state.

Details

To maintain compatibility between Python2 and 3 we are electing to achieve the above using the pkgutil-style namespace packaging method. Using this method the top-level __init__.py will not be compatible with our current package configuration. We propose to move the entire base PlantCV package into a subpackage called base. The new structure would look like this in GitHub:

/plantcv
    /plantcv
        __init__.py
        /base
            __init__.py
            acute.py
            ....etc
        /learn
setup.py
...etc

This means that import plantcv will no longer import any functions like it does now and instead import plantcv.base would be required. To achieve existing functionality that we assume most people use (or a variant thereof) one could do from plantcv import base as pcv. Then functions could be called as normal, for example: pcv.acute().

New distribution packages (e.g. plantcv-hyperspectral) would have the same structure and share the identical top-level __init__.py file:

/plantcv
    /plantcv
        __init__.py
        /hyperspectral
            __init__.py
            ....etc
setup.py
...etc

After installing plantcv and plantcv-hyperspectral, for example, the distribution package can be called from the plantcv namespace, e.g.: import plantcv.hyperspectral.

The code change to achieve this is easy but we will need to update several sections of the documentation.

Completion Criteria

[x] Create base subpackage and move base functions
[x] Create new top-level __init__.py file
[ ] Update the Contribution guide
[x] Update tutorials and other function documents in the documentation
[x] Test code and docs builds

danforthcenter / plantcv