Document installation from wheel packages

2 files changed, 87 insertions, 148 deletions

diff --git a/README.rst b/README.rst
index f18be56..03c84c4 100644
--- a/README.rst
+++ b/README.rst
@@ -29,8 +29,14 @@ Documentation is included in the 'doc' directory and is `available online`__.
 Installation
 ------------
 
-If all the dependencies are met (i.e. you have the Python and libpq
-development packages installed in your system) the standard::
+If your ``pip`` version supports wheel_ packages it should be possible to
+install a binary version of Psycopg including all the dependencies. Just run::
+
+    pip install psycopg2
+
+If you want to build Psycopg from source you will need some prerequisite (a C
+compiler, Python and libpq development packages). If you have what you need
+the standard::
 
     python setup.py build
     sudo python setup.py install
@@ -38,7 +44,8 @@ development packages installed in your system) the standard::
 should work no problem.  In case you have any problem check the 'install' and
 the 'faq' documents in the docs or online__.
 
-.. __: http://initd.org/psycopg/docs/install.html
+.. _wheel: http://pythonwheels.com/
+.. __: http://initd.org/psycopg/docs/install.html#install-from-source
 
 For any other resource (source code repository, bug tracker, mailing list)
 please check the `project homepage`__.
diff --git a/doc/src/install.rst b/doc/src/install.rst
index 0ff4693..a45b74c 100644
--- a/doc/src/install.rst
+++ b/doc/src/install.rst
@@ -30,112 +30,54 @@ The current `!psycopg2` implementation supports:
 .. __: https://github.com/mvantellingen/psycopg2-ctypes
 
 
-.. note::
-
-    `!psycopg2` usually depends at runtime on the libpq dynamic library.
-    However it can connect to PostgreSQL servers of any supported version,
-    independently of the version of the libpq used: just install the most
-    recent libpq version or the most practical, without trying to match it to
-    the version of the PostgreSQL server you will have to connect to.
-
-
-Installation
-============
-
-If possible, and usually it is, please :ref:`install Psycopg from a package
-<install-from-package>` available for your distribution or operating system.
-
-Compiling from source is a very easy task, however `!psycopg2` is a C
-extension module and as such it requires a few more things in place respect to
-a pure Python module. So, if you don't have experience compiling Python
-extension packages, *above all if you are a Windows or a Mac OS user*, please
-use a pre-compiled package and go straight to the :ref:`module usage <usage>`
-avoid bothering with the gory details.
-
-.. note::
-
-    Regardless of the way `!psycopg2` is installed, at runtime it will need to
-    use the libpq_ library. `!psycopg2` relies on the host OS to find the
-    library file (usually ``libpq.so`` or ``libpq.dll``): if the library is
-    installed in a standard location there is usually no problem; if the
-    library is in a non-standard location you will have to tell somehow
-    psycopg how to find it, which is OS-dependent (for instance setting a
-    suitable :envvar:`LD_LIBRARY_PATH` on Linux).
-
-
-
-.. _install-from-package:
-
-Install from a package
-----------------------
 
 .. index::
-    pair: Install; Linux
-
-**Linux**
-    Psycopg is available already packaged in many Linux distributions: look
-    for a package such as ``python-psycopg2`` using the package manager of
-    your choice.
-
-    On Debian, Ubuntu and other deb-based distributions you should just need::
-
-        sudo apt-get install python-psycopg2
-
-    to install the package with all its dependencies.
-
-
-.. index::
-    pair: Install; Mac OS X
+    single: Install; from PyPI
 
-**Mac OS X**
-    Psycopg is available as a `fink package`__ in the *unstable* tree: you may
-    install it with::
+Binary install from PyPI
+------------------------
 
-        fink install psycopg2-py27
+`!psycopg2` is `available on PyPI`__ in the form of wheel_ packages for the
+most common platform (Linux, OSX, Windows): this should make you able to
+install a binary version of the module including all the dependencies simply
+using::
 
-    .. __: http://pdb.finkproject.org/pdb/package.php/psycopg2-py27
+    pip install psycopg2
 
-    The library is also available on `MacPorts`__ try::
+Make sure to use an up-to-date version of :program:`pip` (you can upgrade it
+using something like ``pip install -U pip``)
 
-         sudo port install py27-psycopg2
+.. __: PyPI_
+.. _PyPI: https://pypi.python.org/pypi/psycopg2/
+.. _wheel: http://pythonwheels.com/
 
-    .. __: http://www.macports.org/
 
 
 .. index::
-    pair: Install; Windows
-
-**Microsoft Windows**
-    There are two options to install a precompiled `psycopg2` package under windows:
+    single: Install; from source
 
-    **Option 1:** Using `pip`__ (Included in python 2.7.9+ and python 3.4+)
-    and a binary wheel package.  Launch windows' command prompt (`cmd.exe`)
-    and execute the following command::
-    
-        pip install psycopg2
+.. _install-from-source:
 
-    .. __: https://pip.pypa.io/en/stable/installing/
+Install from source
+-------------------
 
-    **Option 2:** Jason Erickson maintains a packaged `Windows port of Psycopg`__ with
-    installation executable. Download. Double click. Done.
+.. _source-package:
 
-    .. __: http://www.stickpeople.com/projects/python/win-psycopg/
+You can download a copy of Psycopg source files from the `Psycopg download
+page`__ or from PyPI_.
 
+.. __: http://initd.org/psycopg/download/
 
 
-.. index::
-    single: Install; from source
 
-.. _install-from-source:
+.. _build-prerequisites:
 
-Install from source
--------------------
+Build prerequisites
+^^^^^^^^^^^^^^^^^^^
 
 These notes illustrate how to compile Psycopg on Linux. If you want to compile
 Psycopg on other platforms you may have to adjust some details accordingly.
 
-.. _requirements:
-
 Psycopg is a C wrapper to the libpq PostgreSQL client library. To install it
 from sources you will need:
 
@@ -158,9 +100,22 @@ from sources you will need:
   ``/usr/lib/postgresql/X.Y/bin/``) and add it to the :envvar:`PATH`::
 
     $ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH
-    
-  You only need it to compile and install `!psycopg2`, not for its regular
-  usage.
+
+  You only need :program:`pg_config` to compile `!psycopg2`, not for its
+  regular usage.
+
+
+Runtime requirements
+^^^^^^^^^^^^^^^^^^^^
+
+Unless you compile `!psycopg2` as a static library, or you install it from a
+self-contained wheel package, it will need the libpq_ library at runtime
+(usually distributed in a ``libpq.so`` or ``libpq.dll`` file).  `!psycopg2`
+relies on the host OS to find the library if the library is installed in a
+standard location there is usually no problem; if the library is in a
+non-standard location you will have to tell somehow Psycopg how to find it,
+which is OS-dependent (for instance setting a suitable
+:envvar:`LD_LIBRARY_PATH` on Linux).
 
 .. note::
 
@@ -170,40 +125,22 @@ from sources you will need:
     :program:`ldd`) if the module ``psycopg2/_psycopg.so`` is linked to the
     right ``libpq.so``.
 
+.. note::
 
+    Whatever version of libpq `!psycopg2` is compiled with, it will be
+    possible to connect to PostgreSQL servers of any supported version: just
+    install the most recent libpq version or the most practical, without
+    trying to match it to the version of the PostgreSQL server you will have
+    to connect to.
 
-.. index::
-    single: Install; from PyPI
-
-.. _package-manager:
-
-Use a Python package manager
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If the above requirements are satisfied, you can use :program:`easy_install`,
-:program:`pip` or whatever the Python package manager of the week::
-
-    $ pip install psycopg2
-
-Please refer to your package manager documentation about performing a local or
-global installation, :program:`virtualenv` (fully supported by recent Psycopg
-versions), using different Python versions and other nuances.
 
 
 .. index::
     single: setup.py
     single: setup.cfg
 
-.. _source-package:
-
-Use the source package
-^^^^^^^^^^^^^^^^^^^^^^
-
-You can download a copy of Psycopg source files from the `Psycopg download
-page`__. Once unpackaged, to compile and install the package you can run::
-
-    $ python setup.py build
-    $ sudo python setup.py install
+Non-standard builds
+^^^^^^^^^^^^^^^^^^^
 
 If you have less standard requirements such as:
 
@@ -215,43 +152,13 @@ then take a look at the ``setup.cfg`` file.
 
 Some of the options available in ``setup.cfg`` are also available as command
 line arguments of the ``build_ext`` sub-command. For instance you can specify
-an alternate :program:`pg_config` version using::
+an alternate :program:`pg_config` location using::
 
     $ python setup.py build_ext --pg-config /path/to/pg_config build
 
 Use ``python setup.py build_ext --help`` to get a list of the options
 supported.
 
-.. __: http://initd.org/psycopg/download/
-
-
-
-.. index::
-    single: tests
-
-.. _test-suite:
-
-Running the test suite
-^^^^^^^^^^^^^^^^^^^^^^
-
-The included ``Makefile`` allows to run all the tests included in the
-distribution. Just run::
-
-    make
-    make check
-
-The tests run against a database called ``psycopg2_test`` on UNIX socket and
-the standard port. You can configure a different database to run the test by
-setting the environment variables:
-
-- :envvar:`PSYCOPG2_TESTDB`
-- :envvar:`PSYCOPG2_TESTDB_HOST`
-- :envvar:`PSYCOPG2_TESTDB_PORT`
-- :envvar:`PSYCOPG2_TESTDB_USER`
-
-The database should already exist before running the tests.
-
-
 
 .. index::
     single: debug
@@ -260,7 +167,7 @@ The database should already exist before running the tests.
 .. _debug-build:
 
 Creating a debug build
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 In case of problems, Psycopg can be configured to emit detailed debug
 messages, which can be very useful for diagnostics and to report a bug. In
@@ -285,6 +192,32 @@ order to create a debug package:
 
 
 
+.. index::
+    single: tests
+
+.. _test-suite:
+
+Running the test suite
+----------------------
+
+Once `!psycopg2` is installed you can run the test suite to verify it is
+working correctly. You can run::
+
+    python -c "from psycopg2 import tests; tests.unittest.main(defaultTest='tests.test_suite')" --verbose
+
+The tests run against a database called ``psycopg2_test`` on UNIX socket and
+the standard port. You can configure a different database to run the test by
+setting the environment variables:
+
+- :envvar:`PSYCOPG2_TESTDB`
+- :envvar:`PSYCOPG2_TESTDB_HOST`
+- :envvar:`PSYCOPG2_TESTDB_PORT`
+- :envvar:`PSYCOPG2_TESTDB_USER`
+
+The database should already exist before running the tests.
+
+
+
 .. _other-problems:
 
 If you still have problems
@@ -292,7 +225,7 @@ If you still have problems
 
 Try the following. *In order:*
 
-- Read again the :ref:`requirements <requirements>`.
+- Read again the :ref:`build-prerequisites`.
 
 - Read the :ref:`FAQ <faq-compile>`.
 
@@ -306,4 +239,3 @@ Try the following. *In order:*
   :envvar:`ARCHFLAGS`. Especially useful from the Starbucks near you.
 
 .. __: http://mail.postgresql.org/mj/mj_wwwusr/domain=postgresql.org?func=lists-long-full&extra=psycopg
-