Document the fact that edmtool install creates a non-editable install

[aaronayres35]

Document the fact that edmtool install installs the package in a non-editable mode and edmtool test runs the testsuite from an empty temporary directory - not from the root directory of the git repo. Because of this behavior, a developer might run into failures if they choose to manually discover/run the testsuite from the root of the git repo.

see below for the original issue

When running the testsuite I see some errors with:

No module named 'chaco.contour.contour'

The bad import attempts seem to be here:

chaco/chaco/contour_line_plot.py

Line 16 in 4a66835

from .contour.contour import Cntr

and here:

chaco/chaco/contour_poly_plot.py

Line 14 in 4a66835

from .contour.contour import Cntr

To reproduce:

$ python ci/edmtool.py install --toolkit=pyside2
$ edm shell -e chaco-test-3.6-pyside2
$ python -m unittest

which fails with:

======================================================================
ERROR: chaco (unittest.loader._FailedTest)
----------------------------------------------------------------------
ImportError: Failed to import test module: chaco
Traceback (most recent call last):
  File "/Users/aayres/.edm/envs/chaco-test-3.6-pyside2/lib/python3.6/unittest/loader.py", line 462, in _find_test_path
    package = self._get_module_from_name(name)
  File "/Users/aayres/.edm/envs/chaco-test-3.6-pyside2/lib/python3.6/unittest/loader.py", line 369, in _get_module_from_name
    __import__(name)
  File "/Users/aayres/Desktop/chaco/chaco/__init__.py", line 6, in <module>
    from ._version import full_version as __version__  # noqa
ModuleNotFoundError: No module named 'chaco._version'

So I then ran $ python setup.py sdist as I thought I remembered that this would generate _version. I then ran python -m unittest again to see the

No module named 'chaco.contour.contour'

errors mentioned above

When running:

$ python ci/edmtool.py install --toolkit=pyside2
$ python ci/edmtool.py test --toolkit=pyside2

I see no errors

[kitchoi]

I believe the chaco.contour.contour is an extension built from chaco/contour/cntr.c, so it might become missing if the build step has failed for some reasons. Is this from an installation of the source distribution or something else? If you could provide the steps to reproduce that would be good.

[aaronayres35]

I believe the chaco.contour.contour is an extension built from chaco/contour/cntr.c, so it might become missing if the build step has failed for some reasons. Is this from an installation of the source distribution or something else? If you could provide the steps to reproduce that would be good.

I updated the PR description

[jwiggins]

edmtool.py install --toolkit=<whatever> will run pip install chaco in the EDM environment which is created. This is not an in-place ("editable" in pip parlance) build. So when you then attempt to run Python from the root directory of your Chaco repository, all imports from chaco see the package in the current directory before the one in the environment's site-packages directory. That's why chaco._version and compiled extensions are missing.

[rahulporuri]

I'm updating the issue title/description to highlight the fact that this is a documentation/workflow issue and not a code issue.

[aaronayres35]

ref:

chaco/ci/edmtool.py

Lines 33 to 38 in 8065abb

	If you make changes you will either need to remove and re-install the
	environment or manually update the environment using ``edm``, as
	the install performs a ``python setup.py install`` rather than a ``develop``,
	so changes in your code will not be automatically mirrored in the test
	environment. You can update with a command like::
	edm run --environment ... -- python setup.py install

It seems this is already documented so I believe this issue can be closed. Although it might be useful to repurpose it as an issue for allowing specification of an editable install?
eg in traitsUI:
https://github.com/enthought/traitsui/blob/f7fa4b48d2223d60e1e3327bda2bf7501b0fba8e/etstool.py#L226-L230