DOC improve parallel/OpenMP section

Fixed examples to not import unnecessary stuff, cross-ref nogil section,
some typos in docs/README.

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/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