Doc: fixing miscellaneous warnings and missing refs

docs/conf.py

@@ -31,7 +31,7 @@ highlight_language = 'cython'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['ipython_console_highlighting', 'cython_highlighting', 'sphinx.ext.pngmath', 'sphinx.ext.todo']
+extensions = ['ipython_console_highlighting', 'cython_highlighting', 'sphinx.ext.pngmath', 'sphinx.ext.todo', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -173,3 +173,6 @@ latex_documents = [
 
 # todo
 todo_include_todos = True
+
+# intersphinx for standard :keyword:s (def, for, etc.)
+intersphinx_mapping = {'python': ('http://docs.python.org/3.2', None)}

docs/sphinxext/cython_highlighting.py

@@ -179,4 +179,5 @@ class CythonLexer(RegexLexer):
     def analyse_text(text):
         return shebang_matches(text, r'pythonw?(2\.\d)?')
 
-highlighting.lexers['cython'] = CythonLexer()
+def setup(app):
+    app.add_lexer('cython', CythonLexer())

docs/sphinxext/ipython_console_highlighting.py

@@ -72,4 +72,6 @@ class IPythonConsoleLexer(Lexer):
                                       pylexer.get_tokens_unprocessed(curcode)):
                 yield item
 
-highlighting.lexers['ipython'] = IPythonConsoleLexer()
+
+def setup(app):
+    app.add_lexer('ipython', IPythonConsoleLexer())

docs/src/reference/compilation.rst

 .. highlight:: cython
 
-.. _compilation:
+.. _compilation-reference:
 
 =============
 Compilation

docs/src/reference/language_basics.rst

@@ -112,6 +112,7 @@ However with Cython it is possible to gain significant speed-ups through the use
 
     Providing static typing to parameters and variables is convenience to speed up your code, but it is not a necessity. Optimize where and when needed.
 
+
 The cdef Statement
 ==================
 
@@ -531,6 +532,8 @@ Callable from Python
 * Return Python objects
 * See **Parameters** for special consideration
 
+.. _cdef:
+
 Callable from C
 ================
 
@@ -538,6 +541,8 @@ Callable from C
 * Are called with either Python objects or C values.
 * Can return either Python objects or C values.
 
+.. _cpdef:
+
 Callable from both Python and C
 ================================
 

docs/src/tutorial/numpy.rst

@@ -286,7 +286,7 @@ function call.)
 
     Speed comes with some cost. Especially it can be dangerous to set typed
     objects (like ``f``, ``g`` and ``h`` in our sample code) to
-    :keyword:`None`.  Setting such objects to :keyword:`None` is entirely
+    ``None``.  Setting such objects to ``None`` is entirely
     legal, but all you can do with them is check whether they are None. All
     other use (attribute lookup or indexing) can potentially segfault or
     corrupt data (rather than raising exceptions as they would in Python).

docs/src/tutorial/pypy.rst

@@ -119,7 +119,7 @@ may exhibit substantially different performance characteristics in cpyext.
 Functions returning borrowed references were already mentioned as requiring
 special care, but they also induce substantially more runtime overhead because
 they often create weak references in PyPy where they only return a plain
-pointer in CPython.  A visible example is :c:func:``PyTuple_GET_ITEM()`.
+pointer in CPython.  A visible example is :c:func:`PyTuple_GET_ITEM()`.
 
 Some more high-level functions may also show entirely different performance
 characteristics, e.g. :c:func:`PyDict_Next()` for dict iteration.  While

docs/src/userguide/early_binding_for_speed.rst

@@ -102,7 +102,7 @@ overheads. Consider this code:
 .. note:: 
 
     in earlier versions of Cython, the :keyword:`cpdef` keyword is
-    :keyword:`rdef` - but has the same effect).
+    ``rdef`` - but has the same effect).
 
 Here, we just have a single area method, declared as :keyword:`cpdef` to make it
 efficiently callable as a C function, but still accessible from pure Python

docs/src/userguide/extension_types.rst

@@ -37,6 +37,8 @@ particular extension type), or they may be of any C data type. So you can use
 extension types to wrap arbitrary C data structures and provide a Python-like
 interface to them.  
 
+.. _readonly:
+
 Attributes
 ============
 
@@ -464,7 +466,7 @@ built-in complex object.::
 
        .. sourcecode:: c
 
-        ctypedef struct {
+        typedef struct {
             ...
         } PyComplexObject;
 
@@ -475,7 +477,7 @@ built-in complex object.::
     3. When declaring an external extension type, you don't declare any
        methods.  Declaration of methods is not required in order to call them,
        because the calls are Python method calls. Also, as with
-       :keyword:`structs` and :keyword:`unions`, if your extension class
+       :keyword:`struct` and :keyword:`union`, if your extension class
        declaration is inside a :keyword:`cdef` extern from block, you only need to
        declare those C members which you wish to access.
 

docs/src/userguide/external_C_code.rst

@@ -132,12 +132,12 @@ match the C ones, and in some cases they shouldn't or can't. In particular:
    be used for this new type. 
 
 5. If the header file uses macros to define constants, translate them into a
-   dummy ``enum`` declaration.
+   dummy :keyword:`enum` declaration.
 
 6. If the header file defines a function using a macro, declare it as though
    it were an ordinary function, with appropriate argument and result types.
 
-7. For archaic reasons C uses the keyword :keyword:`void` to declare a function
+7. For archaic reasons C uses the keyword ``void`` to declare a function
    taking no parameters. In Cython as in Python, simply declare such functions
    as :meth:`foo()`.
 
@@ -157,6 +157,8 @@ A few more tricks and tips:
     cdef extern from *:
         ...
 
+.. _struct-union-enum-styles:
+
 Styles of struct, union and enum declaration
 ----------------------------------------------
 
@@ -341,6 +343,8 @@ If the Cython module resides within a package, then the name of the ``.h``
 file consists of the full dotted name of the module, e.g. a module called
 :mod:`foo.spam` would have a header file called :file:`foo.spam.h`.
 
+.. _api:
+
 C API Declarations
 -------------------
 
@@ -441,7 +445,7 @@ Releasing the GIL
 ^^^^^^^^^^^^^^^^^
 
 You can release the GIL around a section of code using the
-:keyword:`with nogil` statement::
+``with nogil`` statement::
 
     with nogil:
         <code to be executed with the GIL released>
@@ -450,6 +454,8 @@ Code in the body of the statement must not manipulate Python objects in any
 way, and must not call anything that manipulates Python objects without first
 re-acquiring the GIL. Cython currently does not check this.
 
+.. _gil:
+
 Acquiring the GIL
 ^^^^^^^^^^^^^^^^^
 

docs/src/userguide/language_basics.rst

 .. highlight:: cython
 
 .. _language-basics:
+.. _struct:
+.. _union:
+.. _enum:
+.. _ctypedef:
+
 
 *****************
 Language Basics
@@ -34,6 +39,8 @@ and C :keyword:`struct`, :keyword:`union` or :keyword:`enum` types::
         soft = 2
         runny = 3
 
+See also :ref:`struct-union-enum-styles`
+
 There is currently no special syntax for defining a constant, but you can use
 an anonymous :keyword:`enum` declaration for this purpose, for example,::
 

docs/src/userguide/numpy_tutorial.rst

@@ -440,14 +440,14 @@ function call.)
 .. Warning::
 
     Speed comes with some cost. Especially it can be dangerous to set typed
-    objects (like ``f``, ``g`` and ``h`` in our sample code) to :keyword:`None`.
-    Setting such objects to :keyword:`None` is entirely legal, but all you can do with them
+    objects (like ``f``, ``g`` and ``h`` in our sample code) to ``None``.
+    Setting such objects to ``None`` is entirely legal, but all you can do with them
     is check whether they are None. All other use (attribute lookup or indexing)
     can potentially segfault or corrupt data (rather than raising exceptions as
     they would in Python).
 
     The actual rules are a bit more complicated but the main message is clear: Do
-    not use typed objects without knowing that they are not set to None.
+    not use typed objects without knowing that they are not set to ``None``.
 
 More generic code
 ==================

docs/src/userguide/parallelism.rst

@@ -16,7 +16,6 @@ It currently supports OpenMP, but later on more backends might be supported.
 .. NOTE:: Functionality in this module may only be used from the main thread
           or parallel regions due to OpenMP restrictions.
 
-__ nogil_
 
 .. function:: prange([start,] stop[, step][, nogil=False][, schedule=None[, chunksize=None]][, num_threads=None])
 

docs/src/userguide/pyrex_differences.rst

@@ -78,6 +78,9 @@ http://www.python.org/dev/peps/pep-0308/::
        
 Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C). 
 
+
+.. _inline:
+
 cdef inline
 =============
 
@@ -284,7 +287,7 @@ with corresponding ``.pyx`` file::
 Function pointers in structs
 =============================
 
-Functions declared in :keyword:`structs` are automatically converted to
+Functions declared in :keyword:`struct` are automatically converted to
 function pointers for convenience.
 
 C++ Exception handling
@@ -317,7 +320,7 @@ literals like ``u'abcd'`` to unicode objects.
 Automatic ``typecheck``
 ========================
 
-Rather than introducing a new keyword :keyword:`typecheck` as explained in the
+Rather than introducing a new keyword ``typecheck`` as explained in the
 `Pyrex docs
 <http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/Manual/special_methods.html>`_,
 Cython emits a (non-spoofable and faster) typecheck whenever

docs/src/userguide/sharing_declarations.rst

@@ -59,6 +59,8 @@ corresponding definition file also defines that type (see below).
 If one doesn't need to :keyword:`cimport` anything from this module, then this
 is the only file one needs. 
 
+.. _cimport:
+
 The cimport statement
 =======================
 

docs/src/userguide/source_files_and_compilation.rst

@@ -6,6 +6,8 @@
 Source Files and Compilation
 ****************************
 
+.. note:: See :ref:`compilation-reference` reference section for more details
+
 Cython source file names consist of the name of the module followed by a
 ``.pyx`` extension, for example a module called primes would have a source
 file named :file:`primes.pyx`.