Fixed heading levels. Added some Cython branding!

conf.py

@@ -87,12 +87,18 @@ html_style = 'default.css'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
+# Include the Cython logo in the sidebar
+html_logo = '_static/cythonlogo.png'
+
+# used a favicon!
+html_favicon = '_static/favicon.ico'
+
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True

docs/early_binding_for_speed.rst

 .. highlight:: cython
 
-.. _early-binding-speed-label:
+.. _early-binding-for-speed:
 
+**************************
 Early Binding for Speed
-=======================
+**************************
 
 As a dynamic language, Python encourages a programming style of considering
 classes and objects in terms of their methods and attributes, more than where
@@ -98,7 +99,7 @@ overheads. Consider this code:
         rect = Rectangle(x0, y0, x1, y1)
         return rect.area()
 
-.. Note:: 
+.. note:: 
 
     in earlier versions of Cython, the :keyword:`cpdef` keyword is
     :keyword:`rdef` - but has the same effect).

docs/extension_types.rst

 .. highlight:: cython
 
+.. _extension-types:
+
+******************
 Extension Types
-===============
+******************
 
 Introduction
--------------
+==============
 
 As well as creating normal user-defined classes with the Python class
 statement, Cython also lets you create new built-in Python types, known as
@@ -35,7 +38,7 @@ extension types to wrap arbitrary C data structures and provide a Python-like
 interface to them.  
 
 Attributes
------------
+============
 
 Attributes of an extension type are stored directly in the object's C struct.
 The set of attributes is fixed at compile time; you can't add attributes to an
@@ -75,7 +78,7 @@ and the depth attribute readable but not writable.
     are always readable and writable by direct access.
 
 Type declarations
------------------
+===================
 
 Before you can directly access the attributes of an extension type, the Cython
 compiler must know that you have an instance of that type, and not just a
@@ -112,7 +115,7 @@ The same consideration applies to local variables, for example,::
         return sh2
 
 Extension types and None
-------------------------
+=========================
 
 When you declare a parameter or C variable as being of an extension type,
 Cython will allow it to take on the value ``None`` as well as values of its
@@ -171,7 +174,7 @@ with checking that it has the right type.
       will invoke Python operations and therefore be much slower.
 
 Special methods
----------------
+================
 
 Although the principles are similar, there are substantial differences between
 many of the :meth:`__xxx__` special methods of extension types and their Python
@@ -180,7 +183,7 @@ read it carefully before attempting to use any special methods in your
 extension types.
 
 Properties
-----------
+============
 
 There is a special syntax for defining properties in an extension class::
 
@@ -251,7 +254,7 @@ when it is deleted.::
     We don't have: []
 
 Subclassing
------------
+=============
 
 An extension type may inherit from a built-in type or another extension type::
 
@@ -316,7 +319,7 @@ method using the usual Python technique, i.e.::
     Parrot.describe(self)
 
 Forward-declaring extension types
----------------------------------
+===================================
 
 Extension types can be forward-declared, like :keyword:`struct` and
 :keyword:`union` types. This will be necessary if you have two extension types
@@ -342,7 +345,7 @@ definition, for example,::
         # attributes and methods
 
 Making extension types weak-referenceable
------------------------------------------
+==========================================
 
 By default, extension types do not support having weak references made to
 them. You can enable weak referencing by declaring a C attribute of type
@@ -355,7 +358,7 @@ object called :attr:`__weakref__`. For example,::
         cdef object __weakref__
 
 Public and external extension types
------------------------------------
+====================================
 
 Extension types can be declared extern or public. An extern extension type
 declaration makes an extension type defined in external C code available to a
@@ -373,7 +376,7 @@ objects defined in the Python core or in a non-Cython extension module.
     In Pyrex versions before 0.8, extern extension types were also used to
     reference extension types defined in another Pyrex module. While you can still
     do that, Cython provides a better mechanism for this. See
-    :ref:`sharing-declarations-label`.
+    :ref:`sharing-declarations`.
 
 Here is an example which will let you get at the C-level members of the
 built-in complex object.::

docs/external_C_code.rst

 .. highlight:: cython
 
+.. external-C-code:
+
+**********************************
 Interfacing with External C Code
-================================
+**********************************
 
 One of the main uses of Cython is wrapping existing libraries of C code. This
 is achieved by using external declarations to declare the C functions and
@@ -15,7 +18,7 @@ Cython module can be used as a bridge to allow Python code to call C code, it
 can also be used to allow C code to call Python code.
 
 External declarations
----------------------
+=======================
 
 By default, C functions and variables declared at the module level are local
 to the module (i.e. they have the C static storage class). They can also be
@@ -26,7 +29,7 @@ declared extern to specify that they are defined elsewhere, for example::
     cdef extern void order_spam(int tons)
 
 Referencing C header files
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
 
 When you use an extern definition on its own as in the examples above, Cython
 includes a declaration for it in the generated C file. This can cause problems
@@ -143,7 +146,7 @@ A few more tricks and tips:
         ...
 
 Styles of struct, union and enum declaration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------------------
 
 There are two main ways that structs, unions and enums can be declared in C
 header files: using a tag name, or using a typedef. There are also some
@@ -198,7 +201,7 @@ Note that in all the cases below, you refer to the type in Cython code simply
 as :ctype:`Foo`, not ``struct Foo``.
 
 Accessing Python/C API routines
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------
 
 One particular use of the ``cdef extern from`` statement is for gaining access to
 routines in the Python/C API. For example,::
@@ -210,14 +213,14 @@ routines in the Python/C API. For example,::
 will allow you to create Python strings containing null bytes.
 
 Special Types
-^^^^^^^^^^^^^
+--------------
 
 Cython predefines the name ``Py_ssize_t`` for use with Python/C API routines. To
 make your extensions compatible with 64-bit systems, you should always use
 this type where it is specified in the documentation of Python/C API routines.
 
 Windows Calling Conventions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------
 
 The ``__stdcall`` and ``__cdecl`` calling convention specifiers can be used in
 Cython, with the same syntax as used by C compilers on Windows, for example,::
@@ -230,7 +233,7 @@ If ``__stdcall`` is used, the function is only considered compatible with
 other ``__stdcall`` functions of the same signature.
 
 Resolving naming conflicts - C name specifications
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------------------------
 
 Each Cython module has a single module-level namespace for both Python and C
 names. This can be inconvenient if you want to wrap some external C functions
@@ -274,7 +277,7 @@ enums, struct and union members, and enum values. For example,::
       second "beta" = 3
 
 Using Cython Declarations from C
---------------------------------
+==================================
 
 Cython provides two methods for making C declarations from a Cython module
 available for use by external C code – public declarations and C API
@@ -287,7 +290,7 @@ declarations.
     :keyword:`cimport` statement for that. Sharing Declarations Between Cython Modules.
 
 Public Declarations
-^^^^^^^^^^^^^^^^^^^
+---------------------
 
 You can make C types, variables and functions defined in a Cython module
 accessible to C code that is linked with the module, by declaring them with
@@ -313,7 +316,7 @@ 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`.
 
 C API Declarations
-^^^^^^^^^^^^^^^^^^
+-------------------
 
 The other way of making declarations available to C code is to declare them
 with the :keyword:`api` keyword. You can use this keyword with C functions and
@@ -381,8 +384,8 @@ E.g. a module called :mod:`foo.spam` would have an API header file called
 :file:`foo.spam_api.h` and an importing function called
 :func:`import_foo__spam`.
 
-Multiple public and api declarations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Multiple public and API declarations
+--------------------------------------
 
 You can declare a whole group of items as :keyword:`public` and/or
 :keyword:`api` all at once by enclosing them in a :keyword:`cdef` block, for
@@ -393,11 +396,11 @@ example,::
         char *get_lunch(float tomato_size)
 
 This can be a useful thing to do in a ``.pxd`` file (see
-:ref:`sharing-declarations-label`) to make the module's public interface
+:ref:`sharing-declarations`) to make the module's public interface
 available by all three methods.
 
 Acquiring and Releasing the GIL
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------
 
 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
@@ -428,7 +431,7 @@ header::
         ...
 
 Declaring a function as callable without the GIL
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------------------------
 
 You can specify :keyword:`nogil` in a C function header or function type to
 declare that it is safe to call without the GIL.::

docs/language_basics.rst

 .. highlight:: cython
 
-.. _language-basics-label:
+.. _language-basics:
 
+*****************
 Language Basics
-===============
+*****************
 
 Python functions vs. C functions
---------------------------------
+==================================
 
 There are two kinds of function definition in Cython:
 
@@ -123,7 +124,7 @@ an anonymous :keyword:`enum` declaration for this purpose, for example,::
         ctypedef int *IntPtr
 
 Grouping multiple C declarations
-================================
+==================================
 
 If you have a series of declarations that all begin with :keyword:`cdef`, you
 can group them into a :keyword:`cdef` block like this::
@@ -422,7 +423,7 @@ The include statement
 ----------------------
 
 .. warning:: 
-    This feature is deprecated. Use :ref:`sharing-declarations-label` instead.
+    This feature is deprecated. Use :ref:`sharing-declarations` instead.
 
 A Cython source file can include material from other files using the include
 statement, for example::
@@ -440,7 +441,7 @@ the level of the include statement that is including the file.
 
     There are other mechanisms available for splitting Cython code into
     separate parts that may be more appropriate in many cases. See
-    :ref:`sharing-declarations-label`.
+    :ref:`sharing-declarations`.
 
 Keyword-only arguments
 ----------------------

docs/limitations.rst

 .. highlight:: cython
 
-.. _cython-limitations-label:
+.. _cython-limitations:
 
 *************
 Limitations

docs/numpy_tutorial.rst

 .. highlight:: cython
 
-.. _numpy_tute-label:
+.. _numpy_tutorial:
 
 **************************
 Cython for NumPy users
@@ -34,6 +34,7 @@ The style of this tutorial will not fit everybody, so you can also consider:
 
 Cython at a glance
 ====================
+
 Cython is a compiler which compiles Python-like code files to C code. Still,
 ''Cython is not a Python to C translator''. That is, it doesn't take your full
 program and "turns it into C" -- rather, the result makes full use of the
@@ -56,6 +57,7 @@ functions and generator functions).
 
 Your Cython environment
 ========================
+
 Using Cython consists of these steps:
 
 1. Write a :file:`.pyx` source file

docs/overview.rst

 .. highlight:: cython
 
-.. _overview-label:
+.. _overview:
 
 ********
 Overview
@@ -24,9 +24,9 @@ and for fast C modules that speed up the execution of Python code.
 Future Plans
 ============
 Cython is not finished. Substantial tasks remaining. See
-:ref:`cython-limitations-label` for a current list. 
+:ref:`cython-limitations` for a current list. 
 
 .. rubric:: Footnotes
 
-.. [#] For differences with Pyrex see :ref:`pyrex-differences-label`.
+.. [#] For differences with Pyrex see :ref:`pyrex-differences`.
 

docs/pyrex_differences.rst

 .. highlight:: cython
 
-.. _pyrex-differences-label:
+.. _pyrex-differences:
 
+**************************************
 Differences between Cython and Pyrex
-====================================
+**************************************
 
 Package names and cross-directory imports
------------------------------------------
+==========================================
 
 Just like in python. 
 
 List Comprehensions
--------------------
+====================
 
 `[expr(x) for x in A]` is now available, implementing the full specification
 at http://www.python.org/dev/peps/pep-0202/ . Looping is optimized if ``A`` is
@@ -20,7 +21,7 @@ a list. Also, use the :keyword:`for` ... :keyword:`from` syntax too, e.g.::
     [i*i for i from 0 <= i < 10] 
 
 Conditional expressions "x if b else y" (python 2.5)
-----------------------------------------------------
+=====================================================
 
 Conditional expressions as described in
 http://www.python.org/dev/peps/pep-0308/::
@@ -30,7 +31,7 @@ http://www.python.org/dev/peps/pep-0308/::
 Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C). 
 
 cdef inline
------------
+=============
 
 Module level functions can now be declared inline, with the :keyword:`inline`
 keyword passed on to the C compiler. These can be as fast as macros.::
@@ -43,7 +44,7 @@ function table, so the compiler won't be able to inline them in almost all
 cases. 
 
 Assignment on declaration (e.g. "cdef int spam = 5")
-----------------------------------------------------
+======================================================
 
 In Pyrex, one must write::
 
@@ -62,7 +63,7 @@ The expression on the right hand side can be arbitrarily complicated, e.g.::
        
 
 'by' expression in for loop (e.g. "for i from 0 <= i < 10 by 2")
-----------------------------------------------------------------
+==================================================================
     
 ::
 
@@ -82,7 +83,7 @@ yields::
        
 
 Boolean int type (e.g. it acts like a c int, but coerces to/from python as a boolean)
--------------------------------------------------------------------------------------
+======================================================================================
 
 In C, ints are used for truth values. In python, any object can be used as a
 truth value (using the :meth:`__nonzero__` method, but the canonical choices
@@ -107,7 +108,7 @@ happen via ``x.__nonzero__()``. (Actually, if ``x`` is the python object
 ``True`` or ``False`` then no method call is made.) 
 
 Executable class bodies
------------------------
+=========================
 
 Including a working :func:`classmethod`::
 
@@ -119,7 +120,7 @@ Including a working :func:`classmethod`::
         print "hi", a
         
 cpdef functions
----------------
+=================
 
 Cython adds a third function type on top of the usual :keyword:`def` and
 :keyword:`cdef`. If a function is declared :keyword:`cpdef` it can be called
@@ -154,12 +155,12 @@ method on the class directly, e.g.::
     x.foo()  # will check to see if overridden
     A.foo(x) # will call A's implementation whether overridden or not
 
-See :ref:`early-binding-speed-label` for explanation and usage tips. 
+See :ref:`early-binding-for-speed` for explanation and usage tips. 
 
 .. _automatic-range-conversion:
 
 Automatic range conversion
--------------------------------------
+============================
 
 This will convert statements of the form ``for i in range(...)`` to ``for i
 from ...`` when ``i`` is any cdef'd integer type, and the direction (i.e. sign
@@ -175,7 +176,7 @@ of step) can be determined.
     way to set this).
 
 More friendly type casting
---------------------------
+===========================
 
 In Pyrex, if one types ``<int>x`` where ``x`` is a Python object, one will get
 the memory address of ``x``. Likewise, if one types ``<object>i`` where ``i``
@@ -193,7 +194,7 @@ with type checking (i.e. it will throw an error if ``x`` is not a (subclass of)
 :ctype:`MyExtensionType`. 
 
 Optional arguments in cdef/cpdef functions
-------------------------------------------
+============================================
 
 Cython now supports optional arguments for :keyword:`cdef` and
 :keyword:`cpdef` functions.
@@ -232,13 +233,13 @@ with corresponding ``.pyx`` file::
     :keyword:`cdef` functions.
 
 Function pointers in structs
-----------------------------
+=============================
 
 Functions declared in :keyword:`structs` are automatically converted to
 function pointers for convenience.
 
 C++ Exception handling
-----------------------
+=========================
 
 :keyword:`cdef` functions can now be declared as::
 
@@ -247,15 +248,15 @@ C++ Exception handling
     cdef int foo(...) except +python_error_raising_function
 
 in which case a Python exception will be raised when a C++ error is caught.
-See :ref:`wrapping-cplusplus-label` for more details.
+See :ref:`wrapping-cplusplus` for more details.
 
 Synonyms
---------
+=========
 
 ``cdef import from`` means the same thing as ``cdef extern from``
 
 Source code encoding
---------------------
+======================
 
 .. TODO: add the links to the relevent PEPs
 

docs/sharing_declarations.rst

 .. highlight:: cython
 
-.. _sharing-declarations-label:
+.. _sharing-declarations:
 
+********************************************
 Sharing Declarations Between Cython Modules
-===========================================
+********************************************
 
 This section describes a new set of facilities for making C declarations,
 functions and extension types in one Cython module available for use in
@@ -11,7 +12,7 @@ another Cython module. These facilities are closely modelled on the Python
 import mechanism, and can be thought of as a compile-time version of it.
 
 Definition and Implementation files
------------------------------------
+====================================
 
 A Cython module can be split into two parts: a definition file with a ``.pxd``
 suffix, containing C declarations that are to be available to other Cython
@@ -21,7 +22,7 @@ module's definition file, it imports it using the :keyword:`cimport`
 statement.
 
 What a Definition File contains
--------------------------------
+================================
 
 A definition file can contain:
 
@@ -43,14 +44,14 @@ Python class definitions, or any executable statements.
     declaration if you want to make something available to external C code.
 
 What an Implementation File contains
-------------------------------------
+======================================
 
 An implementation file can contain any kind of Cython statement, although there
 are some restrictions on the implementation part of an extension type if the
 corresponding definition file also defines that type (see below). 
 
 The cimport statement
----------------------
+=======================
 
 The :keyword:`cimport` statement is used in a definition or
 implementation file to gain access to names declared in another definition

docs/source_files_and_compilation.rst

 .. highlight:: cython
 
-.. _compilation_label:
+.. _compilation:
 
 ****************************
 Source Files and Compilation
@@ -44,7 +44,7 @@ would be::
     ) 
 
 To understand the :file:`setup.py` more fully look at the official
-``distutils`` documentation. To compile the extension for use in the
+:mod:`distutils` documentation. To compile the extension for use in the
 current directory use::
 
     $ python setup.py build_ext --inplace
@@ -52,15 +52,36 @@ current directory use::
 Cython Files Depending on C Files
 ===================================
 
-TODO
+When you have come C files that have been wrapped with cython and you want to
+compile them into your extension the basic :file:`setup.py` file to do this
+would be::
+
+    from distutils.core import setup
+    from distutils.extension import Extension
+    from Cython.Distutils import build_ext
+
+    sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
+
+    setup(
+        cmdclass = {'build_ext': build_ext},
+        ext_modules = [Extension("example", sourcefiles)]
+    )
+
+Notice that the files have been given a name, this is not necessary, but it
+makes the file easier to format if the list gets long.
+
+If any of the files depend on include paths information can be passed to the
+:obj:`Extension` class through the :keyword:`include_dirs` option, which is a
+list of paths to the include directories.
+
 
 Multiple Cython Files in a Package
 ===================================
 
 TODO
 
-Distributing Pyrex modules
-===========================
+Distributing Cython modules
+============================
 It is strongly recommended that you distribute the generated ``.c`` files as well
 as your Cython sources, so that users can install your module without needing
 to have Cython available.

docs/tutorial.rst

 .. highlight:: cython
 
-.. _tutorial_label:
+.. _tutorial:
 
 *********
 Tutorial
@@ -13,7 +13,7 @@ The fundamental nature of Cython can be summed up as follows: Cython is Python
 with C data types.
 
 Cython is Python: Almost any piece of Python code is also valid Cython code.
-(There are a few :ref:`cython-limitations-label`, but this approximation will
+(There are a few :ref:`cython-limitations`, but this approximation will
 serve for now.) The Cython compiler will convert it into C code which makes
 equivalent calls to the Python/C API. 
 
@@ -38,7 +38,8 @@ So lets start with the canonical python hello world::
     print "Hello World"
 
 So the first thing to do is rename the file to :file:`helloworld.pyx`. Now we
-need to make the :file:`setup.py`, which is like a python Makefile.::
+need to make the :file:`setup.py`, which is like a python Makefile (for more
+information see :ref:`compilation`)::
 
     from distutils.core import setup
     from distutils.extension import Extension
@@ -53,8 +54,8 @@ To use this to build your Cython file use the commandline options::
 
     $ python setup.py build_ext --inplace
 
-Which will leave a file in your local directory called `helloworld.so` in unix
-or `helloworld.dll` in Windows. Now to use this file start the python
+Which will leave a file in your local directory called :file:`helloworld.so` in unix
+or :file:`helloworld.dll` in Windows. Now to use this file: start the python
 interpreter and simply import it as if it was a regular python module::
 
     >>> import helloworld
@@ -138,5 +139,5 @@ take a look at the C code generated for this module.
 Language Details
 ================
 
-For more about the Cython language, see :ref:`language-basics-label`.
+For more about the Cython language, see :ref:`language-basics`.
 

docs/wrapping_CPlusPlus.rst

 .. highlight:: cython
 
-.. _wrapping-cplusplus-label:
+.. _wrapping-cplusplus:
 
+********************************
 Wrapping C++ Classes in Cython
-====================================
+********************************
 
 Overview
---------
+=========
 
 This page aims to get you quickly up to speed so you can wrap C++ interfaces
 with a minimum of pain and 'surprises'.
@@ -24,7 +25,7 @@ you wrap a lot of C++ code with only moderate effort. There are some
 limitations, which we will discuss at the end of the document.
 
 Procedure Overview
-------------------
+====================
 
 * Specify C++ language in :file:`setup.py` script
 * Create ``cdef extern from`` blocks and declare classes as 
@@ -34,7 +35,7 @@ Procedure Overview
 * Create Cython wrapper class 
 
 An example C++ API
-------------------
+===================
 
 Here is a tiny C++ API which we will use as an example throughout this
 document. Let's assume it will be in a header file called
@@ -54,7 +55,7 @@ document. Let's assume it will be in a header file called
 This is pretty dumb, but should suffice to demonstrate the steps involved.
 
 Specify C++ language in setup.py
---------------------------------
+=================================
 
 In Cython :file:`setup.py` scripts, one normally instantiates an Extension
 object. To make Cython generate and compile a C++ source, you just need
@@ -73,7 +74,7 @@ to add a keyword to your Extension construction statement, as in::
 With the language="c++" keyword, Cython distutils will generate a C++ file.
 
 Create cdef extern from block
------------------------------
+==============================
 
 The procedure for wrapping a C++ class is quite similar to that for wrapping
 normal C structs, with a couple of additions. Let's start here by creating the
@@ -84,7 +85,7 @@ basic ``cdef extern from`` block::
 This will make the C++ class def for Rectangle available.
 
 Declare class as a ctypedef struct
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------------
 
 Now, let's add the Rectangle class to this extern from block -- just copy the
 class def from :file:`Rectangle.h` and adjust for Cython syntax, so now it
@@ -99,7 +100,7 @@ We don't have any way of accessing the constructor/destructor or methods, but
 we'll cover this now.
 
 Add constructors and destructors
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------
 
 We now need to expose a constructor and destructor into the Cython
 namespace. Again, we'll be using C name specifications::
@@ -111,7 +112,7 @@ namespace. Again, we'll be using C name specifications::
         void del_Rectangle "delete" (c_Rectangle *rect)
 
 Add class methods
-^^^^^^^^^^^^^^^^^
+-------------------
 
 Now, let's add the class methods. You can circumvent Cython syntax
 limitations by declaring these as function pointers. Recall that in the C++
@@ -142,7 +143,7 @@ In Pyrex you must explicitly declare these as function pointers, i.e.
 ``(int *getArea)()``.
 
 Create Cython wrapper class
----------------------------
+=============================
 
 At this point, we have exposed into our pyx file's namespace a struct which
 gives us access to the interface of a C++ Rectangle type. Now, we need to make
@@ -177,7 +178,7 @@ attribute access, you could just implement some properties::
     ...
 
 Caveats and Limitations
------------------------
+========================
 
 In this document, we have discussed a relatively straightforward way of
 wrapping C++ classes with Cython. However, there are some limitations in
@@ -189,13 +190,13 @@ The major limitations I'm most immediately aware of (and there will be many
 more) include:
 
 Overloading
-^^^^^^^^^^^
+------------
 
 Presently, it's not easy to overload methods or constructors, but there may be
 a workaround if you try some creative C name specifications
 
 Access to C-only functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
 
 Whenever generating C++ code, Cython generates declarations of and calls
 to functions assuming these functions are C++ (ie, not declared as extern "C"
@@ -209,7 +210,7 @@ module which:
   respective pure-C function 
 
 Inherited C++ methods
-^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 If you have a class ``Foo`` with a child class ``Bar``, and ``Foo`` has a
 method :meth:`fred`, then you'll have to cast to access this method from
@@ -228,10 +229,10 @@ It might take some experimenting by others (you?) to find the most elegant
 ways of handling this issue.
 
 Advanced C++ features
-^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 Exceptions
-""""""""""
+^^^^^^^^^^^
 
 Cython cannot throw C++ exceptions, or catch them with a try-except statement,
 but it is possible to declare a function as potentially raising an C++
@@ -258,7 +259,7 @@ raise_py_error does not actually raise an exception a RuntimeError will be
 raised.
 
 Templates
-"""""""""
+^^^^^^^^^^
 
 Cython does not natively understand C++ templates but we can put them to use
 in some way. As an example consider an STL vector of C ints::
@@ -274,7 +275,7 @@ now we can use the vector like this::
     v.push_back(2)
 
 Overloading
-"""""""""""
+^^^^^^^^^^^^
 
 To support function overloading simply add a different alias to each
 signature, so if you have e.g. ::
@@ -288,7 +289,7 @@ in your C++ header then interface it like this in your ::
     int fooii "foo"(int, int)
 
 Operators
-"""""""""
+^^^^^^^^^^
 
 Some operators (e.g. +,-,...) can be accessed from Cython like this::
 
@@ -296,12 +297,12 @@ Some operators (e.g. +,-,...) can be accessed from Cython like this::
     c_Rectangle add "operator+"(c_Rectangle right)
 
 Declaring/Using References
-""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Question: How do you declare and call a function that takes a reference as an argument?
 
 Conclusion
-----------
+============
 
 A great many existing C++ classes can be wrapped using these techniques, in a
 way much easier than writing a large messy C shim module. There's a bit of

index.rst

-.. Cython documentation master file, created by sphinx-quickstart on Fri Apr 25 12:49:32 2008.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to Cython's documentation!
-================================================
+Welcome to Cython's Users Guide
+=================================
 
 Contents: