Cleanup of install docs

diff --git a/docs/api/pq.rst b/docs/api/pq.rst
index 2d93f98948ce66453364b052d39f37413ce17594..85a1591c0975cf5608ffce1405a31c860d2f7d3f 100644 (file)
--- a/docs/api/pq.rst
+++ b/docs/api/pq.rst
@@ -50,7 +50,12 @@ module constant.
 At import, Psycopg 3 will try to use the best implementation available and
 will fail if none is usable. You can force the use of a specific
 implementation by exporting the env var :envvar:`PSYCOPG_IMPL`: importing the
-library will fail if the requested implementation is not available.
+library will fail if the requested implementation is not available::
+
+    $ PSYCOPG_IMPL=c python -c "import psycopg"
+    Traceback (most recent call last):
+       ...
+    ImportError: couldn't import requested psycopg 'c' implementation: No module named 'psycopg_c'
 
 
 Module content

diff --git a/docs/basic/install.rst b/docs/basic/install.rst
index ea8c2310801b6a3c4dc840d54d087a270b463cfd..6e13c4164d1297ba0ebef9cc6d8560873133cff3 100644 (file)
--- a/docs/basic/install.rst
+++ b/docs/basic/install.rst
@@ -6,8 +6,8 @@ Installation
 Installing the development state
 --------------------------------
 
-Psycopg 3 packages have not been released yet, but you can try it out
-already by installing it `from the GitHub project`__:
+Psycopg 3 packages have not been released on the PyPI index yet: you can try
+it out by installing it `from the GitHub project`__:
 
 .. code:: bash
 
@@ -17,11 +17,11 @@ already by installing it `from the GitHub project`__:
 
 .. __: https://github.com/psycopg/psycopg
 
+or from `the TestPyPI index`__::
 
-.. _binary-install:
+    pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ psycopg
 
-Binary installation
--------------------
+.. __: https://test.pypi.org/project/psycopg/
 
 .. warning::
 
@@ -33,20 +33,35 @@ Binary installation
 
     .. __: https://github.com/psycopg/psycopg#readme
 
-    The following is how it will be *supposed* to work, once it is released...
 
+.. _binary-install:
+
+Binary installation
+-------------------
 
 The quickest way to start developing with Psycopg 3 is to install the binary
 packages by running::
 
     pip install psycopg[binary]
 
+.. warning::
+
+    Add the following options to pip::
+
+        -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/
+
+    to install the Psycopg from TestPyPI, before the final packages are
+    uploaded on PyPI.
+
 This will install a self-contained package with all the libraries needed.
+You will need pip >= 20.3 at least: please run ``pip install -U pip`` to update
+it beforehand.
 
 The above package should work in most situations. It **will not work** in
-some though:
+some cases though:
 
-- the ``binary`` package doesn't work on Alpine Linux;
+- you need a glibc-based Linux distribution: the ``binary`` package doesn't
+  work on Alpine Linux for instance;
 - you have a newly released Python or Mac Os X version for which binary
   packages are not ready yet.
 
@@ -62,6 +77,9 @@ In these case you should proceed to a :ref:`local installation
     You can come back here if you the above method didn't work and you need a
     way to install Psycopg 3 past the basic one.
 
+    For further information about the differences between the packages see
+    :ref:`pq-impl`.
+
 
 .. _local-installation:
 
@@ -71,7 +89,8 @@ Local installation
 A "Local installation" means obtaining a performing and maintainable library.
 The library will include a performing C module and will be bound to the system
 libraries (``libpq``, ``libssl``...) so that system upgrade of libraries will
-upgrade the libraries used by Psycopg 3 too.
+upgrade the libraries used by Psycopg 3 too. This is the preferred way to
+install Psycopg for a production site.
 
 In order to perform a local installation you need some prerequisites:
 
@@ -88,6 +107,15 @@ If your build prerequisites are in place you can run::
 
     pip install psycopg[c]
 
+.. warning::
+
+    Add the following options to pip::
+
+        -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/
+
+    to install the Psycopg from TestPyPI, before the final packages are
+    uploaded on PyPI.
+
 
 .. _pure-python-installation:
 
@@ -100,19 +128,45 @@ If you simply install::
 
 without ``[c]`` or ``[binary]`` extras you will obtain a pure Python
 implementation. This is particularly handy to debug and hack, but it still
-requires the system libpq to operate (which will be used dynamically via
+requires the system libpq to operate (which will be imported dynamically via
 `ctypes`).
 
 In order to use the pure Python installation you will need the ``libpq``
 installed in the system: for instance on Debian system you will probably
 need::
 
-    sudo apt-get install libpq5
+    sudo apt install libpq5
 
 If you are not able to fulfill this requirement please follow the `binary
 installation`_.
 
 
+Handling dependencies
+---------------------
+
+If you need to specify your project dependencies (for instance in a
+``requirements.txt`` file, ``setup.py``, ``pyproject.toml`` dependencies...)
+you should probably specify one of the following:
+
+- If your project is a library, add a dependency on ``psycopg``. This will
+  make sure that your library will have the ``psycopg`` package with the right
+  interface and leaves the possibility of choosing a specific implementation
+  to the end user of your library.
+
+- If your project if a final application (e.g. a service running on a server)
+  you can require a specific implementation, for instance ``psycopg[c]``,
+  after you have made sure that the prerequisites are met (e.g. the depending
+  libraries and tools are installed in the host machine).
+
+In both cases you can specify which version of Psycopg to use using
+`requirement specifiers`__.
+
+.. __: https://pip.pypa.io/en/stable/cli/pip_install/#requirement-specifiers
+
+If you want to make sure that a specific implementation is used you can
+specify the :envvar:`PSYCOPG_IMPL` environment variable: importing the library
+will fail if the implementation specified is not available. See :ref:`pq-impl`.
+
 
 Psycopg 3 and the ``libpq``
 ---------------------------