Merge pull request #68 from larsmans/docfixes

DOC improve parallel/OpenMP section

docs/README

@@ -2,13 +2,14 @@ Cython's entire documentation suite is currently being overhauled.
 
 For the time being, I'll use this page to post notes.
 
-The previous Cython documentation files are hosted at http://hg.cython.org/cython-docs
+The previous Cython documentation files are hosted at
+http://hg.cython.org/cython-docs
 
 
 Notes
 =======
 
-1) Some css work should definately be done.
+1) Some css work should definitely be done.
 2) Use local 'top-of-page' contents rather than the sidebar, imo.
 3) Provide a link from each (sub)section to the TOC of the page.
 4) Fix cython highlighter for cdef blocks

docs/TODO

+Background
+----------
+
+[brain dump]
+
+The "Old Cython Users Guide" is a derivative of the old Pyrex documentation.
+It underwent substantial editing by Peter Alexandar
+to become the Reference Guide, which is oriented around bullet points
+and lists rather than prose. This transition was incomplete. 
+
+At nearly the same time, Robert, Dag, and Stefan wrote a tutorial as 
+part of the SciPy proceedings. It was felt that the content there was 
+cleaner and more up to date than anything else, and this became the 
+basis for the "Getting Started" and "Tutorials" sections. However, 
+it simply doesn't have as much content as the old documentation used to. 
+Eventually, it seems all of the old users manual could be whittled
+down into independent tutorial topics. Much discussion of what we'd
+like to see is at 
+
+http://www.mail-archive.com/cython-dev@codespeak.net/msg06945.html
+
+There is currently a huge amount of redundancy, but no one section has 
+it all. 
+
+Also, we should go through the wiki enhancement proposal list
+and make sure to transfer the (done) ones into the user manual. 

docs/src/userguide/external_C_code.rst

@@ -420,6 +420,8 @@ Cython provides facilities for releasing the Global Interpreter Lock (GIL)
 before calling C code, and for acquiring the GIL in functions that are to be
 called back from C code that is executed without the GIL.
 
+.. _nogil:
+
 Releasing the GIL
 ^^^^^^^^^^^^^^^^^
 

docs/src/userguide/parallelism.rst

@@ -7,8 +7,11 @@ Using Parallelism
 **********************************
 
 Cython supports native parallelism through the :py:mod:`cython.parallel`
-module. To use this kind of parallelism, the GIL must be released. It
-currently supports OpenMP, but later on more backends might be supported.
+module. To use this kind of parallelism, the GIL must be released
+(see :ref:`Releasing the GIL <nogil>`).
+It currently supports OpenMP, but later on more backends might be supported.
+
+__ nogil_
 
 .. function:: prange([start,] stop[, step], nogil=False, schedule=None)
 
@@ -59,11 +62,11 @@ currently supports OpenMP, but later on more backends might be supported.
     +-----------------+------------------------------------------------------+
 
     The default schedule is implementation defined. For more information consult
-    the OpenMP specification: [#]_.
+    the OpenMP specification [#]_.
 
     Example with a reduction::
 
-        from cython.parallel import prange, parallel, threadid
+        from cython.parallel import prange
 
         cdef int i
         cdef int sum = 0
@@ -75,7 +78,7 @@ currently supports OpenMP, but later on more backends might be supported.
 
     Example with a shared numpy array::
 
-        from cython.parallel import *
+        from cython.parallel import prange
 
         def func(np.ndarray[double] x, double alpha):
             cdef Py_ssize_t i
@@ -94,8 +97,8 @@ currently supports OpenMP, but later on more backends might be supported.
 
     Example with thread-local buffers::
 
-       from cython.parallel import *
-       from libc.stdlib cimport abort, malloc, free
+       from cython.parallel import parallel, prange
+       from libc.stdlib cimport abort
 
        cdef Py_ssize_t idx, i, n = 100
        cdef int * local_buf

docs/todo.txt

-Background
-----------
-
-[brain dump]
-
-The "Old Cython Users Guide" is a derivative of the old Pyrex documentation. It underwent substantial editing by Peter Alexandar
-to become the Reference Guide, which is oriented around bullet points
-and lists rather than prose. This transition was incomplete. 
-
-At nearly the same time, Robert, Dag, and Stefan wrote a tutorial as 
-part of the SciPy proceedings. It was felt that the content there was 
-cleaner and more up to date than anything else, and this became the 
-basis for the "Getting Started" and "Tutorials" sections. However, 
-it simply doesn't have as much content as the old documentation used to. 
-Eventually, it seems all of the old users manual could be whittled
-down into independent tutorial topics. Much discussion of what we'd
-like to see is at 
-
-http://www.mail-archive.com/cython-dev@codespeak.net/msg06945.html
-
-There is currently a huge amount of redundancy, but no one section has 
-it all. 
-
-Also, we should go through the wiki enhancement proposal list and make sure to transfer the (done) ones into the user manual.