Changed some filenames.

Demos/Readme_demos.rst → Demos/README.rst

@@ -1,25 +1,25 @@
-* To run demos do::
+To run demos do::
 
     cd Demos
     make test
 
-  which runs run_primes.py, run_numeric_demo.py, run_spam.py,
-  integrate_timing.py, callback/runcheese.py and embed/embedded
+which runs ``run_primes.py``, ``run_numeric_demo.py``, ``run_spam.py``,
+``integrate_timing.py``, ``callback/runcheese.py`` and ``embed/embedded``
 
-* For other demos::
+For other demos::
 
     cd libraries
     python setup.py build_ext --inplace
     python -c 'import call_mymath;print(call_mymath.call_sinc(1))'
 
-  To run one of the benchmarks for 10 iterations to compare cython and python timings::
+To run one of the benchmarks for 10 iterations to compare cython and python timings::
 
     cd benchmarks
     python setup.py build_ext --inplace
     python nqueens.py -n 10
     python -c 'import nqueens;print(nqueens.test_n_queens(10))'
 
-  To demo cython/bin/cython_freeze::
+To demo ``cython/bin/cython_freeze``::
 
     make
     ./nCr 10 5

Demos/callback/README.txt → Demos/callback/README.rst

@@ -2,11 +2,11 @@ This example demonstrates how you can wrap a C API
 that has a callback interface, so that you can
 pass Python functions to it as callbacks.
 
-The files cheesefinder.h and cheesefinder.c
+The files ``cheesefinder.h`` and ``cheesefinder.c``
 represent the C library to be wrapped.
 
-The file cheese.pyx is the Pyrex module
+The file ``cheese.pyx`` is the Cython module
 which wraps it.
 
-The file run_cheese.py demonstrates how to
+The file ``run_cheese.py`` demonstrates how to
 call the wrapper.

Demos/embed/README → Demos/embed/README.rst

@@ -2,4 +2,4 @@ This example demonstrates how Cython-generated code
 can be called directly from a main program written in C.
 
 The Windows makefiles were contributed by
-Duncan Booth <[email protected]>.
+Duncan Booth: [email protected].

Demos/freeze/README.txt → Demos/freeze/README.rst

@@ -1,13 +1,14 @@
 NAME
 ====
 
-cython_freeze - create a C file for embedding Cython modules
+**cython_freeze** - create a C file for embedding Cython modules
 
 
 SYNOPSIS
 ========
+::
 
-cython_freeze [-o outfile] [-p] module [...]
+    cython_freeze [-o outfile] [-p] module [...]
 
 
 DESCRIPTION
@@ -32,21 +33,20 @@ modules, but it requires another C source file to be created.
 
 OPTIONS
 =======
+::
 
--o FILE, --outfile=FILE   write output to FILE instead of standard output
--p, --pymain              do not automatically run the first module as __main__
+    -o FILE, --outfile=FILE   write output to FILE instead of standard output
+    -p, --pymain              do not automatically run the first module as __main__
 
 
 EXAMPLE
 =======
 
-In the Demos/freeze directory, there exist two Cython modules:
+In the ``Demos/freeze`` directory, there exist two Cython modules:
 
-lcmath.pyx
-    A module that interfaces with the -lm library.
+* ``lcmath.pyx``: A module that interfaces with the -lm library.
 
-combinatorics.pyx
-    A module that implements n-choose-r using lcmath.
+* ``combinatorics.pyx``: A module that implements n-choose-r using lcmath.
 
 Both modules have the Python idiom ``if __name__ == "__main__"``, which only
 execute if that module is the "main" module.  If run as main, lcmath prints the

bin/cython_freeze

@@ -3,7 +3,7 @@
 Create a C file for embedding one or more Cython source files.
 Requires Cython 0.11.2 (or perhaps newer).
 
-See Demos/freeze/README.txt for more details.
+See Demos/freeze/README.rst for more details.
 """
 from __future__ import print_function
 

pyximport/README.rst

@@ -0,0 +1,71 @@
+Pyximport
+=========
+
+Cython is a compiler. Therefore it is natural that people tend to go
+through an edit/compile/test cycle with Cython modules. But my personal
+opinion is that one of the deep insights in Python's implementation is
+that a language can be compiled (Python modules are compiled to .pyc)
+files and hide that compilation process from the end-user so that they
+do not have to worry about it. Pyximport does this for Cython modules.
+For instance if you write a Cython module called ``foo.pyx``, with
+Pyximport you can import it in a regular Python module like this::
+
+    import pyximport; pyximport.install()
+    import foo
+
+Doing so will result in the compilation of ``foo.pyx`` (with appropriate
+exceptions if it has an error in it).
+
+If you would always like to import Cython files without building them
+specially, you can also add the first line above to your sitecustomize.py.
+That will install the hook every time you run Python. Then you can use
+Cython modules just with simple import statements. I like to test my
+Cython modules like this::
+
+    python -c "import foo"
+
+See help(pyximport.install) to learn its options for controlling the
+default behavior of ``import`` and ``reload``.
+
+Dependency Handling
+-------------------
+
+In Pyximport 1.1 it is possible to declare that your module depends on
+multiple files, (likely ``.h`` and ``.pxd`` files). If your Cython module is
+named ``foo`` and thus has the filename ``foo.pyx`` then you should make
+another file in the same directory called ``foo.pyxdep``. The
+``modname.pyxdep`` file can be a list of filenames or ``globs`` (like
+``*.pxd`` or ``include/*.h``). Each filename or glob must be on a separate
+line. Pyximport will check the file date for each of those files before
+deciding whether to rebuild the module. In order to keep track of the
+fact that the dependency has been handled, Pyximport updates the
+modification time of your ``.pyx`` source file. Future versions may do
+something more sophisticated like informing distutils of the
+dependencies directly.
+
+Limitations
+-----------
+Pyximport does not give you any control over how your Cython file is
+compiled. Usually the defaults are fine. You might run into problems if
+you wanted to write your program in half-C, half-Cython and build them
+into a single library. Pyximport 1.2 will probably do this.
+
+Pyximport does not hide the Distutils/GCC warnings and errors generated
+by the import process. Arguably this will give you better feedback if
+something went wrong and why. And if nothing went wrong it will give you
+the warm fuzzy that pyximport really did rebuild your module as it was
+supposed to.
+
+For further thought and discussion
+----------------------------------
+
+``setup.py install`` does not modify ``sitecustomize.py`` for you. Should it?
+Modifying Python's "standard interpreter" behaviour may be more than
+most people expect of a package they install..
+
+Pyximport puts your ``.c`` file beside your ``.pyx`` file (analogous to
+``.pyc`` beside ``.py``). But it puts the platform-specific binary in a
+build directory as per normal for Distutils. If I could wave a magic
+wand and get Cython or distutils or whoever to put the build directory I
+might do it but not necessarily: having it at the top level is VERY
+HELPFUL for debugging Cython problems.