Merge pull request #2480 from gabrieldemarmiesse/move_compilation_1

Moving compilation from the reference guide to the userguide Part 1

docs/src/userguide/source_files_and_compilation.rst

@@ -12,8 +12,23 @@ Cython source file names consist of the name of the module followed by a
 ``.pyx`` extension, for example a module called primes would have a source
 file named :file:`primes.pyx`.
 
+Cython code, unlike Python, must be compiled.  This happens in two stages:
+
+  * A ``.pyx`` file is compiled by Cython to a ``.c`` file.
+
+  * The ``.c`` file is compiled by a C compiler to a ``.so`` file (or a
+    ``.pyd`` file on Windows)
+
 Once you have written your ``.pyx`` file, there are a couple of ways of turning it
-into an extension module. One way is to compile it manually with the Cython
+into an extension module.
+
+The following sub-sections describe several ways to build your
+extension modules, and how to pass directives to the Cython compiler.
+
+Compiling from the command line
+===============================
+
+One way is to compile it manually with the Cython
 compiler, e.g.:
 
 .. sourcecode:: text