1
0
mirror of https://github.com/TREX-CoE/trexio.git synced 2024-12-23 04:43:57 +01:00

better documentation

This commit is contained in:
q-posev 2021-09-09 17:29:17 +02:00
parent 569fac5578
commit dcfe1da870
3 changed files with 16 additions and 39 deletions

View File

@ -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 1. Download the latest source code distribution (in `.tar.gz` format) of the TREXIO Python API
2. Unpack and `cd` in the output directory 2. Unpack and `cd` in the output directory
3. Run `pip3 install -r requirements.txt` (this installs all python dependencies) 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! 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 #### 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: You can install `myvenv` as a kernel by executing the following command:
`python3 -m ipykernel install --user --name=myvenv` `python3 -m ipykernel install --user --name=myvenv`

View File

@ -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.

View File

@ -6,8 +6,6 @@ set -e
H5_CFLAGS_LOCAL=$1 H5_CFLAGS_LOCAL=$1
H5_LDFLAGS_LOCAL=$2 H5_LDFLAGS_LOCAL=$2
# This script should update the version of the Python package
#source version.py
# Install/upgrade packages required for the installation # Install/upgrade packages required for the installation
python3 -m pip install --upgrade setuptools wheel twine 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) # 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 #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 #python3 -m pip uninstall trexio
# Test the current release by uploading to TestPyPI sandbox # Test the current release by uploading to TestPyPI sandbox
#python3 -m twine upload --repository testpypi dist/trexio-*.tar.gz #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 # Upload updated version of PyTREXIO to PyPI
#python3 -m twine upload dist/trexio-*.tar.gz #python3 -m twine upload dist/trexio-*.tar.gz
# Cleaning # Cleaning
rm -rf build dist trexio.egg-info 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.