More documentation on all operations

Makefile

@@ -1,7 +1,6 @@
 include Makefile.conf
 
-.PHONY: all dist dist-egg dist-whl install install-prefix install-sys compile clean devenv envtest docs clean-docs
-
+.PHONY: all dist dist-egg dist-whl install install-prefix install-sys compile clean devenv envtest docs clean-docs test
 all: dist
 
 # Build
@@ -33,13 +32,6 @@ install: compile
 install-user: compile
 	pip3 install . --user
 
-clean: clean-docs
-	rm -rf $(BUILD_DIR)
-	rm -rf $(DIST_DIR)
-	rm -rf $(PYTHON_ARTIFACTS)
-	rm -rf $(VERSION_FILE)
-	rm -rf $(BUILD_INPLACE)
-
 
 # Envrionment
 # ===========
@@ -47,20 +39,47 @@ clean: clean-docs
 # already set for the prefix specified in local.conf
 # Only activates venv if already existing
 venv:
-	python3 -m venv _venv
+	python3 -m venv $(VENV_DIR)
 	LD_LIBRARY_PATH=$(PREFIX)/lib \
 	DYLD_LIBRARY_PATH=$(PREFIX)/lib \
-	bash --rcfile _venv/bin/activate
+	bash --rcfile $(VENV_DIR)/bin/activate
 
 # Tests if the current environment is able to load the pEp module
 envtest:
 	python3 -c 'import pEp'
 
+# Test
+# ====
+# Use these targets only in venv created with 'make venv'
+install-test: compile
+	pip3 install .[test]
+
+test: install-test
+	pytest
+
+
+# Development
+develop: compile
+	pip install -e .
+
 
 # Documentation
 # =============
 docs:
 	make html -C docs/
 
+
+# Housekeeping
+# ============
+clean-all: clean
+	rm -rf $(VENV_DIR)
+
+clean: clean-docs
+	rm -rf $(BUILD_DIR)
+	rm -rf $(DIST_DIR)
+	rm -rf $(PYTHON_ARTIFACTS)
+	rm -rf $(VERSION_FILE)
+	rm -rf $(BUILD_INPLACE)
+
 clean-docs:
 	make clean -C docs/

Makefile.conf

@@ -7,8 +7,8 @@ VERSION_FILE = ./src/pEp/__version__.py
 BUILD_INPLACE = ./src/pEp/_pEp.cpython-38-darwin.so
 PYTHON_ARTIFACTS += ./.eggs
 PYTHON_ARTIFACTS += ./src/pEp.egg-info
-
-
+PYTHON_ARTIFACTS += ./.pytest_cache
+VENV_DIR = ./_venv
 
 # Build config Defaults
 DEBUG=0

docs/source/install.rst

@@ -30,7 +30,6 @@ all the build options. You can use this as a template.
 
 ``cp local.conf.example local.conf``
 
-
 If you have pEp-base installed under a custom prefix (e.g. /home/foo/local) it is important
 that you specify "PREFIX".
 
@@ -40,29 +39,60 @@ To build the module just type:
 
 ``make``
 
+This will compile the C/C++ parts of the module and create the python packages in the .egg and .wheel format
+in the dist/ dir.
+
 Installation
 ------------
-You can install this adapter in the in the following ways:
+You can install the module in the in the following ways:
 
 To install the extension module system wide or into a venv:
 
 ``make install``
 
-
 To install the extension module into you home dir:
 
 ``make install-user``
 
 
-If you're working on different Python projects, it's recommended to use
-`virtualenv <https://virtualenv.pypa.io/en/stable/>`_ to have different
-libraries versions.
+Virtualenv
+----------
+We recommend using a venv to work on/with the pEpPythonAdapter.
+There is a convenience make target that will create and activate a venv that already has the LD_LIBRARY_PATH
+or DYLD_LIBRARY_PATH set according to your ```local.conf``.
+If the venv is not existing yet it will be created and activated.
+If the venv already exists it will only be activated.
+
+``make venv``
+
+After that, to install the pEp module into the venv, do:
+
+``make install``
+
+Test
+----
+To run the whole testsuite you need to create/activate the venv, and then invoke the make target 'test'.
+You can do this from a clean clone of the repo, no prior actions required, the whole module and all dependencies
+will be compiled and installed into the venv.
+
+``make venv``
+``make test``
+
+
+Module Development
+------------------
+To develop on the module itself, first of all create and activate a venv:
+
+``make venv``
+
+Then, in the venv install the module in development mode.
 
-If you're working in a virtualenv you can also install the package with
-``pip install .``
+``make develop``
 
-To install the package in "develop mode", run ``python setup.py develop``
-or ``pip install -e .``
+While developing there are two levels of changes. Changes to the python part of the module (pEp), and
+changes to the C/C++ part of the module (_pEp). If you change just python code, the changes are effective immediately.
+If you do changes to the C/C++ part you need to issue ``make develop`` again, to recompile the extension and install
+the new binary (.so/.dylib) of the module into the venv.
 
 
 Docker

src/pEp/__init__.py

@@ -30,12 +30,6 @@ from ._pEp import *
 # with an underscore (of _pEp), but we dont want to import them into this module
 import pEp._pEp
 
-# TODO: Commented out until problems solved
-# try:
-#     __version__ = get_distribution(__name__).version
-# except DistributionNotFound:
-#     print("Package is not installed.")
-
 # Executed on module import
 def init():
     print(init, "called")