Fixed javascript suffix issue that broke search. Added pyximport to...

Fixed javascript suffix issue that broke search. Added pyximport to compilation docs. Removed module and index links.

conf.py

@@ -32,7 +32,7 @@ import cython_highlighting
 extensions = ['ipython_console_highlighting', 'cython_highlighting']
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['.templates']
+templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -42,7 +42,7 @@ master_doc = 'index'
 
 # General substitutions.
 project = 'Cython'
-copyright = '2008, Stefan Behnel, Robert Bradshaw, William Stein, Gary Furnish, Dag Seljebotn, Gabriel Gellner, Greg Ewing'
+copyright = '2008, Stefan Behnel, Robert Bradshaw, Grew Ewing, William Stein, Gary Furnish, Dag Seljebotn, Gabriel Gellner'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
@@ -50,7 +50,7 @@ copyright = '2008, Stefan Behnel, Robert Bradshaw, William Stein, Gary Furnish,
 # The short X.Y version.
 version = '0.9.8.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.9.8.1'
+release = '0.9.8.1.1'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -79,6 +79,9 @@ pygments_style = 'sphinx'
 # Options for HTML output
 # -----------------------
 
+# suffix for generated files
+html_file_suffix = '.html'
+
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
@@ -114,7 +117,10 @@ html_favicon = '_static/favicon.ico'
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_use_modindex = True
+html_use_modindex = False 
+
+# Don't generate and index
+html_use_index = False
 
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True

docs/source_files_and_compilation.rst

@@ -102,3 +102,87 @@ we would have instead::
         ext_modules = [Extension("example", ["example.c"])]
     ) 
 
+
+.. _pyximport:
+
+Pyximport
+===========
+
+.. TODO add some text about how this is Paul Prescods code. Also change the
+   tone to be more universal (i.e. remove all the I statements)
+
+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 :file:`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 :file:`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 the first line above to your :file:`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"
+
+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 :file:`foo.pyx` then you should make
+another file in the same directory called :file:`foo.pyxdep`. The
+:file:`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
+------------------------------------
+
+I don't think that Python's :func:`reload` will do anything for changed
+``.so``'s on some (all?) platforms. It would require some (easy)
+experimentation that I haven't gotten around to. But reload is rarely used in
+applications outside of the Python interactive interpreter and certainly not
+used much for C extension modules. Info about Windows
+`<http://mail.python.org/pipermail/python-list/2001-July/053798.html>`_
+
+``setup.py install`` does not modify :file:`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.
+

docs/tutorial.rst

@@ -65,6 +65,10 @@ Congratulations! You now know how to build a Cython extension. But So Far
 this example doesn't really give a feeling why one would ever want to use Cython, so
 lets create a more realistic example.
 
+:mod:`pyximport`: Cython Compilation the Easy Way
+==================================================
+
+
 Fibonacci Fun
 ==============
 

examples/tutorial/great_circle/c1.pyx

+import math
+
+def great_circle(lon1, lat1, lon2, lat2):
+    radius = 3956 # miles
+    x = math.pi/180.0
+
+    a = (90.0 - lat1)*x
+    b = (90.0 - lat2)*x
+    theta = (lon2 - lon1)*x
+    c = math.acos(math.cos(a)*math.cos(b) + math.sin(a)*math.sin(b)*math.cos(theta))
+
+    return radius*c

examples/tutorial/great_circle/c2.pyx

+import math
+
+def great_circle(double lon1, double lat1, double lon2, double lat2):
+    cdef double radius = 3956 # miles
+    cdef double x = math.pi/180.0
+    cdef double a, b, theta, c
+
+    a = (90.0 - lat1)*x
+    b = (90.0 - lat2)*x
+    theta = (lon2 - lon1)*x
+    c = math.acos(math.cos(a)*math.cos(b) + math.sin(a)*math.sin(b)*math.cos(theta))
+
+    return radius*c

examples/tutorial/great_circle/p1.py

+import math
+
+def great_circle(lon1, lat1, lon2, lat2):
+    radius = 3956 # miles
+    x = math.pi/180.0
+
+    a = (90.0 - lat1)*x
+    b = (90.0 - lat2)*x
+    theta = (lon2 - lon1)*x
+    c = math.acos(math.cos(a)*math.cos(b) + math.sin(a)*math.sin(b)*math.cos(theta))
+
+    return radius*c