Show how to troubleshoot common issues

While building the documentation I met some errors and warnings that were not documented and only found out when dug  a little bit. Am here by making them more visible to make it convenient for new users
This commit is contained in:
Stefano D. Mtangoo 2020-12-05 14:06:03 +03:00 committed by GitHub
parent e85ef2298b
commit 2c0debed68
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -18,3 +18,23 @@ Then you can build the documentation with::
make
You should find the rendered documentation in the ``html`` directory.
Troubleshooting
----------------------------------
1. Outdated pip version
If you get warning of having old pip version be sure to upgrade it.
>WARNING: You are using pip version 20.2.4; however, version 20.3.1 is available.
>You should consider upgrading via the 'PATH_TO_ROOT_FOLDER/psycopg2-2.8.6/doc/env/bin/python -m pip install --upgrade pip' command.
TO fix it and upgrade it successful just follow what the warning message says, i.e run this command on the terminal `PATH_TO_ROOT_FOLDER/psycopg2-2.8.6/doc/env/bin/python -m pip install --upgrade pip`
2. Missing "psycopg.pth" file
When running `make env` and encounter this error, it most likely it is picking wrong non-existent version of python. In that case you need to tell it what is the correct version that is active. The error message looks like this
>echo "$(pwd)/../build/lib.2.7" \
> > env/lib/python2.7/site-packages/psycopg.pth
>/bin/sh: env/lib/python2.7/site-packages/psycopg.pth: No such file or directory
>make: *** [env] Error 1
To specify your active Python version you have to define `PYTHON_VERSION` environment variable. For example in Unix with let say Python 3.9 active it goes like:
`export PYTHON_VERSION=3` then you can happily run `make env` and the error should be gone