Installation and readme improvements

diff --git a/README.rst b/README.rst
index dd1635ae4b4f6fd404d6acd07201b11973828496..e64d72403b3a4b918562e8e08cd9ddd85ee001bf 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -3,42 +3,68 @@ psycopg3 -- PostgreSQL database adapter for Python
 
 psycopg3 is a modern implementation of a PostgreSQL adapter for Python.
 
-The package is split in different parts, with different requirements.
 
-- The pure python package only depends on the **libpq**, the PostgreSQL client
-  library. The code is in the ``psycopg3`` directory.
+Installation
+------------
 
-- The optional C optimization: in order to build it requires the **libpq-dev**
-  packages, a C compiler and Cython. The code is in the ``psycopg3_c``
-  directory.
+The library is still in a development stage and is not available on PyPI in
+the form of packages yet. You can install it directly `from the GitHub
+project`__::
 
+    $ pip install git+https://github.com/psycopg/psycopg3.git#subdirectory=psycopg3
+    $ python3
+    >>> import psycopg3
 
-Installation
-------------
+.. __: https://github.com/psycopg/psycopg3
 
-The library is still in early development stage. If you want to try it out you
-can install it from source using::
+You are required to have the ``libpq``, the PostgreSQL client library, already
+installed in the system before using ``psycopg3``. On Debian system you can
+obtain it by running::
 
-    git clone https://github.com/psycopg/psycopg3.git
-    cd psycopg3
-    python psycopg3/setup.py install    # for the base Python package
-    python psycopg3_c/setup.py install  # for the C extension module
+    sudo apt-get install libpq5
+
+Please check your system's documentation for information about installing the
+``libpq`` on your platform.
 
 
 Hacking
 -------
 
-You can create a local virtualenv and install there the dev and test
-requirements. Feel free to adapt the following recipe if you follow a
-different development pattern::
+In order to work on the ``psycopg3`` source code you should clone this
+repository::
+
+    git clone https://github.com/psycopg/psycopg3.git
+    cd psycopg3
+
+Please note that the repository contains the source code of several Python
+packages: that's why you don't see a ``setup.py`` here. The packages may have
+different requirements:
+
+- The ``psycopg3`` directory contains the pure python implementation of
+  ``psycopg3``. The package has only a runtime dependency on the ``libpq``,
+  the PostgreSQL client library, which should have been already installed in
+  your system.
+
+- The ``psycopg3_c`` directory contains an optimization module written in
+  C/Cython. In order to build it you will need a few development tools: please
+  look at `Local installation`__ in the docs for the details.
+
+  .. __: https://www.psycopg.org/psycopg3/docs/install.html#local-installation
+
+You can create a local virtualenv and install there the packages `in
+development mode`__, together with their development and testing
+requirements::
 
     python -m venv .venv
     source .venv/bin/activate
-    pip install -e ./psycopg3[dev,test]     # for the base Python pacakge
+    pip install -e ./psycopg3[dev,test]     # for the base Python package
     pip install -e ./psycopg3_c             # for the C extension module
 
-You can use tox to validate the code::
+.. __: https://pip.pypa.io/en/stable/reference/pip_install/#install-editable
+
+Now hack away! You can use tox to validate the code::
 
+    pip install tox
     tox -p4
 
 and to run the tests::
@@ -50,4 +76,5 @@ and to run the tests::
 
 Please look at the commands definitions in the ``tox.ini`` files if you want
 to run some of them interactively: the dependency should be already in your
-virtualenv.
+virtualenv. Feel free to adapt these recipes if you follow a different
+development pattern.

diff --git a/docs/install.rst b/docs/install.rst
index 45d631eaf23e000ec3368a01de532682e61e53e2..406678d89214806da107a8a5c22aa33be21d1769 100644 (file)
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -3,6 +3,26 @@
 Installation
 ============
 
+Installing the development state
+--------------------------------
+
+``psycopg3`` packages have not been released yet, but you can try it out
+already by installing it `from the GitHub project`__:
+
+.. code:: bash
+
+    $ pip install git+https://github.com/psycopg/psycopg3.git#subdirectory=psycopg3
+    $ python3
+    >>> import psycopg3
+
+.. __: https://github.com/psycopg/psycopg3
+
+
+.. _binary-install:
+
+Binary installation
+-------------------
+
 .. warning::
 
     `!psycopg3` is still in a development phase: packages haven't been
@@ -16,10 +36,8 @@ Installation
     The following is how it will be *supposed* to work, once it is released...
 
 
-Quick install
--------------
-
-The quickest way to start developing with psycopg3 is to run::
+The quickest way to start developing with psycopg3 is to install the binary
+packages by running::
 
     pip install psycopg3[binary]
 
@@ -29,22 +47,33 @@ The above package should work in most situations. It **will not work** in
 some though:
 
 - the ``binary`` package doesn't work on Alpine Linux;
-- the ``binary`` package is not advised in production.
+- you have a newly released Python or Mac Os X version for which binary
+  packages are not ready yet.
 
+In these case you should proceed to a :ref:`local installation
+<local-installation>` or a :ref:`pure Python installation
+<pure-python-installation>`.
 
-Proper installation
--------------------
+.. seealso::
 
-.. admonition:: TODO
+    Did ``psycopg3`` install ok? Great! You can now move on to the :ref:`basic
+    module usage <module-usage>` to learn how it works.
 
-    "proper" is scary... bettern name?
+    You can come back here if you the above method didn't work and you need a
+    way to install ``psycopg3`` past the basic one.
 
-Proper install means obtaining a performing and maintainable library. The
-library will include a performing C module and will be bound to the system
-libpq, so that system upgrade of libraries will upgrade the library used by
-``psycopg3``.
 
-In order to perform a "proper" installation you need some prerequisites:
+.. _local-installation:
+
+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 ``psycopg3`` too.
+
+In order to perform a local installation you need some prerequisites:
 
 - a C compiler,
 - Python development headers (e.g. the python3-dev package).
@@ -53,13 +82,15 @@ In order to perform a "proper" installation you need some prerequisites:
 
 You **must be able** to troubleshoot an extension build, for instance you must
 be able to read your compiler's error message. If you are not, please don't
-try this and follow the `quick install`_ instead.
+try this and follow the `binary installation`_ instead.
 
 If your build prerequisites are in place you can run::
 
     pip install psycopg3[c]
 
 
+.. _pure-python-installation:
+
 Pure Python installation
 ------------------------
 
@@ -78,8 +109,8 @@ need::
 
     sudo apt-get install libpq5
 
-If you are not able to fulfill this requirement please follow the `quick
-install`_.
+If you are not able to fulfill this requirement please follow the `binary
+installation`_.
 
 
 

diff --git a/docs/usage.rst b/docs/usage.rst
index ede4a39c8aa16dc3022345f7bc1e394ba1045e12..65a95055839c1658ae5b3261a5c5b9b3489e04f4 100644 (file)
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -1,5 +1,7 @@
 .. currentmodule:: psycopg3
 
+.. _module-usage:
+
 Basic module usage
 ==================