better documentation

python/README.md

@@ -31,8 +31,12 @@ For more details, see the corresponding part of the [Python documentation](https
 1. Download the latest source code distribution (in `.tar.gz` format) of the TREXIO Python API
 2. Unpack and `cd` in the output directory
 3. Run `pip3 install -r requirements.txt` (this installs all python dependencies)
-4. Run `pip3 install .` (this installs `trexio` in your environment)
+4. Export custom environment variables needed for the installation. Steps 1 and 2 can be skipped if HDF5 is properly configured for `pkg-config` (i.e. if executing `pkg-config --libs hdf5` returns a list of options).
-5. Run `cd test && python3 test_api.py` (this executes several tests that verify the installation)
+   1. `export H5_CFLAGS=-I/path/to/hdf5/include`
+   2. `export H5_LDFLAGS=-L/path/to/hdf5/lib`
+   3. `source tools/set_NUMPY_INCLUDEDIR.sh`
+5. Run `pip3 install .` (this installs `trexio` in your environment)
+6. Run `cd test && python3 test_api.py` (this executes several tests that verify the installation)
 
 You are ready to go!
 
@@ -54,8 +58,9 @@ The example notebook can be launched using the following command:
 
 #### Additional steps needed to run a custom virtual environment in Jupyter notebooks
 
-If you have installed `trexio` in a virtual environemnt called, e.g. `myvenv`, but would like to use your system-wide Jupyter installation, this is also possible.
+In some cases, it may happen that the Jupyter kernels in the activated virtual environment (e.g. `myvenv`) still point to the system-wide python binaries and not to the environment ones.
-This requires `ipykernel` python package to be installed, which usually comes together with the Jupyter installation. If this is not the case, run `pip install ipykernel`. 
+This will result in `ImportError` when importing `trexio` in the notebook cell. In order to avoid this, the `myvenv` has to be installed as an additional kernel.
+This requires `ipykernel` python package, which usually comes together with the Jupyter installation. If this is not the case, run `pip install ipykernel`. 
 You can install `myvenv` as a kernel by executing the following command:
 
 `python3 -m ipykernel install --user --name=myvenv`

python/README_SETUP.txt

@@ -1,24 +0,0 @@
-# Additional information related to the installation of the TREXIO Python API
-
-Removing MANIFEST.in leads to issues in the installation. In particular, the .c and .h source files do not get copied 
-from the src/ directory into the tar.gz which is produced by setup sdist command. 
-These source files are required to build the pytrexio.so extension module, which is needed for the Python API.
-
-Then the following commands do the job of installing trexio in virtual environment:
-
-$ python3 -m pip install --upgrade setuptools wheel twine
-$ python3 -s setup.py --no-user-cfg build
-$ python3 setup.py sdist bdist_wheel
-$ python3 -m pip install dist/trexio-0.1-*.whl --force-reinstall
-
-BUG: when trying to install trexio from tar.gz, trexio appears to be installed 
-after user runs [python3 -s setup.py --no-user-cfg build] 
-but before [python3 -m pip install dist/{WHEELNAME}.whl]
-which leads to pip install saying that trexio is already installed but the test fails saying that _trexio was not found,
-indicating that probably first installation did not go well. 
-FIX: Use --force-reinstall option with pip install
-
-The installed in virtual environment trexio can be uninstalled using [pip uninstall trexio] 
-but only from the root directory where the initially used (to install) setup.py script is located. 
-For example, it is most probably the python/ directory of the TREXIO_ROOT folder.
-

python/install_pytrexio.sh

@@ -6,8 +6,6 @@ set -e
 H5_CFLAGS_LOCAL=$1
 H5_LDFLAGS_LOCAL=$2
 
-# This script should update the version of the Python package
-#source version.py
 
 # Install/upgrade packages required for the installation
 python3 -m pip install --upgrade setuptools wheel twine
@@ -33,23 +31,21 @@ python3 -m pip install dist/trexio-*.whl --force-reinstall
 # Run the command below in the root directory to install the package in 'editable' (-e) mode without dependencies (--no-deps)
 #python -m pip install -e . --no-deps
 
-# Uninstall pytrexio: this only works from the pytrexio root directory (more likely python/ folder) and only after --force-reinstall
+# Uninstall pytrexio: this only works from the pytrexio root directory
 #python3 -m pip uninstall trexio
 
 # Test the current release by uploading to TestPyPI sandbox
 #python3 -m twine upload --repository testpypi dist/trexio-*.tar.gz
 
-# NOTE:I get an error: 
-#      Binary wheel 'trexio-0.1-cp38-cp38-linux_x86_64.whl' has an unsupported platform tag 'linux_x86_64'.
-# when uploading the wheel instead of the tar.gz file to testpypi
-# This is a well-known issue, see https://stackoverflow.com/questions/59451069/binary-wheel-cant-be-uploaded-on-pypi-using-twine
-# Once fixed both .tar.gz and .whl distribution can be uploaded, meaning that dist/trexio-*.tar.gz can be replaced by dist/*
-#
-# Compatibility tags for Linux have been discussed in PEP-513 https://www.python.org/dev/peps/pep-0513/
-
 # Upload updated version of PyTREXIO to PyPI
 #python3 -m twine upload dist/trexio-*.tar.gz
 
 # Cleaning
 rm -rf build dist trexio.egg-info
 
+# Additional information related to the installation of the TREXIO Python API
+
+#Removing MANIFEST.in leads to issues in the installation. In particular, the .c and .h source files do not get copied 
+#from the src/ directory into the tar.gz which is produced by setup sdist command. 
+#These source files are required to build the pytrexio.so extension module, which is needed for the Python API.
+