A first restructuration of Compilation section.

docs/src/reference/compilation.rst

@@ -6,49 +6,48 @@
 Compilation
 ***********
 
-* Cython code, unlike Python, must be compiled.
-* This happens in two stages:
+Cython code, unlike Python, must be compiled.  This happens in two stages:
 
   * A ``.pyx`` file is compiles by Cython to a ``.c`` file.
- * The ``.c`` file is compiled by a C comiler to a ``.so`` file (or a ``.pyd`` file on Windows)
 
-* The following sub-sections describe several ways to build your extension modules.
+  * The ``.c`` file is compiled by a C comiler to a ``.so`` file (or a
+    ``.pyd`` file on Windows)
 
-.. note:: The ``-a`` option
-
-    * Using the Cython compiler with the ``-a`` option will produce a really nice HTML file of the Cython generated ``.c`` code.
-    * Double clicking on the highlighted sections will expand the code to reveal what Cython has actually generated for you.
-    * This is very useful for understanding, optimizing or debugging your module.
+The following sub-sections describe several ways to build your
+extension modules.
 
 =====================
 From the Command Line
 =====================
 
-* Run the Cython compiler command with your options and list of ``.pyx`` files to generate::
+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)
-* Compiling your ``.c`` files will vary depending on your operating system.
-
- * Python documentation for writing extension modules should have some details for your system.
+This creates a ``yourmod.c`` file (and the -a switch produces a
+generated html file).
 
-* Here we give an example on a Linux system::
+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.
- * Your module, ``yourmod`` is available for you to import as you normally would.
+[``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.
 
 =========
 Distutils
 =========
 
-* Ensure Distutils is installed in your system.
-* The following assumes a Cython file to be compiled called *hello.pyx*.
-* Create a ``setup.py`` script::
+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
@@ -62,78 +61,40 @@ Distutils
         ext_modules = ext_modules
     )
 
-* Run the command ``python setup.py build_ext --inplace`` in your system's command shell.
-* Your done.. import your new extension module into your python shell or script as normal.
-
-=====
-SCons
-=====
-
-to be completed...
+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.
 
 =========
 Pyximport
 =========
 
-* For generating Cython code right in your pure python modulce::
+For generating Cython code right in your pure python module just type::
 
     >>> import pyximport; pyximport.install()
     >>> import helloworld  
     Hello World
 
-* Use for simple Cython builds only.
-
- * No extra C libraries.
- * No special build setup needed.
+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.
 
-* Also has experimental compilation support for normal Python modules.
+In the case that Cython fails to compile a Python module, *pyximport*
+will fall back to loading the source modules instead.
 
- * Allows you to automatically run Cython on every ``.pyx`` and ``.py`` module that Python imports.
-
-  * This includes the standard library and installed packages.
-  * In the case that Cython fails to compile a Python module, *pyximport* will fall back to loading the source modules instead.
-
-* The ``.py`` import mechanism is installed like this::
+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)
 
-
-.. note:: Authors
-
-    Paul Prescod, Stefan Behnal
-
 ====
 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 func-
-tions defined in a Cython cell imported into the run-
-ning session.
-
-.. todo:: Provide a link to Sage docs
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+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.