Improvements of the docs.

docs/src/quickstart/build.rst

@@ -4,24 +4,34 @@ Building Cython code
 Cython code must, unlike Python, be compiled. This happens in two stages:
 
  - A ``.pyx`` file is compiled by Cython to a ``.c`` file, containing
-   the code of a Python extension module
+   the code of a Python extension module.
  - The ``.c`` file is compiled by a C compiler to
    a ``.so`` file (or ``.pyd`` on Windows) which can be
    ``import``-ed directly into a Python session.
+   Distutils or setuptools take care of this part.
+   Although Cython can call them for you in certain cases.
+
+To understand fully the Cython + distutils/setuptools build process,
+one may want to read more about
+`distributing Python modules <https://docs.python.org/3/distributing/index.html>`_.
 
 There are several ways to build Cython code:
 
- - Write a distutils ``setup.py``. This is the normal and recommended way.
+ - Write a distutils/setuptools ``setup.py``. This is the normal and recommended way.
  - Use ``pyximport``, importing Cython ``.pyx`` files as if they
    were ``.py`` files (using distutils to compile and build in the background).
+   This method is easier than writing a ``setup.py``, but isn't very flexible.
+   So you'll need to write a ``setup.py`` if you want, for example, certain compilations options.
  - Run the ``cython`` command-line utility manually to produce the ``.c`` file
    from the ``.pyx`` file, then manually compiling the ``.c`` file into a shared
    object library or DLL suitable for import from Python.
    (These manual steps are mostly for debugging and experimentation.)
  - Use the [Jupyter]_ notebook or the [Sage]_ notebook,
    both of which allow Cython code inline.
+   This is the easiest way to get started writting Cython code and run it.
 
-Currently, distutils is the most common way Cython files are built and distributed. The other methods are described in more detail in the :ref:`compilation` section of the reference manual.
+Currently, using distutils or setuptools is the most common way Cython files are built and distributed.
+The other methods are described in more detail in the :ref:`compilation` section of the reference manual.
 
 
 Building a Cython module using distutils
@@ -59,8 +69,8 @@ use pip:
     (venv)$ pip install jupyter
     (venv)$ jupyter notebook
 
-To enable support for Cython compilation, install Cython and load the
-``Cython`` extension from within the Jupyter notebook::
+To enable support for Cython compilation, install Cython as described in :ref:`the installation guide<install>`
+and load the ``Cython`` extension from within the Jupyter notebook::
 
     %load_ext Cython
 

docs/src/quickstart/install.rst

+.. _install:
+
 Installing Cython
 =================