move some build docs from user guide to reference to reduce redundancy

--HG--
extra : transplant_source : a%5D%AC%9A%18%7B%DD%94%7D%20%22%CC%CB%D39%AE%10%C0%8FC

docs/src/reference/compilation.rst

@@ -43,6 +43,7 @@ paths to libraries you need to link with]
 A ``yourmod.so`` file is now in the same directory and your module,
 ``yourmod``, is available for you to import as you normally would.
 
+
 Compiling with ``distutils``
 ============================
 
@@ -67,6 +68,10 @@ The ``cythonize`` command also allows for multi-threaded compilation and
 dependency resolution.  Recompilation will be skipped if the target file
 is up to date with its main source file and dependencies.
 
+
+Configuring the C-Build
+------------------------
+
 If you have include files in non-standard places you can pass an
 ``include_path`` parameter to ``cythonize``::
 
@@ -78,9 +83,15 @@ If you have include files in non-standard places you can pass an
         ext_modules = cythonize("src/*.pyx", include_path = [...]),
     )
 
-If you need to specify compiler options, libraries to link with or other linker
-options you will need to create ``Extension`` instances manually (note
-that glob syntax can still be used to specify multiple extensions in one line)::
+Often, Python packages that offer a C-level API provide a way to find
+the necessary include files, e.g. for NumPy::
+
+    include_path = [numpy.get_include()]
+
+If you need to specify compiler options, libraries to link with or other
+linker options you will need to create ``Extension`` instances manually
+(note that glob syntax can still be used to specify multiple extensions
+in one line)::
 
     from distutils.core import setup
     from distutils.extension import Extension
@@ -109,6 +120,79 @@ If your options are static (for example you do not need to call a tool like
     # distutils: libraries = spam eggs
     # distutils: include_dirs = /opt/food/include
 
+If you have some C files that have been wrapped with Cython and you want to
+compile them into your extension, you can define the distutils ``sources``
+parameter::
+
+    # distutils: sources = helper.c, another_helper.c
+
+Note that these sources are added to the list of sources of the current
+extension module.  Spelling this out in the :file:`setup.py` file looks
+as follows::
+
+    from distutils.core import setup
+    from Cython.Build import cythonize
+    from distutils.extension import Extension
+
+    sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
+
+    extensions = [Extension("example", sourcefiles)]
+
+    setup(
+        ext_modules = cythonize(extensions)
+    )
+
+The :class:`Extension` class takes many options, and a fuller explanation can
+be found in the `distutils documentation`_. Some useful options to know about
+are ``include_dirs``, ``libraries``, and ``library_dirs`` which specify where
+to find the ``.h`` and library files when linking to external libraries.
+
+.. _distutils documentation: http://docs.python.org/extending/building.html
+
+
+Distributing Cython modules
+----------------------------
+
+It is strongly recommended that you distribute the generated ``.c`` files as well
+as your Cython sources, so that users can install your module without needing
+to have Cython available.
+
+It is also recommended that Cython compilation not be enabled by default in the
+version you distribute. Even if the user has Cython installed, he/she probably
+doesn't want to use it just to install your module. Also, the installed version
+may not be the same one you used, and may not compile your sources correctly.
+
+This simply means that the :file:`setup.py` file that you ship with will just
+be a normal distutils file on the generated `.c` files, for the basic example
+we would have instead::
+
+    from distutils.core import setup
+    from distutils.extension import Extension
+
+    setup(
+        ext_modules = [Extension("example", ["example.c"])]
+    )
+
+This is easy to combine with :func:`cythonize` by changing the file extension
+of the extension module sources::
+
+    from distutils.core import setup
+    from distutils.extension import Extension
+
+    USE_CYTHON = ...   # command line option, try-import, ...
+
+    ext = '.pyx' if USE_CYTHON else '.c'
+
+    extensions = [Extension("example", ["example"+ext])]
+
+    if USE_CYTHON:
+        from Cython.Build import cythonize
+        extensions = cythonize(extensions)
+
+    setup(
+        ext_modules = extensions
+    )
+
 
 Compiling with ``pyximport``
 =============================

docs/src/userguide/source_files_and_compilation.rst

@@ -55,37 +55,6 @@ current directory use:
     $ python setup.py build_ext --inplace
 
 
-Cython Files Depending on C Files
-===================================
-
-When you have come C files that have been wrapped with cython and you want to
-compile them into your extension the basic :file:`setup.py` file to do this
-would be::
-
-    from distutils.core import setup
-    from Cython.Build import cythonize
-    from distutils.extension import Extension
-
-    sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
-
-    extensions = [Extension("example", sourcefiles)]
-
-    setup(
-        ext_modules = cythonize(extensions)
-    )
-
-Notice that the files have been given a name, this is not necessary, but it
-makes the file easier to format if the list gets long.
-
-The :class:`Extension` class takes many options, and a fuller explanation can
-be found in the `distutils documentation`_. Some useful options to know about 
-are ``include_dirs``, ``libraries``, and ``library_dirs`` which specify where
-to find the ``.h`` and library files when linking to external libraries. 
-
-.. _distutils documentation: http://docs.python.org/extending/building.html
-
-
-
 Multiple Cython Files in a Package
 ===================================
 
@@ -106,50 +75,6 @@ them through :func:`cythonize`::
     )
 
 
-Distributing Cython modules
-============================
-
-It is strongly recommended that you distribute the generated ``.c`` files as well
-as your Cython sources, so that users can install your module without needing
-to have Cython available.
-
-It is also recommended that Cython compilation not be enabled by default in the
-version you distribute. Even if the user has Cython installed, he/she probably
-doesn't want to use it just to install your module. Also, the installed version
-may not be the same one you used, and may not compile your sources correctly.
-
-This simply means that the :file:`setup.py` file that you ship with will just
-be a normal distutils file on the generated `.c` files, for the basic example
-we would have instead::
-
-    from distutils.core import setup
-    from distutils.extension import Extension
-
-    setup(
-        ext_modules = [Extension("example", ["example.c"])]
-    ) 
-
-This is easy to combine with :func:`cythonize` by changing the file extension
-of the extension module sources::
-
-    from distutils.core import setup
-    from distutils.extension import Extension
-
-    USE_CYTHON = ...   # command line option, try-import, ...
-
-    ext = '.pyx' if USE_CYTHON else '.c'
-
-    extensions = [Extension("example", ["example"+ext])]
-
-    if USE_CYTHON:
-        from Cython.Build import cythonize
-        extensions = cythonize(extensions)
-
-    setup(
-        ext_modules = extensions
-    )
-
-
 .. _pyximport:
 
 Pyximport