README.rst: add installation instructions for cython module

README.rst

@@ -58,6 +58,59 @@ statistics between calls by providing your own report dictionary:
         fonts_to_quadratic([font], stats=stats)
     # "stats" will report combined statistics for both fonts
 
+Installation
+------------
+
+You can install/upgrade cu2qu using pip, like any other Python package.
+
+.. code:: sh
+
+    $ pip install --upgrade cu2qu
+
+This will download the latest stable version available from the Python
+Package Index (PyPI).
+
+If you wish to modify the sources in-place, you can clone the git repository
+from Github and install in ``--editable`` (or ``-e``) mode:
+
+.. code:: sh
+
+    $ git clone https://github.com/googlei18n/cu2qu
+    $ cd cu2qu
+    $ pip install --editable .
+
+Optionally, you can build an optimized version of cu2qu which uses Cython_
+to compile Python to C. The extension module thus created is *more than
+twice as fast* than its pure-Python equivalent.
+
+When installing cu2qu from PyPI using pip, as long as you have a C compiler
+available, the cu2qu setup script will automatically attempt to build a
+C/Python extension module. If the compilation fails for any reasons, an error
+is printed and cu2qu is be installed as pure-Python, without the optimized
+extension.
+
+If you have cloned the git repository, the C source files are not present and
+need to be regenerated. To do that, you need to install the latest Cython
+(as usual, ``pip install -U cython``), and then use the global option
+``--with-cython`` when invoking the ``setup.py`` script. You can also export
+a ``CU2QU_WITH_CYTYON=1`` environment variable if you prefer.
+
+For example, to build the cu2qu extension module in-place (i.e. in the same
+source directory):
+
+.. code:: sh
+
+    $ python setup.py --with-cython build_ext --inplace
+
+You can also pass ``--global-option`` when installing with pip from a local
+source checkout, like so:
+
+.. code:: sh
+
+    $ pip install --global-option="--with-cython" -e .
+
+
+.. _Cython: https://github.com/cython/cython
 .. |Build Status| image:: https://travis-ci.org/googlei18n/cu2qu.svg
    :target: https://travis-ci.org/googlei18n/cu2qu
 .. |PyPI Version| image:: https://img.shields.io/pypi/v/cu2qu.svg