Document cythonize usage for command line compilation.

Closes #2012.

docs/src/reference/compilation.rst

@@ -21,28 +21,43 @@ extension modules, and how to pass directives to the Cython compiler.
 Compiling from the command line
 ===============================
 
-Run the Cython compiler command with your options and list of ``.pyx``
-files to generate.  For example::
+Run the ``cythonize`` compiler command with your options and list of
+``.pyx`` files to generate.  For example::
 
-    $ cython -a yourmod.pyx
+    $ cythonize -a -i yourmod.pyx
 
-This creates a ``yourmod.c`` file, and the ``-a`` switch produces an
-annotated html file of the source code.  Pass the ``-h`` flag for a
-complete list of supported flags.
+This creates a ``yourmod.c`` file (or ``yourmod.cpp`` in C++ mode), compiles it,
+and puts the resulting extension module (``.so`` or ``.pyd``, depending on your
+platform) next to the source file for direct import (``-i`` builds "in place").
+The ``-a`` switch additionally produces an annotated html file of the source code.
 
-Compiling your ``.c`` files will vary depending on your operating
-system.  Python documentation for writing extension modules should
-have some details for your system.  Here we give an example on a Linux
-system::
+The ``cythonize`` command accepts multiple source files and glob patterns like
+``**/*.pyx`` as argument and also understands the common ``-j`` option for
+running multiple parallel build jobs.  When called without further options, it
+will only translate the source files to ``.c`` or ``.cpp`` files.  Pass the
+``-h`` flag for a complete list of supported options.
 
-    $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing \
-          -I/usr/include/python2.7 -o yourmod.so yourmod.c
+There is also a simpler command line tool named ``cython`` which only invokes
+the source code translator.
 
-[``gcc`` will need to have paths to your included header files and
-paths to libraries you need to link with]
+In the case of manual compilation, how to compile your ``.c`` files will vary
+depending on your operating system and compiler.  The Python documentation for
+writing extension modules should have some details for your system.  On a Linux
+system, for example, it might look similar to this::
 
-A ``yourmod.so`` file is now in the same directory and your module,
-``yourmod``, is available for you to import as you normally would.
+    $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing \
+          -I/usr/include/python3.5 -o yourmod.so yourmod.c
+
+(``gcc`` will need to have paths to your included header files and paths
+to libraries you want to link with.)
+
+After compilation, a ``yourmod.so`` file is written into the target directory
+and your module, ``yourmod``, is available for you to import as with any other
+Python module.  Note that if you are not relying on ``cythonize`` or distutils,
+you will not automatically benefit from the platform specific file extension
+that CPython generates for disambiguation, such as
+``yourmod.cpython-35m-x86_64-linux-gnu.so`` on a regular 64bit Linux installation
+of CPython 3.5.
 
 
 Compiling with ``distutils``