Move compilation block to before directives, add note about cython.inline.

docs/src/reference/compilation.rst

@@ -13,9 +13,128 @@ Cython code, unlike Python, must be compiled.  This happens in two stages:
   * The ``.c`` file is compiled by a C compiler to a ``.so`` file (or a
     ``.pyd`` file on Windows)
 
+
+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
+===============================
+
+Run the Cython compiler command with your options and list of ``.pyx``
+files to generate.  For example::
+
+    $ cython -a yourmod.pyx
+
+This creates a ``yourmod.c`` file, and the -a switch produces a
+generated html file.  Pass the ``-h`` flag for a complete list of
+supported flags.
+
+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::
+
+    $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing -I/usr/include/python2.5 -o yourmod.so yourmod.c
+
+[``gcc`` will need to have paths to your included header files and
+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``
+============================
+
+First, make sure that ``distutils`` package is installed in your
+system.  The following assumes a Cython file to be compiled called
+*hello.pyx*.  Now, create a ``setup.py`` script::
+
+    from distutils.core import setup
+    from distutils.extension import Extension
+    from Cython.Distutils import build_ext
+
+    ext_modules = [Extension("spam", ["spam.pyx"]),
+                   Extension("ham", ["ham.pyx"])]
+    # You can add directives for each extension too
+    # by attaching the `pyrex_directives`
+    for e in ext modules:
+        e.pyrex_directives = {"boundscheck": False}
+    setup(
+        name = "My hello app",
+        cmdclass = {"build_ext": build_ext},
+        ext_modules = ext_modules
+    )
+
+Run the command ``python setup.py build_ext --inplace`` in your
+system's command shell and you are done.  Import your new extension
+module into your python shell or script as normal.
+
+Cython provides utility code to automatically generate lists of
+Extension objects from ```.pyx`` files, so one can write::
+
+    from distutils.core import setup
+    from Cython.Build import cythonize
+
+    setup(
+        name = "My hello app",
+        ext_modules = cythonize("*.pyx"),
+    )
+
+to compile all ``.pyx`` files in a given directory.
+The ``cythonize`` command also allows for multi-threaded compilation and
+dependency resolution.
+
+Compiling with ``pyximport``
+=============================
+
+For generating Cython code right in your pure python module just type::
+
+    >>> import pyximport; pyximport.install()
+    >>> import helloworld  
+    Hello World
+
+This allows you to automatically run Cython on every ``.pyx`` that
+Python is trying to import.  You should use this for simple Cython
+builds only where no extra C libraries and no special building setup
+is needed.
+
+In the case that Cython fails to compile a Python module, *pyximport*
+will fall back to loading the source modules instead.
+
+It is also possible to compile new ``.py`` modules that are being
+imported (including the standard library and installed packages).  For
+using this feature, just tell that to ``pyximport``::
+
+    >>> pyximport.install(pyimport = True)
+
+Compiling with ``cython.inline``
+=============================
+
+One can also compile Cython in a fashion similar to SciPy's ``weave.inline``.
+For example::
+
+    >>> import cython
+    >>> def f(a):
+    ...     ret = cython.inline("return a+b", b=3)
+    ... 
+
+Unbound variables are automatically pulled from the surrounding local
+and global scopes, and the result of the compilation is cached for
+efficient re-use.
+
+Compiling with Sage
+===================
+
+The Sage notebook allows transparently editing and compiling Cython
+code simply by typing ``%cython`` at the top of a cell and evaluate
+it. Variables and functions defined in a Cython cell are imported into the
+running session.  Please check `Sage documentation
+<http://www.sagemath.org/doc/>`_ for details.
+
 You can tailor the behavior of the Cython compiler by specifying the
 directives below.
 
+====================
 Compiler directives
 ====================
 
@@ -112,6 +231,7 @@ Locally
 For local blocks, you need to cimport the special builtin ``cython``
 module::
 
+    #!python
     cimport cython
 
 Then you can use the directives either as decorators or in a with
@@ -127,90 +247,3 @@ statement, like this::
 .. Warning:: These two methods of setting directives are **not**
     affected by overriding the directive on the command-line using the
     -X option.
-
-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
-===============================
-
-Run the Cython compiler command with your options and list of ``.pyx``
-files to generate.  For example::
-
-    $ cython -a yourmod.pyx
-
-This creates a ``yourmod.c`` file, and the -a switch produces a
-generated html file.  Pass the ``-h`` flag for a complete list of
-supported flags.
-
-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::
-
-    $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing -I/usr/include/python2.5 -o yourmod.so yourmod.c
-
-[``gcc`` will need to have paths to your included header files and
-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``
-============================
-
-First, make sure that ``distutils`` package is installed in your
-system.  The following assumes a Cython file to be compiled called
-*hello.pyx*.  Now, create a ``setup.py`` script::
-
-    from distutils.core import setup
-    from distutils.extension import Extension
-    from Cython.Distutils import build_ext
-
-    ext_modules = [Extension("spam", ["spam.pyx"]),
-                   Extension("ham", ["ham.pyx"])]
-    # You can add directives for each extension too
-    # by attaching the `pyrex_directives`
-    for e in ext modules:
-        e.pyrex_directives = {"boundscheck": False}
-    setup(
-        name = ’My hello app’,
-        cmdclass = {’build_ext’: build_ext},
-        ext_modules = ext_modules
-    )
-
-Run the command ``python setup.py build_ext --inplace`` in your
-system's command shell and you are done.  Import your new extension
-module into your python shell or script as normal.
-
-Compiling with ``pyximport``
-=============================
-
-For generating Cython code right in your pure python module just type::
-
-    >>> import pyximport; pyximport.install()
-    >>> import helloworld  
-    Hello World
-
-This allows you to automatically run Cython on every ``.pyx`` that
-Python is trying to import.  You should use this for simple Cython
-builds only where no extra C libraries and no special building setup
-is needed.
-
-In the case that Cython fails to compile a Python module, *pyximport*
-will fall back to loading the source modules instead.
-
-It is also possible to compile new ``.py`` modules that are being
-imported (including the standard library and installed packages).  For
-using this feature, just tell that to ``pyximport``::
-
-    >>> pyximport.install(pyimport = True)
-
-Compiling with Sage
-===================
-
-The Sage notebook allows transparently editing and compiling Cython
-code simply by typing ``%cython`` at the top of a cell and evaluate
-it. Variables and functions defined in a Cython cell imported into the
-running session.  Please check `Sage documentation
-<http://www.sagemath.org/doc/>`_ for details.