Initial import of SIP4 for Qt3

16 files changed, 7998 insertions, 0 deletions

diff --git a/sphinx/annotations.rst b/sphinx/annotations.rst
new file mode 100644
index 0000000..05ab847
--- /dev/null
+++ b/sphinx/annotations.rst
@@ -0,0 +1,805 @@
+Annotations
+===========
+
+In this section we describe each of the annotations that can be used in
+specification files.
+
+Annotations can either be :ref:`argument annotations <ref-arg-annos>`,
+:ref:`class annotations <ref-class-annos>`, :ref:`mapped type annotations
+<ref-mapped-type-annos>`, :ref:`enum annotations <ref-enum-annos>`,
+:ref:`exception annotations <ref-exception-annos>`, :ref:`function annotations
+<ref-function-annos>`, :ref:`license annotations <ref-license-annos>`,
+:ref:`typedef annotations <ref-typedef-annos>` or :ref:`variable annotations
+<ref-variable-annos>` depending on the context in which they can be used.
+
+Annotations are placed between forward slashes (``/``).  Multiple annotations
+are comma separated within the slashes.
+
+Annotations have a type and, possibly, a value.  The type determines the
+format of the value.  The name of an annotation and its value are separated by
+``=``.
+
+Annotations can have one of the following types:
+
+*boolean*
+    This type of annotation has no value and is implicitly true.
+
+*name*
+    The value is a name that is compatible with a C/C++ identifier.  In some
+    cases the value is optional.
+
+*dotted name*
+    The value is a name that is compatible with an identifier preceded by a
+    Python scope.
+
+*string*
+    The value is a double quoted string.
+
+*API range*
+    The value is the name of an API (defined using the :directive:`%API`
+    directive) separated by a range of version numbers with a colon.
+
+    The range of version numbers is a pair of numbers separated by a hyphen
+    specifying the lower and upper bounds of the range.  A version number is
+    within the range if it is greater or equal to the lower bound and less
+    than the upper bound.  Each bound can be omitted meaning that the range is
+    unbounded in that direction.
+
+    For example::
+
+        # This is part of the PyQt4 API up to but excluding v2.
+        void hex() /API=PyQt4:-2/
+
+        # This is part of the PyQt4 API starting from v2.
+        void hex() /PyName=hex_, API=PyQt4:2-/
+
+The following example shows argument and function annotations::
+
+    void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/;
+
+Note that the current version of SIP does not complain about unknown
+annotations, or annotations used out of their correct context.
+
+
+.. _ref-arg-annos:
+
+Argument Annotations
+--------------------
+
+.. argument-annotation:: AllowNone
+
+    This boolean annotation specifies that the value of the corresponding
+    argument (which should be either :stype:`SIP_PYCALLABLE`,
+    :stype:`SIP_PYDICT`, :stype:`SIP_PYLIST`, :stype:`SIP_PYSLICE`,
+    :stype:`SIP_PYTUPLE` or :stype:`SIP_PYTYPE`) may be ``None``.
+
+
+.. argument-annotation:: Array
+
+    This boolean annotation specifies that the corresponding argument refers
+    to an array.
+    
+    The argument should be either a pointer to a wrapped type, a ``char *`` or
+    a ``unsigned char *``.  If the argument is a character array then the
+    annotation also implies the :aanno:`Encoding` annotation with an encoding
+    of ``"None"``.
+
+    There must be a corresponding argument with the :aanno:`ArraySize`
+    annotation specified.  The annotation may only be specified once in a list
+    of arguments.
+
+
+.. argument-annotation:: ArraySize
+
+    This boolean annotation specifies that the corresponding argument (which
+    should be either ``short``, ``unsigned short``, ``int``, ``unsigned``,
+    ``long`` or ``unsigned long``) refers to the size of an array.  There must
+    be a corresponding argument with the :aanno:`Array` annotation specified.
+    The annotation may only be specified once in a list of arguments.
+
+
+.. argument-annotation:: Constrained
+
+    Python will automatically convert between certain compatible types.  For
+    example, if a floating pointer number is expected and an integer supplied,
+    then the integer will be converted appropriately.  This can cause problems
+    when wrapping C or C++ functions with similar signatures.  For example::
+
+        // The wrapper for this function will also accept an integer argument
+        // which Python will automatically convert to a floating point number.
+        void foo(double);
+
+        // The wrapper for this function will never get used.
+        void foo(int);
+
+    This boolean annotation specifies that the corresponding argument (which
+    should be either ``bool``, ``int``, ``float``, ``double``, ``enum`` or a
+    wrapped class) must match the type without any automatic conversions.  In
+    the context of a wrapped class the invocation of any
+    :directive:`%ConvertToTypeCode` is suppressed.
+
+    The following example gets around the above problem::
+
+        // The wrapper for this function will only accept floating point
+        // numbers.
+        void foo(double /Constrained/);
+
+        // The wrapper for this function will be used for anything that Python
+        // can convert to an integer, except for floating point numbers.
+        void foo(int);
+
+
+.. argument-annotation:: DocType
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the type of the argument as it will appear
+    in any generated docstrings.  It is usually used with arguments of type
+    :stype:`SIP_PYOBJECT` to provide a more specific type.
+
+
+.. argument-annotation:: DocValue
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the default value of the argument as it
+    will appear in any generated docstrings.
+
+
+.. argument-annotation:: Encoding
+
+    This string annotation specifies that the corresponding argument (which
+    should be either ``char``, ``const char``, ``char *`` or ``const char *``)
+    refers to an encoded character or ``'\0'`` terminated encoded string with
+    the specified encoding.  The encoding can be either ``"ASCII"``,
+    ``"Latin-1"``, ``"UTF-8"`` or ``"None"``.  An encoding of ``"None"`` means
+    that the corresponding argument refers to an unencoded character or string.
+
+    The default encoding is specified by the :directive:`%DefaultEncoding`
+    directive.  If the directive is not specified then ``None`` is used.
+
+    Python v3 will use the ``bytes`` type to represent the argument if the
+    encoding is ``"None"`` and the ``str`` type otherwise.
+
+    Python v2 will use the ``str`` type to represent the argument if the
+    encoding is ``"None"`` and the ``unicode`` type otherwise.
+
+
+.. argument-annotation:: GetWrapper
+
+    This boolean annotation is only ever used in conjunction with handwritten
+    code specified with the :directive:`%MethodCode` directive.  It causes an
+    extra variable to be generated for the corresponding argument which is a
+    pointer to the Python object that wraps the argument.
+
+    See the :directive:`%MethodCode` directive for more detail.
+
+
+.. argument-annotation:: In
+
+    This boolean annotation is used to specify that the corresponding argument
+    (which should be a pointer type) is used to pass a value to the function.
+
+    For pointers to wrapped C structures or C++ class instances, ``char *`` and
+    ``unsigned char *`` then this annotation is assumed unless the :aanno:`Out`
+    annotation is specified.
+
+    For pointers to other types then this annotation must be explicitly
+    specified if required.  The argument will be dereferenced to obtain the
+    actual value.
+
+    Both :aanno:`In` and :aanno:`Out` may be specified for the same argument.
+
+
+.. argument-annotation:: KeepReference
+
+    This boolean annotation is used to specify that a reference to the
+    corresponding argument should be kept to ensure that the object is not
+    garbage collected.  If the method is called again with a new argument then
+    the reference to the previous argument is discarded.  Note that ownership
+    of the argument is not changed.
+
+
+.. argument-annotation:: NoCopy
+
+    .. versionadded:: 4.10.1
+
+    This boolean annotation is used with arguments of virtual methods that are
+    a ``const`` reference to a class.  Normally, if the class defines a copy
+    constructor then a copy of the returned reference is automatically created
+    and wrapped before being passed to a Python reimplementation of the method.
+    The copy will be owned by Python.  This means that the reimplementation may
+    take a reference to the argument without having to make an explicit copy.
+    
+    If the annotation is specified then the copy is not made and the original
+    reference is wrapped instead and will be owned by C++.
+
+
+.. argument-annotation:: Out
+
+    This boolean annotation is used to specify that the corresponding argument
+    (which should be a pointer type) is used by the function to return a value
+    as an element of a tuple.
+
+    For pointers to wrapped C structures or C++ class instances, ``char *`` and
+    ``unsigned char *`` then this annotation must be explicitly specified if
+    required.
+
+    For pointers to other types then this annotation is assumed unless the
+    :aanno:`In` annotation is specified.
+
+    Both :aanno:`In` and :aanno:`Out` may be specified for the same argument.
+
+
+.. argument-annotation:: ResultSize
+
+    This boolean annotation is used with functions or methods that return a
+    ``void *`` or ``const void *``.  It identifies an argument that defines the
+    size of the block of memory whose address is being returned.  This allows
+    the ``sip.voidptr`` object that wraps the address to support the Python
+    buffer protocol and allows the memory to be read and updated when wrapped
+    by the Python ``buffer()`` builtin.
+
+
+.. argument-annotation:: SingleShot
+
+    This boolean annotation is used only with arguments of type
+    :stype:`SIP_RXOBJ_CON` to specify that the signal connected to the slot
+    will only ever be emitted once.  This prevents a certain class of memory
+    leaks.
+
+
+.. argument-annotation:: Transfer
+
+    This boolean annotation is used to specify that ownership of the
+    corresponding argument (which should be a wrapped C structure or C++ class
+    instance) is transferred from Python to C++.  In addition, if the argument
+    is of a class method, then it is associated with the class instance with
+    regard to the cyclic garbage collector.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. argument-annotation:: TransferBack
+
+    This boolean annotation is used to specify that ownership of the
+    corresponding argument (which should be a wrapped C structure or C++ class
+    instance) is transferred back to Python from C++.  In addition, any
+    association of the argument with regard to the cyclic garbage collector
+    with another instance is removed.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. argument-annotation:: TransferThis
+
+    This boolean annotation is only used in C++ constructors or methods.  In
+    the context of a constructor or factory method it specifies that ownership
+    of the instance being created is transferred from Python to C++ if the
+    corresponding argument (which should be a wrapped C structure or C++ class
+    instance) is not ``None``.  In addition, the newly created instance is
+    associated with the argument with regard to the cyclic garbage collector.
+
+    In the context of a non-factory method it specifies that ownership of
+    ``this`` is transferred from Python to C++ if the corresponding argument is
+    not ``None``.  If it is ``None`` then ownership is transferred to Python.
+
+    The annotation may be used more that once, in which case ownership is
+    transferred to last instance that is not ``None``.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. _ref-class-annos:
+
+Class Annotations
+-----------------
+
+.. class-annotation:: Abstract
+
+    This boolean annotation is used to specify that the class has additional
+    pure virtual methods that have not been specified and so it cannot be
+    instantiated or sub-classed from Python.
+
+
+.. class-annotation:: AllowNone
+
+    .. versionadded:: 4.8.2
+
+    Normally when a Python object is converted to a C/C++ instance ``None``
+    is handled automatically before the class's
+    :directive:`%ConvertToTypeCode` is called.  This boolean annotation
+    specifies that the handling of ``None`` will be left to the
+    :directive:`%ConvertToTypeCode`.  The annotation is ignored if the class
+    does not have any :directive:`%ConvertToTypeCode`.
+
+
+.. class-annotation:: API
+
+    .. versionadded:: 4.9
+
+    This API range annotation is used to specify an API and corresponding
+    range of version numbers that the class is enabled for.
+
+    If a class or mapped type has different implementations enabled for
+    different ranges of version numbers then those ranges must not overlap.
+
+    See :ref:`ref-incompat-apis` for more detail.
+
+
+.. class-annotation:: DelayDtor
+
+    This boolean annotation is used to specify that the class's destructor
+    should not be called until the Python interpreter exits.  It would normally
+    only be applied to singleton classes.
+
+    When the Python interpreter exits the order in which any wrapped instances
+    are garbage collected is unpredictable.  However, the underlying C or C++
+    instances may need to be destroyed in a certain order.  If this annotation
+    is specified then when the wrapped instance is garbage collected the C or
+    C++ instance is not destroyed but instead added to a list of delayed
+    instances.  When the interpreter exits then the function
+    :cfunc:`sipDelayedDtors()` is called with the list of delayed instances.
+    :cfunc:`sipDelayedDtors()` can then choose to call (or ignore) the
+    destructors in any desired order.
+
+    The :cfunc:`sipDelayedDtors()` function must be specified using the
+    :directive:`%ModuleCode` directive.
+
+.. cfunction:: void sipDelayedDtors(const sipDelayedDtor *dd_list)
+
+    :param dd_list:
+        the linked list of delayed instances.
+
+.. ctype:: sipDelayedDtor
+
+    This structure describes a particular delayed destructor.
+
+    .. cmember:: const char *dd_name
+
+        This is the name of the class excluding any package or module name.
+
+    .. cmember:: void *dd_ptr
+
+        This is the address of the C or C++ instance to be destroyed.  It's
+        exact type depends on the value of :cmember:`dd_isderived`.
+
+    .. cmember:: int dd_isderived
+
+        This is non-zero if the type of :cmember:`dd_ptr` is actually the
+        generated derived class.  This allows the correct destructor to be
+        called.  See :ref:`ref-derived-classes`.
+
+    .. cmember:: sipDelayedDtor *dd_next
+
+        This is the address of the next entry in the list or zero if this is
+        the last one.
+
+    Note that the above applies only to C and C++ instances that are owned by
+    Python.
+
+
+.. class-annotation:: Deprecated
+
+    This boolean annotation is used to specify that the class is deprecated.
+    It is the equivalent of annotating all the class's constructors, function
+    and methods as being deprecated.
+
+
+.. class-annotation:: External
+
+    This boolean annotation is used to specify that the class is defined in
+    another module.  Declarations of external classes are private to the module
+    in which they appear.
+
+
+.. class-annotation:: Metatype
+
+    This dotted name annotation specifies the name of the Python type object
+    (i.e. the value of the ``tp_name`` field) used as the meta-type used when
+    creating the type object for this C structure or C++ type.
+
+    See the section :ref:`ref-types-metatypes` for more details.
+
+
+.. class-annotation:: NoDefaultCtors
+
+    This boolean annotation is used to suppress the automatic generation of
+    default constructors for the class.
+
+
+.. class-annotation:: PyName
+
+    This name annotation specifies an alternative name for the class being
+    wrapped which is used when it is referred to from Python.  It is required
+    when a class name is the same as a Python keyword.  It may also be used to
+    avoid name clashes with other objects (e.g. enums, exceptions, functions)
+    that have the same name in the same C++ scope.
+
+
+.. class-annotation:: Supertype
+
+    This dotted name annotation specifies the name of the Python type object
+    (i.e. the value of the ``tp_name`` field) used as the super-type used when
+    creating the type object for this C structure or C++ type.
+
+    See the section :ref:`ref-types-metatypes` for more details.
+
+
+.. _ref-mapped-type-annos:
+
+Mapped Type Annotations
+-----------------------
+
+.. mapped-type-annotation:: AllowNone
+
+    Normally when a Python object is converted to a C/C++ instance ``None``
+    is handled automatically before the mapped type's
+    :directive:`%ConvertToTypeCode` is called.  This boolean annotation
+    specifies that the handling of ``None`` will be left to the
+    :directive:`%ConvertToTypeCode`.
+
+
+.. mapped-type-annotation:: API
+
+    .. versionadded:: 4.9
+
+    This API range annotation is used to specify an API and corresponding
+    range of version numbers that the mapped type is enabled for.
+
+    If a class or mapped type has different implementations enabled for
+    different ranges of version numbers then those ranges must not overlap.
+
+    See :ref:`ref-incompat-apis` for more detail.
+
+
+.. mapped-type-annotation:: DocType
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the name of the type as it will appear in
+    any generated docstrings.
+
+
+.. mapped-type-annotation:: NoRelease
+
+    This boolean annotation is used to specify that the mapped type does not
+    support the :cfunc:`sipReleaseType()` function.  Any
+    :directive:`%ConvertToTypeCode` should not create temporary instances of
+    the mapped type, i.e. it should not return :cmacro:`SIP_TEMPORARY`.
+
+
+.. _ref-enum-annos:
+
+Enum Annotations
+----------------
+
+.. enum-annotation:: PyName
+
+    This name annotation specifies an alternative name for the enum or enum
+    member being wrapped which is used when it is referred to from Python.  It
+    is required when an enum or enum member name is the same as a Python
+    keyword.  It may also be used to avoid name clashes with other objects
+    (e.g. classes, exceptions, functions) that have the same name in the same
+    C++ scope.
+
+
+.. _ref-exception-annos:
+
+Exception Annotations
+---------------------
+
+.. exception-annotation:: Default
+
+    This boolean annotation specifies that the exception being defined will be
+    used as the default exception to be caught if a function or constructor
+    does not have a ``throw`` clause.
+
+.. exception-annotation:: PyName
+
+    This name annotation specifies an alternative name for the exception being
+    defined which is used when it is referred to from Python.  It is required
+    when an exception name is the same as a Python keyword.  It may also be
+    used to avoid name clashes with other objects (e.g. classes, enums,
+    functions) that have the same name.
+
+
+.. _ref-function-annos:
+
+Function Annotations
+--------------------
+
+.. function-annotation:: API
+
+    .. versionadded:: 4.9
+
+    This API range annotation is used to specify an API and corresponding
+    range of version numbers that the function is enabled for.
+
+    See :ref:`ref-incompat-apis` for more detail.
+
+
+.. function-annotation:: AutoGen
+
+    This optional name annotation is used with class methods to specify that
+    the method be automatically included in all sub-classes.  The value is the
+    name of a feature (specified using the :directive:`%Feature` directive)
+    which must be enabled for the method to be generated.
+
+
+.. function-annotation:: Default
+
+    This boolean annotation is only used with C++ constructors.  Sometimes SIP
+    needs to create a class instance.  By default it uses a constructor with no
+    compulsory arguments if one is specified.  (SIP will automatically generate
+    a constructor with no arguments if no constructors are specified.)  This
+    annotation is used to explicitly specify which constructor to use.  Zero is
+    passed as the value of any arguments to the constructor.
+
+
+.. function-annotation:: Deprecated
+
+    This boolean annotation is used to specify that the constructor or function
+    is deprecated.  A deprecation warning is issued whenever the constructor or
+    function is called.
+
+
+.. function-annotation:: DocType
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the name of the type of the returned value
+    as it will appear in any generated docstrings.  It is usually used with
+    values of type :stype:`SIP_PYOBJECT` to provide a more specific type.
+
+
+.. function-annotation:: Factory
+
+    This boolean annotation specifies that the value returned by the function
+    (which should be a wrapped C structure or C++ class instance) is a newly
+    created instance and is owned by Python.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. function-annotation:: HoldGIL
+
+    This boolean annotation specifies that the Python Global Interpreter Lock
+    (GIL) is not released before the call to the underlying C or C++ function.
+    See :ref:`ref-gil` and the :fanno:`ReleaseGIL` annotation.
+
+
+.. function-annotation:: KeywordArgs
+
+    .. versionadded:: 4.10
+
+    This boolean annotation specifies that the argument parser generated for
+    this function will support passing the parameters using Python's keyword
+    argument syntax.  Keyword arguments cannot be used for functions that have
+    unnamed arguments or use an ellipsis to designate that the function has a
+    variable number of arguments.
+
+
+.. function-annotation:: __len__
+
+    .. versionadded:: 4.10.3
+
+    This boolean annotation specifies that a ``__len__()`` method should be
+    automatically generated that will use the method being annotated to compute
+    the value that the ``__len__()`` method will return.
+
+
+.. function-annotation:: NewThread
+
+    This boolean annotation specifies that the function will create a new
+    thread.
+
+
+.. function-annotation:: NoArgParser
+
+    This boolean annotation is used with methods and global functions to
+    specify that the supplied :directive:`%MethodCode` will handle the parsing
+    of the arguments.
+
+
+.. function-annotation:: NoCopy
+
+    .. versionadded:: 4.10.1
+
+    This boolean annotation is used with methods and global functions that
+    return a ``const`` reference to a class.  Normally, if the class defines a
+    copy constructor then a copy of the returned reference is automatically
+    created and wrapped.  The copy will be owned by Python.
+    
+    If the annotation is specified then the copy is not made and the original
+    reference is wrapped instead and will be owned by C++.
+
+
+.. function-annotation:: NoDerived
+
+    This boolean annotation is only used with C++ constructors.  In many cases
+    SIP generates a derived class for each class being wrapped (see
+    :ref:`ref-derived-classes`).  This derived class contains constructors with
+    the same C++ signatures as the class being wrapped.  Sometimes you may want
+    to define a Python constructor that has no corresponding C++ constructor.
+    This annotation is used to suppress the generation of the constructor in
+    the derived class.
+
+
+.. function-annotation:: NoKeywordArgs
+
+    .. versionadded:: 4.10
+
+    This boolean annotation specifies that the argument parser generated for
+    this function will not support passing the parameters using Python's
+    keyword argument syntax.  In other words, the argument parser will only
+    support only normal positional arguments.  This annotation is useful when
+    the default setting of allowing keyword arguments has been changed via the
+    command line, but you would still like certain functions to only support
+    positional arguments.
+
+
+.. function-annotation:: Numeric
+
+    This boolean annotation specifies that the operator should be interpreted
+    as a numeric operator rather than a sequence operator.  Python uses the
+    ``+`` operator for adding numbers and concatanating sequences, and the
+    ``*`` operator for multiplying numbers and repeating sequences.  SIP tries
+    to work out which is meant by looking at other operators that have been
+    defined for the type.  If it finds either ``-``, ``-=``, ``/``, ``/=``,
+    ``%`` or ``%=`` defined then it assumes that ``+``, ``+=``, ``*`` and
+    ``*=`` should be numeric operators.  Otherwise, if it finds either ``[]``,
+    :meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` defined
+    then it assumes that they should be sequence operators.  This annotation is
+    used to force SIP to treat the operator as numeric.
+
+
+.. function-annotation:: PostHook
+
+    This name annotation is used to specify the name of a Python builtin that
+    is called immediately after the call to the underlying C or C++ function or
+    any handwritten code.  The builtin is not called if an error occurred.  It
+    is primarily used to integrate with debuggers.
+
+
+.. function-annotation:: PreHook
+
+    This name annotation is used to specify the name of a Python builtin that
+    is called immediately after the function's arguments have been successfully
+    parsed and before the call to the underlying C or C++ function or any
+    handwritten code.  It is primarily used to integrate with debuggers.
+
+
+.. function-annotation:: PyName
+
+    This name annotation specifies an alternative name for the function being
+    wrapped which is used when it is referred to from Python.  It is required
+    when a function or method name is the same as a Python keyword.  It may
+    also be used to avoid name clashes with other objects (e.g. classes, enums,
+    exceptions) that have the same name in the same C++ scope.
+
+
+.. function-annotation:: ReleaseGIL
+
+    This boolean annotation specifies that the Python Global Interpreter Lock
+    (GIL) is released before the call to the underlying C or C++ function and
+    reacquired afterwards.  It should be used for functions that might block or
+    take a significant amount of time to execute.  See :ref:`ref-gil` and the
+    :fanno:`HoldGIL` annotation.
+
+
+.. function-annotation:: Transfer
+
+    This boolean annotation specifies that ownership of the value returned by
+    the function (which should be a wrapped C structure or C++ class instance)
+    is transferred to C++.  It is only used in the context of a class
+    constructor or a method.
+
+    In the case of methods returned values (unless they are new references to
+    already wrapped values) are normally owned by C++ anyway.  However, in
+    addition, an association between the returned value and the instance
+    containing the method is created with regard to the cyclic garbage
+    collector.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. function-annotation:: TransferBack
+
+    This boolean annotation specifies that ownership of the value returned by
+    the function (which should be a wrapped C structure or C++ class instance)
+    is transferred back to Python from C++.  Normally returned values (unless
+    they are new references to already wrapped values) are owned by C++.  In
+    addition, any association of the returned value with regard to the cyclic
+    garbage collector with another instance is removed.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. function-annotation:: TransferThis
+
+    This boolean annotation specifies that ownership of ``this`` is transferred
+    from Python to C++.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. _ref-license-annos:
+
+License Annotations
+-------------------
+
+.. license-annotation:: Licensee
+
+    This optional string annotation specifies the license's licensee.  No
+    restrictions are placed on the contents of the string.
+
+    See the :directive:`%License` directive.
+
+
+.. license-annotation:: Signature
+
+    This optional string annotation specifies the license's signature.  No
+    restrictions are placed on the contents of the string.
+
+    See the :directive:`%License` directive.
+
+
+.. license-annotation:: Timestamp
+
+    This optional string annotation specifies the license's timestamp.  No
+    restrictions are placed on the contents of the string.
+
+    See the :directive:`%License` directive.
+
+
+.. license-annotation:: Type
+
+    This string annotation specifies the license's type.  No restrictions are
+    placed on the contents of the string.
+
+    See the :directive:`%License` directive.
+
+
+.. _ref-typedef-annos:
+
+Typedef Annotations
+-------------------
+
+.. typedef-annotation:: NoTypeName
+
+    This boolean annotation specifies that the definition of the type rather
+    than the name of the type being defined should be used in the generated
+    code.
+
+    Normally a typedef would be defined as follows::
+
+        typedef bool MyBool;
+
+    This would result in ``MyBool`` being used in the generated code.
+
+    Specifying the annotation means that ``bool`` will be used in the generated
+    code instead.
+
+
+.. _ref-variable-annos:
+
+Variable Annotations
+--------------------
+
+.. variable-annotation:: DocType
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the name of the type of the variable as it
+    will appear in any generated docstrings.  It is usually used with variables
+    of type :stype:`SIP_PYOBJECT` to provide a more specific type.
+
+
+.. variable-annotation:: PyName
+
+    This name annotation specifies an alternative name for the variable being
+    wrapped which is used when it is referred to from Python.  It is required
+    when a variable name is the same as a Python keyword.  It may also be used
+    to avoid name clashes with other objects (e.g. classes, functions) that
+    have the same name in the same C++ scope.
diff --git a/sphinx/build_system.rst b/sphinx/build_system.rst
new file mode 100644
index 0000000..292836a
--- /dev/null
+++ b/sphinx/build_system.rst
@@ -0,0 +1,843 @@
+.. _ref-build-system:
+
+The Build System
+================
+
+.. module:: sipconfig
+
+The purpose of the build system is to make it easy for you to write
+configuration scripts in Python for your own bindings.  The build system takes
+care of the details of particular combinations of platform and compiler.  It
+supports over 50 different platform/compiler combinations.
+
+The build system is implemented as a pure Python module called :mod:`sipconfig`
+that contains a number of classes and functions.  Using this module you can
+write bespoke configuration scripts (e.g. PyQt's ``configure.py``) or use it
+with other Python based build systems (e.g.
+`Distutils <http://www.python.org/sigs/distutils-sig/distutils.html>`_ and
+`SCons <http://www.scons.org>`_).
+
+An important feature of SIP is the ability to generate bindings that are built
+on top of existing bindings.  For example, both
+`PyKDE <http://www.riverbankcomputing.com/software/pykde/>`_ and
+`PyQwt <http://pyqwt.sourceforge.net/>`_ are built on top of PyQt but all three
+packages are maintained by different developers.  To make this easier PyQt
+includes its own configuration module, ``pyqtconfig``, that contains additional
+classes intended to be used by the configuration scripts of bindings built on
+top of PyQt.  The SIP build system includes facilities that do a lot of the
+work of creating these additional configuration modules.
+
+
+.. function:: create_config_module(module, template, content[, macros=None])
+
+    This creates a configuration module (e.g. ``pyqtconfig``) from a template
+    file and a string.
+
+    :param module:
+        the name of the configuration module file to create.
+    :param template:
+        the name of the template file.
+    :param content:
+        a string which replaces every occurence of the pattern
+        ``@SIP_CONFIGURATION@`` in the template file.  The content string is
+        usually created from a Python dictionary using
+        :func:`sipconfig.create_content()`.  *content* may also be a
+        dictionary, in which case :func:`sipconfig.create_content()` is
+        automatically called to convert it to a string.
+    :param macros:
+        an optional dictionary of platform specific build macros.  It is only
+        used if :func:`sipconfig.create_content()` is called automatically to
+        convert a *content* dictionary to a string.
+
+
+.. function:: create_content(dict[, macros=None]) -> string
+
+    This converts a Python dictionary to a string that can be parsed by the
+    Python interpreter and converted back to an equivalent dictionary.  It is
+    typically used to generate the content string for
+    :func:`sipconfig.create_config_module()`.
+
+    :param dict:
+        the Python dictionary to convert.
+    :param macros:
+        the optional dictionary of platform specific build macros.
+    :return:
+        the string representation of the dictionary.
+
+
+.. function:: create_wrapper(script, wrapper[, gui=0[, use_arch='']]) -> string
+
+    This creates a platform dependent executable wrapper around a Python
+    script.
+
+    :param script:
+        the full pathname of the script.
+    :param wrapper:
+        the full pathname of the wrapper to create, excluding any platform
+        specific extension.
+    :param gui:
+        is non-zero if a GUI enabled version of the interpreter should be used
+        on platforms that require it.
+    :param use_arch:
+        is the MacOS/X architecture to invoke python with.
+    :return:
+        the platform specific name of the wrapper.
+
+
+.. function:: error(msg)
+
+    This displays an error message on ``stderr`` and calls ``sys.exit(1)``.
+
+    :param msg:
+        the text of the message and should not include any newline characters.
+
+
+.. function:: format(msg[, leftmargin=0[, rightmargin=78]]) -> string
+
+    This formats a message by inserting newline characters at appropriate
+    places.
+
+    :param msg:
+        the text of the message and should not include any newline characters.
+    :param leftmargin:
+        the optional position of the left margin.
+    :param rightmargin:
+        the optional position of the right margin.
+    :return:
+        the formatted message.
+
+
+.. function:: inform(msg)
+
+    This displays an information message on ``stdout``.
+
+    :param msg:
+        the text of the message and should not include any newline characters.
+
+
+.. function:: parse_build_macros(filename, names[, overrides=None[, properties=None]]) -> dict
+
+    This parses a ``qmake`` compatible file of build system macros and converts
+    it to a dictionary.  A macro is a name/value pair.  Individual macros may
+    be augmented or replaced.
+
+    :param filename:
+        the name of the file to parse.
+    :param names:
+        the list of the macro names to extract from the file.
+    :param overrides:
+        the optional list of macro names and values that modify those found in
+        the file.  They are of the form ``name=value`` (in which case the value
+        replaces the value found in the file) or ``name+=value`` (in which case
+        the value is appended to the value found in the file).
+    :param properties:
+        the optional dictionary of property name and values that are used to
+        resolve any expressions of the form ``$[name]`` in the file.
+    :return:
+        the dictionary of parsed macros or ``None`` if any of the overrides
+        were invalid.
+
+
+.. function:: read_version(filename, description[, numdefine=None[, strdefine=None]]) -> integer, string
+
+    This extracts version information for a package from a file, usually a C or
+    C++ header file.  The version information must each be specified as a
+    ``#define`` of a numeric (hexadecimal or decimal) value and/or a string
+    value.
+
+    :param filename:
+        the name of the file to read.
+    :param description:
+        a descriptive name of the package used in error messages.
+    :param numdefine:
+        the optional name of the ``#define`` of the version as a number.  If it
+        is ``None`` then the numeric version is ignored.
+    :param strdefine:
+        the optional name of the ``#define`` of the version as a string.  If it
+        is ``None`` then the string version is ignored.
+    :return:
+        a tuple of the numeric and string versions.  :func:`sipconfig.error()`
+        is called if either were required but could not be found.
+
+
+.. function:: version_to_sip_tag(version, tags, description) -> string
+
+    This converts a version number to a SIP version tag.  SIP uses the
+    :directive:`%Timeline` directive to define the chronology of the different
+    versions of the C/C++ library being wrapped.  Typically it is not necessary
+    to define a version tag for every version of the library, but only for
+    those versions that affect the library's API as SIP sees it.
+
+    :param version:
+        the numeric version number of the C/C++ library being wrapped.  If it
+        is negative then the latest version is assumed.  (This is typically
+        useful if a snapshot is indicated by a negative version number.)
+    :param tags:
+        the dictionary of SIP version tags keyed by the corresponding C/C++
+        library version number.  The tag used is the one with the smallest key
+        (i.e. earliest version) that is greater than *version*.
+    :param description:
+        a descriptive name of the C/C++ library used in error messages.
+    :return:
+        the SIP version tag.  :func:`sipconfig.error()` is called if the C/C++
+        library version number did not correspond to a SIP version tag.
+
+
+.. function:: version_to_string(v) -> string
+
+    This converts a 3 part version number encoded as a hexadecimal value to a
+    string.
+
+    :param v:
+        the version number.
+    :return:
+        a string.
+
+
+.. class:: Configuration
+
+    This class encapsulates configuration values that can be accessed as
+    instance objects.  A sub-class may provide a dictionary of additional
+    configuration values in its constructor the elements of which will have
+    precedence over the super-class's values.
+
+    The following configuration values are provided:
+
+    .. attribute:: default_bin_dir
+
+        The name of the directory where executables should be installed by
+        default.
+
+    .. attribute:: default_mod_dir
+
+        The name of the directory where SIP generated modules should be
+        installed by default.
+
+    .. attribute:: default_sip_dir
+
+        The name of the base directory where the ``.sip`` files for SIP
+        generated modules should be installed by default.  A sub-directory with
+        the same name as the module should be created and its ``.sip`` files
+        should be installed in the sub-directory.  The ``.sip`` files only need
+        to be installed if you might want to build other bindings based on
+        them.
+
+    .. attribute:: platform
+
+        The name of the platform/compiler for which the build system has been
+        configured for.
+
+    .. attribute:: py_conf_inc_dir
+
+        The name of the directory containing the ``pyconfig.h`` header file.
+
+    .. attribute:: py_inc_dir
+
+        The name of the directory containing the ``Python.h`` header file.
+
+    .. attribute:: py_lib_dir
+
+        The name of the directory containing the Python interpreter library.
+
+    .. attribute:: py_version
+
+        The Python version as a 3 part hexadecimal number (e.g. v2.3.3 is
+        represented as ``0x020303``).
+
+    .. attribute:: sip_bin
+
+        The full pathname of the SIP executable.
+
+    .. attribute:: sip_config_args
+
+        The command line passed to ``configure.py`` when SIP was configured.
+
+    .. attribute:: sip_inc_dir
+
+        The name of the directory containing the ``sip.h`` header file.
+
+    .. attribute:: sip_mod_dir
+
+        The name of the directory containing the SIP module.
+
+    .. attribute:: sip_version
+
+        The SIP version as a 3 part hexadecimal number (e.g. v4.0.0 is
+        represented as ``0x040000``).
+
+    .. attribute:: sip_version_str
+
+        The SIP version as a string.  For development snapshots it will start
+        with ``snapshot-``.
+
+    .. attribute:: universal
+
+        The name of the MacOS/X SDK used when creating universal binaries.
+
+    .. attribute:: arch
+
+        The space separated MacOS/X architectures to build.
+
+    .. method:: __init__([sub_cfg=None])
+
+        :param sub_cfg:
+            an optional list of sub-class configurations.  It should only be
+            used by the ``__init__()`` method of a sub-class to append its own
+            dictionary of configuration values before passing the list to its
+            super-class.
+
+    .. method:: build_macros() -> dict
+
+        Get the dictionary of platform specific build macros.
+
+        :return:
+            the macros dictionary.
+
+    .. method:: set_build_macros(macros)
+
+        Set the dictionary of platform specific build macros to be used when
+        generating Makefiles.  Normally there is no need to change the default
+        macros.
+
+        :param macros:
+            the macros dictionary.
+
+
+.. class:: Makefile
+
+    This class encapsulates a Makefile.  It is intended to be sub-classed to
+    generate Makefiles for particular purposes.  It handles all platform and
+    compiler specific flags, but allows them to be adjusted to suit the
+    requirements of a particular module or program.  These are defined using a
+    number of macros which can be accessed as instance attributes.
+
+    The following instance attributes are provided to help in fine tuning the
+    generated Makefile:
+
+    .. attribute:: chkdir
+
+        A string that will check for the existence of a directory.
+
+    .. attribute:: config
+
+        A reference to the *configuration* argument that was passed to
+        :meth:`Makefile.__init__`.
+
+    .. attribute:: console
+
+        A reference to the *console* argument that was passed to the
+        :meth:`Makefile.__init__`.
+
+    .. attribute:: copy
+
+        A string that will copy a file.
+
+    .. attribute:: extra_cflags
+
+        A list of additional flags passed to the C compiler.
+
+    .. attribute:: extra_cxxflags
+
+        A list of additional flags passed to the C++ compiler.
+
+    .. attribute:: extra_defines
+
+        A list of additional macro names passed to the C/C++ preprocessor.
+
+    .. attribute:: extra_include_dirs
+
+        A list of additional include directories passed to the C/C++
+        preprocessor.
+
+    .. attribute:: extra_lflags
+
+        A list of additional flags passed to the linker.
+
+    .. attribute:: extra_lib_dirs
+
+        A list of additional library directories passed to the linker.
+
+    .. attribute:: extra_libs
+
+        A list of additional libraries passed to the linker.  The names of the
+        libraries must be in platform neutral form (i.e. without any platform
+        specific prefixes, version numbers or extensions).
+
+    .. attribute:: generator
+
+        A string that defines the platform specific style of Makefile.  The
+        only supported values are ``UNIX``, ``MSVC``, ``MSVC.NET``, ``MINGW``
+        and ``BMAKE``.
+
+    .. attribute:: mkdir
+
+        A string that will create a directory.
+
+    .. attribute:: rm
+
+        A string that will remove a file.
+
+    .. method:: __init__(configuration[, console=0[, qt=0[, opengl=0[, python=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, universal=None[, arch=None]]]]]]]]]]]])
+
+        :param configuration:
+            the current configuration and is an instance of the
+            :class:`Configuration` class or a sub-class.
+        :param console:
+            is set if the target is a console (rather than GUI) target.  This
+            only affects Windows and is ignored on other platforms.
+        :param qt:
+            is set if the target uses Qt.  For Qt v4 a list of Qt libraries may
+            be specified and a simple non-zero value implies QtCore and QtGui.
+        :param opengl:
+            is set if the target uses OpenGL.
+        :param python:
+            is set if the target uses Python.h.
+        :param threaded:
+            is set if the target requires thread support.  It is set
+            automatically if the target uses Qt and Qt has thread support
+            enabled.
+        :param warnings:
+            is set if compiler warning messages should be enabled.  The default
+            of ``None`` means that warnings are enabled for SIP v4.x and
+            disabled for SIP v3.x.
+        :param debug:
+            is set if debugging symbols should be generated.
+        :param dir:
+            the name of the directory where build files are read from (if they
+            are not absolute file names) and Makefiles are written to.  The
+            default of ``None`` means the current directory is used.
+        :param makefile:
+            the name of the generated Makefile.
+        :param installs:
+            the list of extra install targets.  Each element is a two part
+            list, the first of which is the source and the second is the
+            destination.  If the source is another list then it is a list of
+            source files and the destination is a directory.
+        :param universal:
+            the name of the SDK if universal binaries are to be created under
+            MacOS/X.  If it is ``None`` then the value is taken from the
+            configuration.
+        :param arch:
+            the space separated MacOS/X architectures to build.  If it is
+            ``None`` then the value is taken from the configuration.
+
+    .. method:: clean_build_file_objects(mfile, build)
+
+        This generates the Makefile commands that will remove any files
+        generated during the build of the default target.
+
+        :param mfile:
+            the Python file object of the Makefile.
+        :param build:
+            the dictionary created from parsing the build file.
+
+    .. method:: finalise()
+
+        This is called just before the Makefile is generated to ensure that it
+        is fully configured.  It must be reimplemented by a sub-class.
+
+    .. method:: generate()
+
+        This generates the Makefile.
+
+    .. method:: generate_macros_and_rules(mfile)
+
+        This is the default implementation of the Makefile macros and rules
+        generation.
+
+        :param mfile:
+            the Python file object of the Makefile.
+
+    .. method:: generate_target_clean(mfile)
+
+        This is the default implementation of the Makefile clean target
+        generation.
+
+        :param mfile:
+            the Python file object of the Makefile.
+
+    .. method:: generate_target_default(mfile)
+
+        This is the default implementation of the Makefile default target
+        generation.
+
+        :param mfile:
+            the Python file object of the Makefile.
+
+    .. method:: generate_target_install(mfile)
+
+        This is the default implementation of the Makefile install target
+        generation.
+
+        :param mfile:
+            the Python file object of the Makefile.
+
+    .. method:: install_file(mfile, src, dst[, strip=0])
+
+        This generates the Makefile commands to install one or more files to a
+        directory.
+
+        :param mfile:
+            the Python file object of the Makefile.
+        :param src:
+            the name of a single file to install or a list of a number of files
+            to install.
+        :param dst:
+            the name of the destination directory.
+        :param strip:
+            is set if the files should be stripped of unneeded symbols after
+            having been installed.
+
+    .. method:: optional_list(name) -> list
+
+        This returns an optional Makefile macro as a list.
+
+        :param name:
+            the name of the macro.
+        :return:
+            the macro as a list.
+
+    .. method:: optional_string(name[, default=""])
+
+        This returns an optional Makefile macro as a string.
+
+        :param name:
+            the name of the macro.
+        :param default:
+            the optional default value of the macro.
+        :return:
+            the macro as a string.
+
+    .. method:: parse_build_file(filename) -> dict
+
+        This parses a build file (created with the :option:`-b <sip -b>` SIP
+        command line option) and converts it to a dictionary.  It can also
+        validate an existing dictionary created through other means.
+
+        :param filename: is the name of the build file, or is a dictionary to
+            be validated.  A valid dictionary will contain the name of the
+            target to build (excluding any platform specific extension) keyed
+            by ``target``; the names of all source files keyed by ``sources``;
+            and, optionally, the names of all header files keyed by
+            ``headers``.
+        :return:
+            a dictionary corresponding to the parsed build file.
+
+    .. method:: platform_lib(clib[, framework=0]) -> string
+
+        This converts a library name to a platform specific form.
+
+        :param clib:
+            the name of the library in cannonical form.
+        :param framework:
+            is set if the library is implemented as a MacOS framework.
+        :return:
+            the platform specific name.
+
+    .. method:: ready()
+
+        This is called to ensure that the Makefile is fully configured.  It is
+        normally called automatically when needed.
+
+    .. method:: required_string(name) -> string
+
+        This returns a required Makefile macro as a string.
+
+        :param name:
+            the name of the macro.
+        :return:
+            the macro as a string.  An exception is raised if the macro does
+            not exist or has an empty value.
+
+
+.. class:: ModuleMakefile
+
+    This class is derived from :class:`sipconfig.Makefile`.
+
+    This class encapsulates a Makefile to build a generic Python extension
+    module.
+
+    .. method:: __init__(self, configuration, build_file[, install_dir=None[, static=0[, console=0[, opengl=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, strip=1[, export_all=0[, universal=None[, arch=None]]]]]]]]]]]]]])
+
+        :param configuration:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param build_file:
+            the name of the build file.  Build files are generated using the
+            :option:`-b <sip -b>` SIP command line option.
+        :param install_dir:
+            the name of the directory where the module will be optionally
+            installed.
+        :param static:
+            is set if the module should be built as a static library (see
+            :ref:`ref-builtin`).
+        :param console:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param qt:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param opengl:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param threaded:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param warnings:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param debug:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param dir:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param makefile:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param installs:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param strip:
+            is set if the module should be stripped of unneeded symbols after
+            installation.  It is ignored if either *debug* or *static* is set,
+            or if the platform doesn't support it.
+        :param export_all:
+            is set if all of the module's symbols should be exported rather
+            than just the module's initialisation function.  Exporting all
+            symbols increases the size of the module and slows down module load
+            times but may avoid problems with modules that use C++ exceptions.
+            All symbols are exported if either *debug* or *static* is set, or
+            if the platform doesn't support it.
+        :param universal:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param arch:
+            see :meth:`sipconfig.Makefile.__init__`.
+
+    .. method:: finalise()
+
+        This is a reimplementation of :meth:`sipconfig.Makefile.finalise`.
+
+    .. method:: generate_macros_and_rules(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_macros_and_rules`.
+
+    .. method:: generate_target_clean(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_clean`.
+
+    .. method:: generate_target_default(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_default`.
+
+    .. method:: generate_target_install(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_install`.
+
+    .. method:: module_as_lib(mname) -> string
+
+        This gets the name of a SIP v3.x module for when it is used as a
+        library to be linked against.  An exception will be raised if it is
+        used with SIP v4.x modules.
+
+        :param mname:
+            the name of the module.
+        :return:
+            the corresponding library name.
+
+
+.. class:: ParentMakefile
+
+    This class is derived from :class:`sipconfig.Makefile`.
+
+    This class encapsulates a Makefile that sits above a number of other
+    Makefiles in sub-directories.
+
+    .. method:: __init__(self, configuration, subdirs[, dir=None[, makefile[="Makefile"[, installs=None]]]])
+
+        :param configuration:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param subdirs:
+            the sequence of sub-directories.
+        :param dir:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param makefile:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param installs:
+            see :meth:`sipconfig.Makefile.__init__`.
+
+    .. method:: generate_macros_and_rules(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_macros_and_rules`.
+
+    .. method:: generate_target_clean(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_clean`.
+
+    .. method:: generate_target_default(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_default`.
+
+    .. method:: generate_target_install(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_install`.
+
+.. class:: ProgramMakefile
+
+    This class is derived from :class:`sipconfig.Makefile`.
+
+    This class encapsulates a Makefile to build an executable program.
+
+    .. method:: __init__(configuration[, build_file=None[, install_dir=None[, console=0[, qt=0[, opengl=0[, python=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, universal=None[, arch=None]]]]]]]]]]]]]])
+
+        :param configuration:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param build_file:
+            the name of the optional build file.  Build files are generated
+            using the :option:`-b <sip -b>` SIP command line option.
+        :param install_dir:
+            the name of the directory where the executable program will be
+            optionally installed.
+        :param console:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param qt:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param opengl:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param python:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param threaded:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param warnings:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param debug:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param dir:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param makefile:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param installs:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param universal:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param arch:
+            see :meth:`sipconfig.Makefile.__init__`.
+
+    .. method:: build_command(source) -> string, string
+
+        This creates a single command line that will create an executable
+        program from a single source file.
+
+        :param source:
+            the name of the source file.
+        :return:
+            a tuple of the name of the executable that will be created and the
+            command line.
+
+    .. method:: finalise()
+
+        This is a reimplementation of :meth:`sipconfig.Makefile.finalise`.
+
+    .. method:: generate_macros_and_rules(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_macros_and_rules`.
+
+    .. method:: generate_target_clean(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_clean`.
+
+    .. method:: generate_target_default(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_default`.
+
+    .. method:: generate_target_install(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_install`.
+
+
+.. class:: PythonModuleMakefile
+
+    This class is derived from :class:`sipconfig.Makefile`.
+
+    This class encapsulates a Makefile that installs a pure Python module.
+
+    .. method:: __init__(self, configuration, dstdir[, srcdir=None[, dir=None[, makefile="Makefile"[, installs=None]]]])
+
+        :param configuration:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param dstdir:
+            the name of the directory in which the module's Python code will be
+            installed.
+        :param srcdir:
+            the name of the directory (relative to *dir*) containing the
+            module's Python code.  It defaults to the same directory.
+        :param dir:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param makefile:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param installs:
+            see :meth:`sipconfig.Makefile.__init__`.
+
+    .. method:: generate_macros_and_rules(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_macros_and_rules`.
+
+    .. method:: generate_target_install(mfile)
+
+        This is a reimplementation of
+        :meth:`sipconfig.Makefile.generate_target_install`.
+
+
+.. class:: SIPModuleMakefile
+
+    This class is derived from :class:`sipconfig.ModuleMakefile`.
+
+    This class encapsulates a Makefile to build a SIP generated Python
+    extension module.
+
+    .. method:: __init__(self, configuration, build_file[, install_dir=None[, static=0[, console=0[, opengl=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, strip=1[, export_all=0[, universal=None[, arch=None[, prot_is_public=0]]]]]]]]]]]]]]])
+
+        :param configuration:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param build_file:
+            see :meth:`sipconfig.ModuleMakefile.__init__`.
+        :param install_dir:
+            see :meth:`sipconfig.ModuleMakefile.__init__`.
+        :param static:
+            see :meth:`sipconfig.ModuleMakefile.__init__`.
+        :param console:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param qt:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param opengl:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param threaded:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param warnings:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param debug:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param dir:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param makefile:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param installs:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param strip:
+            see :meth:`sipconfig.ModuleMakefile.__init__`.
+        :param export_all:
+            see :meth:`sipconfig.ModuleMakefile.__init__`.
+        :param universal:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param arch:
+            see :meth:`sipconfig.Makefile.__init__`.
+        :param prot_is_public:
+            is set if ``protected`` should be redefined as ``public`` when
+            compiling the generated module.
+
+    .. method:: finalise()
+
+        This is a reimplementation of :meth:`sipconfig.Makefile.finalise`.
diff --git a/sphinx/builtin.rst b/sphinx/builtin.rst
new file mode 100644
index 0000000..58c7019
--- /dev/null
+++ b/sphinx/builtin.rst
@@ -0,0 +1,50 @@
+.. _ref-builtin:
+
+Builtin Modules and Custom Interpreters
+=======================================
+
+Sometimes you want to create a custom Python interpreter with some modules
+built in to the interpreter itself rather than being dynamically loaded.  To
+do this the module must be created as a static library and linked with a
+custom stub and the normal Python library.
+
+To build the SIP module as a static library you must pass the ``-k`` command
+line option to ``configure.py``.  You should then build and install SIP as
+normal.  (Note that, because the module is now a static library, you will not
+be able to import it.)
+
+To build a module you have created for your own library you must modify your
+own configuration script to pass a non-zero value as the ``static`` argument
+of the ``__init__()`` method of the :class:`sipconfig.ModuleMakefile` class (or
+any derived class you have created).  Normally you would make this configurable
+using a command line option in the same way that SIP's ``configure.py`` handles
+it.
+
+The next stage is to create a custom stub and a Makefile.  The SIP distribution
+contains a directory called ``custom`` which contains example stubs and a
+Python script that will create a correct Makefile.  Note that, if your copy of
+SIP was part of a standard Linux distribution, the ``custom`` directory may
+not be installed on your system.
+
+The ``custom`` directory contains the following files.  They are provided as
+examples - each needs to be modified according to your particular
+requirements.
+
+    - ``mkcustom.py`` is a Python script that will create a Makefile which is
+      then used to build the custom interpreter.  Comments in the file describe
+      how it should be modified.
+
+    - ``custom.c`` is a stub for a custom interpreter on Linux/UNIX.  It
+      should also be used for a custom console interpreter on Windows (i.e.
+      like ``python.exe``).  Comments in the file describe how it should be
+      modified.
+
+    - ``customw.c`` is a stub for a custom GUI interpreter on Windows (i.e.
+      like ``pythonw.exe``).  Comments in the file describe how it should be
+      modified.
+
+Note that this technique does not restrict how the interpreter can be used.
+For example, it still allows users to write their own applications that can
+import your builtin modules.  If you want to prevent users from doing that,
+perhaps to protect a proprietary API, then take a look at the
+`VendorID <http://www.riverbankcomputing.com/software/vendorid/>`__ package.
diff --git a/sphinx/c_api.rst b/sphinx/c_api.rst
new file mode 100644
index 0000000..782056c
--- /dev/null
+++ b/sphinx/c_api.rst
@@ -0,0 +1,1721 @@
+.. _ref-c-api:
+
+C API for Handwritten Code
+==========================
+
+In this section we describe the API that can be used by handwritten code in
+specification files.
+
+
+.. cmacro:: SIP_API_MAJOR_NR
+
+    This is a C preprocessor symbol that defines the major number of the SIP
+    API.  Its value is a number.  There is no direct relationship between this
+    and the SIP version number.
+
+
+.. cmacro:: SIP_API_MINOR_NR
+
+    This is a C preprocessor symbol that defines the minor number of the SIP
+    API.  Its value is a number.  There is no direct relationship between this
+    and the SIP version number.
+
+
+.. cmacro:: SIP_BLOCK_THREADS
+
+    This is a C preprocessor macro that will make sure the Python Global
+    Interpreter Lock (GIL) is acquired.  Python API calls must only be made
+    when the GIL has been acquired.  There must be a corresponding
+    :cmacro:`SIP_UNBLOCK_THREADS` at the same lexical scope.
+
+
+.. cmacro:: SIP_NO_CONVERTORS
+
+    This is a flag used by various type convertors that suppresses the use of a
+    type's :directive:`%ConvertToTypeCode`.
+
+
+.. cmacro:: SIP_NOT_NONE
+
+    This is a flag used by various type convertors that causes the conversion
+    to fail if the Python object being converted is ``Py_None``.
+
+
+.. cmacro:: SIP_PROTECTED_IS_PUBLIC
+
+    .. versionadded:: 4.10
+
+    This is a C preprocessor macro that is set automatically by the build
+    system to specify that the generated code is being compiled with
+    ``protected`` redefined as ``public``.  This allows handwritten code to
+    determine if the generated helper functions for accessing protected C++
+    functions are available (see :directive:`%MethodCode`).
+
+
+.. cmacro:: SIP_SSIZE_T
+
+    This is a C preprocessor macro that is defined as ``Py_ssize_t`` for Python
+    v2.5 and later, and as ``int`` for earlier versions of Python.  It makes it
+    easier to write PEP 353 compliant handwritten code.
+
+
+.. cmacro:: SIP_UNBLOCK_THREADS
+
+    This is a C preprocessor macro that will restore the Python Global
+    Interpreter Lock (GIL) to the state it was prior to the corresponding
+    :cmacro:`SIP_BLOCK_THREADS`.
+
+
+.. cmacro:: SIP_VERSION
+
+    This is a C preprocessor symbol that defines the SIP version number
+    represented as a 3 part hexadecimal number (e.g. v4.0.0 is represented as
+    ``0x040000``).
+
+
+.. cmacro:: SIP_VERSION_STR
+
+    This is a C preprocessor symbol that defines the SIP version number
+    represented as a string.  For development snapshots it will start with
+    ``snapshot-``.
+
+
+.. cfunction:: sipErrorState sipBadCallableArg(int arg_nr, PyObject *arg)
+
+    .. versionadded:: 4.10
+
+    This is called from :directive:`%MethodCode` to raise a Python exception
+    when an argument to a function, a C++ constructor or method is found to
+    have an unexpected type.  This should be used when the
+    :directive:`%MethodCode` does additional type checking of the supplied
+    arguments.
+
+    :param arg_nr:
+        the number of the argument.  Arguments are numbered from 0 but are
+        numbered from 1 in the detail of the exception.
+    :param arg:
+        the argument.
+    :return:
+        the value that should be assigned to ``sipError``.
+
+
+.. cfunction:: void sipBadCatcherResult(PyObject *method)
+
+    This raises a Python exception when the result of a Python reimplementation
+    of a C++ method doesn't have the expected type.  It is normally called by
+    handwritten code specified with the :directive:`%VirtualCatcherCode`
+    directive.
+
+    :param method:
+        the Python method and would normally be the supplied ``sipMethod``.
+
+
+.. cfunction:: void sipBadLengthForSlice(SIP_SSIZE_T seqlen, SIP_SSIZE_T slicelen)
+
+    This raises a Python exception when the length of a slice object is
+    inappropriate for a sequence-like object.  It is normally called by
+    handwritten code specified for :meth:`__setitem__` methods.
+
+    :param seqlen:
+        the length of the sequence.
+    :param slicelen:
+        the length of the slice.
+
+
+.. cfunction:: PyObject *sipBuildResult(int *iserr, const char *format, ...)
+
+    This creates a Python object based on a format string and associated
+    values in a similar way to the Python :cfunc:`Py_BuildValue()` function.
+
+    :param iserr:
+        if this is not ``NULL`` then the location it points to is set to a
+        non-zero value.
+    :param format:
+        the string of format characters.
+    :return:
+        If there was an error then ``NULL`` is returned and a Python exception
+        is raised.
+        
+    If the format string begins and ends with parentheses then a tuple of
+    objects is created.  If it contains more than one format character then
+    parentheses must be specified.
+
+    In the following description the first letter is the format character, the
+    entry in parentheses is the Python object type that the format character
+    will create, and the entry in brackets are the types of the C/C++ values
+    to be passed. 
+
+    ``a`` (string) [char]
+        Convert a C/C++ ``char`` to a Python v2 or v3 string object.
+
+    ``b`` (boolean) [int]
+        Convert a C/C++ ``int`` to a Python boolean.
+
+    ``c`` (string/bytes) [char]
+        Convert a C/C++ ``char`` to a Python v2 string object or a Python v3
+        bytes object.
+
+    ``d`` (float) [double]
+        Convert a C/C++ ``double`` to a Python floating point number.
+
+    ``e`` (integer) [enum]
+        Convert an anonymous C/C++ ``enum`` to a Python integer.
+
+    ``f`` (float) [float]
+        Convert a C/C++ ``float`` to a Python floating point number.
+
+    ``g`` (string/bytes) [char \*, :cmacro:`SIP_SSIZE_T`]
+        Convert a C/C++ character array and its length to a Python v2 string
+        object or a Python v3 bytes object.  If the array is ``NULL`` then the
+        length is ignored and the result is ``Py_None``.
+
+    ``h`` (integer) [short]
+        Convert a C/C++ ``short`` to a Python integer.
+
+    ``i`` (integer) [int]
+        Convert a C/C++ ``int`` to a Python integer.
+
+    ``l`` (long) [long]
+        Convert a C/C++ ``long`` to a Python integer.
+
+    ``m`` (long) [unsigned long]
+        Convert a C/C++ ``unsigned long`` to a Python long.
+
+    ``n`` (long) [long long]
+        Convert a C/C++ ``long long`` to a Python long.
+
+    ``o`` (long) [unsigned long long]
+        Convert a C/C++ ``unsigned long long`` to a Python long.
+
+    ``r`` (wrapped instance) [*type* \*, :cmacro:`SIP_SSIZE_T`, const :ctype:`sipTypeDef` \*]
+        Convert an array of C structures, C++ classes or mapped type instances
+        to a Python tuple.  Note that copies of the array elements are made.
+
+    ``s`` (string/bytes) [char \*]
+        Convert a C/C++ ``'\0'`` terminated string to a Python v2 string object
+        or a Python v3 bytes object.  If the string pointer is ``NULL`` then
+        the result is ``Py_None``.
+
+    ``t`` (long) [unsigned short]
+        Convert a C/C++ ``unsigned short`` to a Python long.
+
+    ``u`` (long) [unsigned int]
+        Convert a C/C++ ``unsigned int`` to a Python long.
+
+    ``w`` (unicode/string) [wchar_t]
+        Convert a C/C++ wide character to a Python v2 unicode object or a
+        Python v3 string object.
+
+    ``x`` (unicode/string) [wchar_t \*]
+        Convert a C/C++ ``L'\0'`` terminated wide character string to a Python
+        v2 unicode object or a Python v3 string object.  If the string pointer
+        is ``NULL`` then the result is ``Py_None``.
+
+    ``A`` (string) [char \*]
+        Convert a C/C++ ``'\0'`` terminated string to a Python v2 or v3 string
+        object.  If the string pointer is ``NULL`` then the result is
+        ``Py_None``.
+
+    ``B`` (wrapped instance) [*type* \*, :ctype:`sipWrapperType` \*, PyObject \*]
+        Convert a new C structure or a new C++ class instance to a Python class
+        instance object.  Ownership of the structure or instance is determined
+        by the ``PyObject *`` argument.  If it is ``NULL`` and the instance has
+        already been wrapped then the ownership is unchanged.  If it is
+        ``NULL`` or ``Py_None`` then ownership will be with Python.  Otherwise
+        ownership will be with C/C++ and the instance associated with the
+        ``PyObject *`` argument.  The Python class is influenced by any
+        applicable :directive:`%ConvertToSubClassCode` code.
+
+        .. note::
+            This is deprecated from SIP v4.8.  Instead you should use ``N``.
+
+    ``C`` (wrapped instance) [*type* \*, :ctype:`sipWrapperType` \*, PyObject \*]
+        Convert a C structure or a C++ class instance to a Python class
+        instance object.  If the structure or class instance has already been
+        wrapped then the result is a new reference to the existing class
+        instance object.  Ownership of the structure or instance is determined
+        by the ``PyObject *`` argument.  If it is ``NULL`` and the instance has
+        already been wrapped then the ownership is unchanged.  If it is
+        ``NULL`` and the instance is newly wrapped then ownership will be with
+        C/C++.  If it is ``Py_None`` then ownership is transferred to Python
+        via a call to :cfunc:`sipTransferBack()`.  Otherwise ownership is
+        transferred to C/C++ and the instance associated with the
+        ``PyObject *`` argument via a call to :cfunc:`sipTransferTo()`.  The
+        Python class is influenced by any applicable
+        :directive:`%ConvertToSubClassCode` code.
+
+        .. note::
+            This is deprecated from SIP v4.8.  Instead you should use ``D``.
+
+    ``D`` (wrapped instance) [*type* \*, const :ctype:`sipTypeDef` \*, PyObject \*]
+        Convert a C structure, C++ class or mapped type instance to a Python
+        object.  If the instance has already been wrapped then the result is a
+        new reference to the existing object.  Ownership of the instance is
+        determined by the ``PyObject *`` argument.  If it is ``NULL`` and the
+        instance has already been wrapped then the ownership is unchanged.  If
+        it is ``NULL`` and the instance is newly wrapped then ownership will be
+        with C/C++.  If it is ``Py_None`` then ownership is transferred to
+        Python via a call to :cfunc:`sipTransferBack()`.  Otherwise ownership
+        is transferred to C/C++ and the instance associated with the
+        ``PyObject *`` argument via a call to :cfunc:`sipTransferTo()`.  The
+        Python class is influenced by any applicable
+        :directive:`%ConvertToSubClassCode` code.
+
+    ``E`` (wrapped enum) [enum, PyTypeObject \*]
+        Convert a named C/C++ ``enum`` to an instance of the corresponding
+        Python named enum type.
+
+        .. note::
+            This is deprecated from SIP v4.8.  Instead you should use ``F``.
+
+    ``F`` (wrapped enum) [enum, :ctype:`sipTypeDef` \*]
+        Convert a named C/C++ ``enum`` to an instance of the corresponding
+        Python named enum type.
+
+    ``G`` (unicode) [wchar_t \*, :cmacro:`SIP_SSIZE_T`]
+        Convert a C/C++ wide character array and its length to a Python unicode
+        object.  If the array is ``NULL`` then the length is ignored and the
+        result is ``Py_None``.
+
+    ``N`` (wrapped instance) [*type* \*, :ctype:`sipTypeDef` \*, PyObject \*]
+        Convert a new C structure, C++ class or mapped type instance to a
+        Python object.  Ownership of the instance is determined by the
+        ``PyObject *`` argument.  If it is ``NULL`` and the instance has
+        already been wrapped then the ownership is unchanged.  If it is
+        ``NULL`` or ``Py_None`` then ownership will be with Python.  Otherwise
+        ownership will be with C/C++ and the instance associated with the
+        ``PyObject *`` argument.  The Python class is influenced by any
+        applicable :directive:`%ConvertToSubClassCode` code.
+
+    ``R`` (object) [PyObject \*]
+        The result is value passed without any conversions.  The reference
+        count is unaffected, i.e. a reference is taken.
+
+    ``S`` (object) [PyObject \*]
+        The result is value passed without any conversions.  The reference
+        count is incremented.
+
+    ``V`` (sip.voidptr) [void \*]
+        Convert a C/C++ ``void *`` Python :class:`sip.voidptr` object.
+
+
+.. cfunction:: PyObject *sipCallMethod(int *iserr, PyObject *method, const char *format, ...)
+
+    This calls a Python method passing a tuple of arguments based on a format
+    string and associated values in a similar way to the Python
+    :cfunc:`PyObject_CallObject()` function.
+
+    :param iserr:
+        if this is not ``NULL`` then the location it points to is set to a
+        non-zero value if there was an error.
+    :param method:
+        the Python bound method to call.
+    :param format:
+        the string of format characters (see :cfunc:`sipBuildResult()`).
+    :return:
+        If there was an error then ``NULL`` is returned and a Python exception
+        is raised.
+
+    It is normally called by handwritten code specified with the
+    :directive:`%VirtualCatcherCode` directive with method being the supplied
+    ``sipMethod``.
+
+
+.. cfunction:: int sipCanConvertToEnum(PyObject *obj, const sipTypeDef *td)
+
+    This checks if a Python object can be converted to a named enum.
+
+    :param obj:
+        the Python object.
+    :param td:
+        the enum's :ref:`generated type structure <ref-type-structures>`.
+    :return:
+        a non-zero value if the object can be converted.
+
+
+.. cfunction:: int sipCanConvertToInstance(PyObject *obj, sipWrapperType *type, int flags)
+
+    This checks if a Python object can be converted to an instance of a C
+    structure or C++ class.
+
+    :param obj:
+        the Python object.
+    :param type:
+        the C/C++ type's :ref:`generated type object <ref-type-objects>`.
+    :param flags:
+        any combination of the :cmacro:`SIP_NOT_NONE` and
+        :cmacro:`SIP_NO_CONVERTORS` flags.
+    :return:
+        a non-zero value if the object can be converted.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipCanConvertToType()`.
+
+
+.. cfunction:: int sipCanConvertToMappedType(PyObject *obj, const sipMappedType *mt, int flags)
+
+    This checks if a Python object can be converted to an instance of a C
+    structure or C++ class which has been implemented as a mapped type.
+
+    :param obj:
+        the Python object.
+    :param mt:
+        the opaque structure returned by :cfunc:`sipFindMappedType()`.
+    :param flags:
+        this may be the :cmacro:`SIP_NOT_NONE` flag.
+    :return:
+        a non-zero value if the object can be converted.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipCanConvertToType()`.
+
+
+.. cfunction:: int sipCanConvertToType(PyObject *obj, const sipTypeDef *td, int flags)
+
+    This checks if a Python object can be converted to an instance of a C
+    structure, C++ class or mapped type.
+
+    :param obj:
+        the Python object.
+    :param td:
+        the C/C++ type's :ref:`generated type structure <ref-type-structures>`.
+    :param flags:
+        any combination of the :cmacro:`SIP_NOT_NONE` and
+        :cmacro:`SIP_NO_CONVERTORS` flags.
+    :return:
+        a non-zero value if the object can be converted.
+
+
+.. cfunction:: PyObject *sipClassName(PyObject *obj)
+
+    This gets the class name of a wrapped instance as a Python string.  It
+    comes with a reference.
+
+    :param obj:
+        the wrapped instance.
+    :return:
+        the name of the instance's class.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use the
+        following::
+
+            PyString_FromString(obj->ob_type->tp_name)
+
+
+.. cfunction:: PyObject *sipConvertFromConstVoidPtr(const void *cpp)
+
+    This creates a :class:`sip.voidptr` object for a memory address.  The
+    object will not be writeable and has no associated size.
+
+    :param cpp:
+        the memory address.
+    :return:
+        the :class:`sip.voidptr` object.
+
+
+.. cfunction:: PyObject *sipConvertFromConstVoidPtrAndSize(const void *cpp, SIP_SSIZE_T size)
+
+    This creates a :class:`sip.voidptr` object for a memory address.  The
+    object will not be writeable and can be used as an immutable buffer object.
+
+    :param cpp:
+        the memory address.
+    :param size:
+        the size associated with the address.
+    :return:
+        the :class:`sip.voidptr` object.
+
+
+.. cfunction:: PyObject *sipConvertFromEnum(int eval, const sipTypeDef *td)
+
+    This converts a named C/C++ ``enum`` to an instance of the corresponding
+    generated Python type.
+
+    :param eval:
+        the enumerated value to convert.
+    :param td:
+        the enum's :ref:`generated type structure <ref-type-structures>`.
+    :return:
+        the Python object.
+
+
+.. cfunction:: PyObject *sipConvertFromInstance(void *cpp, sipWrapperType *type, PyObject *transferObj)
+
+    This converts a C structure or a C++ class instance to an instance of the
+    corresponding generated Python type.
+
+    :param cpp:
+        the C/C++ instance.
+    :param type:
+        the type's :ref:`generated type object <ref-type-objects>`.
+    :param transferObj:
+        this controls the ownership of the returned value.
+    :return:
+        the Python object.
+
+    If the C/C++ instance has already been wrapped then the result is a
+    new reference to the existing class instance object.
+    
+    If *transferObj* is ``NULL`` and the instance has already been wrapped then
+    the ownership is unchanged.
+    
+    If *transferObj* is ``NULL`` and the instance is newly wrapped then
+    ownership will be with C/C++.
+    
+    If *transferObj* is ``Py_None`` then ownership is transferred to Python via
+    a call to :cfunc:`sipTransferBack()`.
+    
+    Otherwise ownership is transferred to C/C++ and the instance associated
+    with *transferObj* via a call to :cfunc:`sipTransferTo()`.
+    
+    The Python type is influenced by any applicable
+    :directive:`%ConvertToSubClassCode` code.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipConvertFromType()`.
+
+
+.. cfunction:: PyObject *sipConvertFromMappedType(void *cpp, const sipMappedType *mt, PyObject *transferObj)
+
+    This converts a C structure or a C++ class instance wrapped as a mapped
+    type to an instance of the corresponding generated Python type.
+    
+    :param cpp:
+        the C/C++ instance.
+    :param mt:
+        the opaque structure returned by :cfunc:`sipFindMappedType()`.
+    :param transferObj:
+        this controls the ownership of the returned value.
+    :return:
+        the Python object.
+
+    If *transferObj*  is ``NULL`` then the ownership is unchanged.
+    
+    If *transferObj* is ``Py_None`` then ownership is transferred to Python
+    via a call to :cfunc:`sipTransferBack()`.
+    
+    Otherwise ownership is transferred to C/C++ and the instance associated
+    with *transferObj* argument via a call to :cfunc:`sipTransferTo()`.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipConvertFromType()`.
+
+
+.. cfunction:: PyObject *sipConvertFromNamedEnum(int eval, PyTypeObject *type)
+
+    This converts a named C/C++ ``enum`` to an instance of the corresponding
+    generated Python type.
+    
+    :param eval:
+        the enumerated value to convert.
+    :param type:
+        the enum's :ref:`generated type object <ref-type-objects>`.
+    :return:
+        the Python object.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipConvertFromEnum()`.
+
+
+.. cfunction:: PyObject *sipConvertFromNewInstance(void *cpp, sipWrapperType *type, PyObject *transferObj)
+
+    This converts a new C structure or a C++ class instance to an instance of
+    the corresponding generated Python type.
+
+    :param cpp:
+        the C/C++ instance.
+    :param type:
+        the type's :ref:`generated type object <ref-type-objects>`.
+    :param transferObj:
+        this controls the ownership of the returned value.
+    :return:
+        the Python object.
+
+    If *transferObj* is ``NULL`` or ``Py_None`` then ownership will be with
+    Python.
+    
+    Otherwise ownership will be with C/C++ and the instance associated with
+    *transferObj*.
+    
+    The Python type is influenced by any applicable
+    :directive:`%ConvertToSubClassCode` code.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipConvertFromNewType()`.
+
+
+.. cfunction:: PyObject *sipConvertFromNewType(void *cpp, const sipTypeDef *td, PyObject *transferObj)
+
+    This converts a new C structure or a C++ class instance to an instance of
+    the corresponding generated Python type.
+
+    :param cpp:
+        the C/C++ instance.
+    :param td:
+        the type's :ref:`generated type structure <ref-type-structures>`.
+    :param transferObj:
+        this controls the ownership of the returned value.
+    :return:
+        the Python object.
+
+    If *transferObj* is ``NULL`` or ``Py_None`` then ownership will be with
+    Python.
+    
+    Otherwise ownership will be with C/C++ and the instance associated with
+    *transferObj*.
+    
+    The Python type is influenced by any applicable
+    :directive:`%ConvertToSubClassCode` code.
+
+
+.. cfunction:: SIP_SSIZE_T sipConvertFromSequenceIndex(SIP_SSIZE_T idx, SIP_SSIZE_T len)
+
+    This converts a Python sequence index (i.e. where a negative value refers
+    to the offset from the end of the sequence) to a C/C++ array index.  If the
+    index was out of range then a negative value is returned and a Python
+    exception raised.
+
+    :param idx:
+        the sequence index.
+    :param len:
+        the length of the sequence.
+    :return:
+        the unsigned array index.
+
+
+.. cfunction:: int sipConvertFromSliceObject(PyObject *slice, SIP_SSIZE_T length, SIP_SSIZE_T *start, SIP_SSIZE_T *stop, SIP_SSIZE_T *step, SIP_SSIZE_T *slicelength)
+
+    This is a thin wrapper around the Python :cfunc:`PySlice_GetIndicesEx()`
+    function provided to make it easier to write handwritten code that is
+    compatible with SIP v3.x and versions of Python earlier that v2.3.
+
+
+.. cfunction:: PyObject *sipConvertFromType(void *cpp, const sipTypeDef *td, PyObject *transferObj)
+
+    This converts a C structure or a C++ class instance to an instance of the
+    corresponding generated Python type.
+
+    :param cpp:
+        the C/C++ instance.
+    :param td:
+        the type's :ref:`generated type structure <ref-type-structures>`.
+    :param transferObj:
+        this controls the ownership of the returned value.
+    :return:
+        the Python object.
+
+    If the C/C++ instance has already been wrapped then the result is a new
+    reference to the existing object.
+
+    If *transferObj* is ``NULL`` and the instance has already been wrapped then
+    the ownership is unchanged.
+    
+    If *transferObj* is ``NULL`` and the instance is newly wrapped then
+    ownership will be with C/C++.
+    
+    If *transferObj* is ``Py_None`` then ownership is transferred to Python via
+    a call to :cfunc:`sipTransferBack()`.
+    
+    Otherwise ownership is transferred to C/C++ and the instance associated
+    with *transferObj* via a call to :cfunc:`sipTransferTo()`.
+    
+    The Python class is influenced by any applicable
+    :directive:`%ConvertToSubClassCode` code.
+
+
+.. cfunction:: PyObject *sipConvertFromVoidPtr(void *cpp)
+
+    This creates a :class:`sip.voidptr` object for a memory address.  The
+    object will be writeable but has no associated size.
+
+    :param cpp:
+        the memory address.
+    :return:
+        the :class:`sip.voidptr` object.
+
+
+.. cfunction:: PyObject *sipConvertFromVoidPtrAndSize(void *cpp, SIP_SSIZE_T size)
+
+    This creates a :class:`sip.voidptr` object for a memory address.  The
+    object will be writeable and can be used as a mutable buffer object.
+    
+    :param cpp:
+        the memory address.
+    :param size:
+        the size associated with the address.
+    :return:
+        the :class:`sip.voidptr` object.
+
+
+.. cfunction:: void *sipConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr)
+
+    This converts a Python object to an instance of a C structure or C++ class
+    assuming that a previous call to :cfunc:`sipCanConvertToInstance()` has
+    been successful.
+
+    :param obj:
+        the Python object.
+    :param type:
+        the type's :ref:`generated type object <ref-type-objects>`.
+    :param transferObj:
+        this controls any ownership changes to *obj*.
+    :param flags:
+        any combination of the :cmacro:`SIP_NOT_NONE` and
+        :cmacro:`SIP_NO_CONVERTORS` flags.
+    :param state:
+        the state of the returned C/C++ instance is returned via this pointer.
+    :param iserr:
+        the error flag is passed and updated via this pointer.
+    :return:
+        the C/C++ instance.
+    
+    If *transferObj* is ``NULL`` then the ownership is unchanged.
+    
+    If *transferObj* is ``Py_None`` then ownership is transferred to Python via
+    a call to :cfunc:`sipTransferBack()`.
+    
+    Otherwise ownership is transferred to C/C++ and *obj* associated with
+    *transferObj* via a call to :cfunc:`sipTransferTo()`.
+
+    If *state* is not ``NULL`` then the location it points to is set to
+    describe the state of the returned C/C++ instance and is the value returned
+    by any :directive:`%ConvertToTypeCode`.  The calling code must then release
+    the value at some point to prevent a memory leak by calling
+    :cfunc:`sipReleaseInstance()`.
+
+    If there is an error then the location *iserr* points to is set to a
+    non-zero value.  If it was initially a non-zero value then the conversion
+    isn't attempted in the first place.  (This allows several calls to be made
+    that share the same error flag so that it only needs to be tested once
+    rather than after each call.)
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipConvertToType()`.
+
+
+.. cfunction:: void *sipConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr)
+
+    This converts a Python object to an instance of a C structure or C++
+    class that is implemented as a mapped type assuming that a previous call to
+    :cfunc:`sipCanConvertToMappedType()` has been successful.
+
+    :param obj:
+        the Python object.
+    :param mt:
+        the opaque structure returned by :cfunc:`sipFindMappedType()`.
+    :param transferObj:
+        this controls any ownership changes to *obj*.
+    :param flags:
+        this may be the :cmacro:`SIP_NOT_NONE` flag.
+    :param state:
+        the state of the returned C/C++ instance is returned via this pointer.
+    :param iserr:
+        the error flag is passed and updated via this pointer.
+    :return:
+        the C/C++ instance.
+
+    If *transferObj* is ``NULL`` then the ownership is unchanged.
+    
+    If *transferObj* is ``Py_None`` then ownership is transferred to Python via
+    a call to :cfunc:`sipTransferBack()`.
+    
+    Otherwise ownership is transferred to C/C++ and *obj* associated with
+    *transferObj* via a call to :cfunc:`sipTransferTo()`.
+    
+    If *state* is not ``NULL`` then the location it points to is set to
+    describe the state of the returned C/C++ instance and is the value returned
+    by any :directive:`%ConvertToTypeCode`.  The calling code must then release
+    the value at some point to prevent a memory leak by calling
+    :cfunc:`sipReleaseMappedType()`.
+    
+    If there is an error then the location *iserr* points to is set to a
+    non-zero value.  If it was initially a non-zero value then the conversion
+    isn't attempted in the first place.  (This allows several calls to be made
+    that share the same error flag so that it only needs to be tested once
+    rather than after each call.)
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipConvertToType()`
+
+
+.. cfunction:: void *sipConvertToType(PyObject *obj, const sipTypeDef *td, PyObject *transferObj, int flags, int *state, int *iserr)
+
+    This converts a Python object to an instance of a C structure, C++ class or
+    mapped type assuming that a previous call to :cfunc:`sipCanConvertToType()`
+    has been successful.
+
+    :param obj:
+        the Python object.
+    :param td:
+        the type's :ref:`generated type structure <ref-type-structures>`.
+    :param transferObj:
+        this controls any ownership changes to *obj*.
+    :param flags:
+        any combination of the :cmacro:`SIP_NOT_NONE` and
+        :cmacro:`SIP_NO_CONVERTORS` flags.
+    :param state:
+        the state of the returned C/C++ instance is returned via this pointer.
+    :param iserr:
+        the error flag is passed and updated via this pointer.
+    :return:
+        the C/C++ instance.
+    
+    If *transferObj* is ``NULL`` then the ownership is unchanged.  If it is
+    ``Py_None`` then ownership is transferred to Python via a call to
+    :cfunc:`sipTransferBack()`.
+    
+    Otherwise ownership is transferred to C/C++ and *obj* associated with
+    *transferObj* via a call to :cfunc:`sipTransferTo()`.
+
+    If *state* is not ``NULL`` then the location it points to is set to
+    describe the state of the returned C/C++ instance and is the value returned
+    by any :directive:`%ConvertToTypeCode`.  The calling code must then release
+    the value at some point to prevent a memory leak by calling
+    :cfunc:`sipReleaseType()`.
+    
+    If there is an error then the location *iserr* points to is set to a
+    non-zero value.  If it was initially a non-zero value then the conversion
+    isn't attempted in the first place.  (This allows several calls to be made
+    that share the same error flag so that it only needs to be tested once
+    rather than after each call.)
+
+
+.. cfunction:: void *sipConvertToVoidPtr(PyObject *obj)
+
+    This converts a Python object to a memory address.
+    :cfunc:`PyErr_Occurred()` must be used to determine if the conversion was
+    successful.
+
+    :param obj:
+        the Python object which may be ``Py_None``, a :class:`sip.voidptr` or a
+        :ctype:`PyCObject`.
+    :return:
+        the memory address.
+
+
+.. cfunction:: int sipExportSymbol(const char *name, void *sym)
+
+    Python does not allow extension modules to directly access symbols in
+    another extension module.  This exports a symbol, referenced by a name,
+    that can subsequently be imported, using :cfunc:`sipImportSymbol()`, by
+    another module.
+
+    :param name:
+        the name of the symbol.
+    :param sym:
+        the value of the symbol.
+    :return:
+        0 if there was no error.  A negative value is returned if *name* is
+        already associated with a symbol or there was some other error.
+
+
+.. cfunction:: sipWrapperType *sipFindClass(const char *type)
+
+    This returns a pointer to the :ref:`generated type object
+    <ref-type-objects` corresponding to a C/C++ type.
+
+    :param type:
+        the C/C++ declaration of the type.
+    :return:
+        the generated type object.  This will not change and may be saved in a
+        static cache.  ``NULL`` is returned if the C/C++ type doesn't exist.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipFindType()`.
+
+
+.. cfunction:: const sipMappedType *sipFindMappedType(const char *type)
+
+    This returns a pointer to an opaque structure describing a mapped type.
+
+    :param type:
+        the C/C++ declaration of the type.
+    :return:
+        the opaque structure.  This will not change and may be saved in a
+        static cache.  ``NULL`` is returned if the C/C++ type doesn't exist.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipFindType()`.
+
+
+.. cfunction:: PyTypeObject *sipFindNamedEnum(const char *type)
+
+    This returns a pointer to the :ref:`generated Python type object
+    <ref-enum-type-objects>` corresponding to a named C/C++ enum.
+
+    :param type:
+        the C/C++ declaration of the enum.
+    :return:
+        the generated Python type object.  This will not change and may be
+        saved in a static cache.  ``NULL`` is returned if the C/C++ enum
+        doesn't exist.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipFindType()`.
+
+
+.. cfunction:: const sipTypeDef *sipFindType(const char *type)
+
+    This returns a pointer to the :ref:`generated type structure
+    <ref-type-structures>` corresponding to a C/C++ type.
+
+    :param type:
+        the C/C++ declaration of the type.
+    :return:
+        the generated type structure.  This will not change and may be saved in
+        a static cache.  ``NULL`` is returned if the C/C++ type doesn't exist.
+
+
+.. cfunction:: void *sipForceConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr)
+
+    This converts a Python object to an instance of a C structure or C++ class
+    by calling :cfunc:`sipCanConvertToInstance()` and, if it is successfull,
+    calling :cfunc:`sipConvertToInstance()`.
+
+    See :cfunc:`sipConvertToInstance()` for a full description of the
+    arguments.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipForceConvertToType()`.
+
+
+.. cfunction:: void *sipForceConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr)
+
+    This converts a Python object to an instance of a C structure or C++ class
+    which has been implemented as a mapped type by calling
+    :cfunc:`sipCanConvertToMappedType()` and, if it is successfull, calling
+    :cfunc:`sipConvertToMappedType()`.
+
+    See :cfunc:`sipConvertToMappedType()` for a full description of the
+    arguments.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipForceConvertToType()`.
+
+
+.. cfunction:: void *sipForceConvertToType(PyObject *obj, const sipTypeDef *td, PyObject *transferObj, int flags, int *state, int *iserr)
+
+    This converts a Python object to an instance of a C structure, C++ class or
+    mapped type by calling :cfunc:`sipCanConvertToType()` and, if it is
+    successfull, calling :cfunc:`sipConvertToType()`.
+
+    See :cfunc:`sipConvertToType()` for a full description of the arguments.
+
+
+.. cfunction:: void sipFree(void *mem)
+
+    This returns an area of memory allocated by :cfunc:`sipMalloc()` to the
+    heap.
+
+    :param mem:
+        the memory address.
+
+
+.. cfunction:: PyObject *sipGetPyObject(void *cppptr, const sipTypeDef *td)
+
+    This returns a borrowed reference to the Python object for a C structure or
+    C++ class instance.
+
+    :param cppptr:
+        the pointer to the C/C++ instance.
+    :param td:
+        the :ref:`generated type structure <ref-type-structures>` corresponding
+        to the C/C++ type.
+    :return:
+        the Python object or ``NULL`` (and no exception is raised) if the
+        C/C++ instance hasn't been wrapped.
+
+
+.. cfunction:: int sipGetState(PyObject *transferObj)
+
+    The :directive:`%ConvertToTypeCode` directive requires that the provided
+    code returns an ``int`` describing the state of the converted value.  The
+    state usually depends on any transfers of ownership that have been
+    requested.  This is a convenience function that returns the correct state
+    when the converted value is a temporary.
+
+    :param transferObj:
+        the object that describes the requested transfer of ownership.
+    :return:
+        the state of the converted value.
+
+
+.. cfunction:: PyObject *sipGetWrapper(void *cppptr, sipWrapperType *type)
+
+    This returns a borrowed reference to the wrapped instance object for a C
+    structure or C++ class instance.
+    
+    :param cppptr:
+        the pointer to the C/C++ instance.
+    :param type:
+        the :ref:`generated type object <ref-type-objects>` corresponding to
+        the C/C++ type.
+    :return:
+        the Python object or ``NULL`` (and no exception is raised) if the
+        C/C++ instance hasn't been wrapped.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipGetPyObject()`.
+
+
+.. cfunction:: void *sipImportSymbol(const char *name)
+
+    Python does not allow extension modules to directly access symbols in
+    another extension module.  This imports a symbol, referenced by a name,
+    that has previously been exported, using :cfunc:`sipExportSymbol()`, by
+    another module.
+
+    :param name:
+        the name of the symbol.
+    :return:
+        the value of the symbol.  ``NULL`` is returned if there is no such
+        symbol.
+
+
+.. ctype:: sipIntTypeClassMap
+
+    This C structure is used with :cfunc:`sipMapIntToClass()` to define a
+    mapping between integer based RTTI and :ref:`generated type objects
+    <ref-type-objects>`.  The structure elements are as follows.
+
+    .. cmember:: int typeInt
+
+        The integer RTTI.
+
+    .. cmember:: sipWrapperType **pyType.
+
+        A pointer to the corresponding generated type object.
+
+    .. note::
+        This is deprecated from SIP v4.8.
+
+
+.. cfunction:: int sipIsAPIEnabled(const char *name, int from, int to)
+
+    .. versionadded:: 4.9
+
+    This checks to see if the current version number of an API falls within a
+    given range.  See :ref:`ref-incompat-apis` for more detail.
+
+    :param name:
+        the name of the API.
+    :param from:
+        the lower bound of the range.  For the API to be enabled its version
+        number must be greater than or equal to *from*.  If *from* is 0 then
+        this check isn't made.
+    :param to:
+        the upper bound of the range.  For the API to be enabled its version
+        number must be less than *to*.  If *to* is 0 then this check isn't
+        made.
+    :return:
+        a non-zero value if the API is enabled.
+
+
+.. cfunction:: unsigned long sipLong_AsUnsignedLong(PyObject *obj)
+
+    This function is a thin wrapper around :cfunc:`PyLong_AsUnsignedLong()`
+    that works around a bug in Python v2.3.x and earlier when converting
+    integer objects.
+
+
+.. cfunction:: void *sipMalloc(size_t nbytes)
+
+    This allocates an area of memory on the heap using the Python
+    :cfunc:`PyMem_Malloc()` function.  The memory is freed by calling
+    :cfunc:`sipFree()`.
+
+    :param nbytes:
+        the number of bytes to allocate.
+    :return:
+        the memory address.  If there was an error then ``NULL`` is returned
+        and a Python exception raised.
+
+
+.. cfunction:: sipWrapperType *sipMapIntToClass(int type, const sipIntTypeClassMap *map, int maplen)
+
+    This can be used in :directive:`%ConvertToSubClassCode` code as a
+    convenient way of converting integer based RTTI to the corresponding
+    :ref:`generated type object <ref-type-objects>`.
+
+    :param type:
+        the integer RTTI.
+    :param map:
+        the table of known RTTI and the corresponding type objects (see
+        :ctype:`sipIntTypeClassMap`).  The entries in the table must be sorted
+        in ascending order of RTTI.
+    :param maplen:
+        the number of entries in the table.
+    :return:
+        the corresponding type object, or ``NULL`` if *type* wasn't in *map*.
+
+    .. note::
+        This is deprecated from SIP v4.8.
+
+
+.. cfunction:: sipWrapperType *sipMapStringToClass(char *type, const sipStringTypeClassMap *map, int maplen)
+
+    This can be used in :directive:`%ConvertToSubClassCode` code as a
+    convenient way of converting ``'\0'`` terminated string based RTTI to the
+    corresponding :ref:`generated type object <ref-type-objects>`.
+
+    :param type:
+        the string RTTI.
+    :param map:
+        the table of known RTTI and the corresponding type objects (see
+        :ctype:`sipStringTypeClassMap`).  The entries in the table must be
+        sorted in ascending order of RTTI.
+    :param maplen:
+        the number of entries in the table.
+    :return:
+        the corresponding type object, or ``NULL`` if *type* wasn't in *map*.
+
+    .. note::
+        This is deprecated from SIP v4.8.
+
+
+.. cfunction:: int sipParseResult(int *iserr, PyObject *method, PyObject *result, const char *format, ...)
+
+    This converts a Python object (usually returned by a method) to C/C++ based
+    on a format string and associated values in a similar way to the Python
+    :cfunc:`PyArg_ParseTuple()` function.
+
+    :param iserr:
+        if this is not ``NULL`` then the location it points to is set to a
+        non-zero value if there was an error.
+    :param method:
+        the Python method that returned *result*.
+    :param result:
+        the Python object returned by *method*.
+    :param format:
+        the format string.
+    :return:
+        0 if there was no error.  Otherwise a negative value is returned, and
+        an exception raised.
+
+    This is normally called by handwritten code specified with the
+    :directive:`%VirtualCatcherCode` directive with *method* being the supplied
+    ``sipMethod`` and *result* being the value returned by
+    :cfunc:`sipCallMethod()`.
+
+    If *format* begins and ends with parentheses then *result* must be a Python
+    tuple and the rest of *format* is applied to the tuple contents.
+
+    In the following description the first letter is the format character, the
+    entry in parentheses is the Python object type that the format character
+    will convert, and the entry in brackets are the types of the C/C++ values
+    to be passed. 
+
+    ``ae`` (object) [char \*]
+        Convert a Python string-like object of length 1 to a C/C++ ``char``
+        according to the encoding ``e``.  ``e`` can either be ``A`` for ASCII,
+        ``L`` for Latin-1, or ``8`` for UTF-8.  For Python v2 the object may be
+        either a string or a unicode object that can be encoded.  For Python v3
+        the object may either be a bytes object or a string object that can be
+        encoded.  An object that supports the buffer protocol may also be used.
+
+    ``b`` (integer) [bool \*]
+        Convert a Python integer to a C/C++ ``bool``.
+
+    ``c`` (string/bytes) [char \*]
+        Convert a Python v2 string object or a Python v3 bytes object of length
+        1 to a C/C++ ``char``.
+
+    ``d`` (float) [double \*]
+        Convert a Python floating point number to a C/C++ ``double``.
+
+    ``e`` (integer) [enum \*]
+        Convert a Python integer to an anonymous C/C++ ``enum``.
+
+    ``f`` (float) [float \*]
+        Convert a Python floating point number to a C/C++ ``float``.
+
+    ``g`` (string/bytes) [const char \*\*, :cmacro:`SIP_SSIZE_T` \*]
+        Convert a Python v2 string object or a Python v3 bytes object to a
+        C/C++ character array and its length.  If the Python object is
+        ``Py_None`` then the array and length are ``NULL`` and zero
+        respectively.
+
+    ``h`` (integer) [short \*]
+        Convert a Python integer to a C/C++ ``short``.
+
+    ``i`` (integer) [int \*]
+        Convert a Python integer to a C/C++ ``int``.
+
+    ``l`` (long) [long \*]
+        Convert a Python long to a C/C++ ``long``.
+
+    ``m`` (long) [unsigned long \*]
+        Convert a Python long to a C/C++ ``unsigned long``.
+
+    ``n`` (long) [long long \*]
+        Convert a Python long to a C/C++ ``long long``.
+
+    ``o`` (long) [unsigned long long \*]
+        Convert a Python long to a C/C++ ``unsigned long long``.
+
+    ``s`` (string/bytes) [const char \*\*]
+        Convert a Python v2 string object or a Python v3 bytes object to a
+        C/C++ ``'\0'`` terminated string.  If the Python object is ``Py_None``
+        then the string is ``NULL``.
+
+        .. note::
+            This is deprecated from SIP v4.8.  Instead you should use ``B``.
+
+    ``t`` (long) [unsigned short \*]
+        Convert a Python long to a C/C++ ``unsigned short``.
+
+    ``u`` (long) [unsigned int \*]
+        Convert a Python long to a C/C++ ``unsigned int``.
+
+    ``w`` (unicode/string) [wchar_t \*]
+        Convert a Python v2 string or unicode object or a Python v3 string
+        object of length 1 to a C/C++ wide character.
+
+    ``x`` (unicode/string) [wchar_t \*\*]
+        Convert a Python v2 string or unicode object or a Python v3 string
+        object to a C/C++ ``L'\0'`` terminated wide character string.  If the
+        Python object is ``Py_None`` then the string is ``NULL``.
+
+    ``Ae`` (object) [int, const char \*\*]
+        Convert a Python string-like object to a C/C++ ``'\0'`` terminated
+        string according to the encoding ``e``.  ``e`` can either be ``A`` for
+        ASCII, ``L`` for Latin-1, or ``8`` for UTF-8.  If the Python object is
+        ``Py_None`` then the string is ``NULL``.  The integer uniquely
+        identifies the object in the context defined by the ``S`` format
+        character and allows an extra reference to the object to be kept to
+        ensure that the string remains valid.  For Python v2 the object may be
+        either a string or a unicode object that can be encoded.  For Python v3
+        the object may either be a bytes object or a string object that can be
+        encoded.  An object that supports the buffer protocol may also be used.
+
+    ``B`` (string/bytes) [int, const char \*\*]
+        Convert a Python v2 string object or a Python v3 bytes object to a
+        C/C++ ``'\0'`` terminated string.  If the Python object is ``Py_None``
+        then the string is ``NULL``.  The integer uniquely identifies the
+        object in the context defined by the ``S`` format character and allows
+        an extra reference to the object to be kept to ensure that the string
+        remains valid.
+
+    ``Cf`` (wrapped class) [:ctype:`sipWrapperType` \*, int \*, void \*\*]
+        Convert a Python object to a C structure or a C++ class instance and
+        return its state as described in :cfunc:`sipConvertToInstance()`.
+        ``f`` is a combination of the following flags encoded as an ASCII
+        character by adding ``0`` to the combined value:
+
+            0x01 disallows the conversion of ``Py_None`` to ``NULL``
+
+            0x02 implements the :fanno:`Factory` and :fanno:`TransferBack`
+                 annotations
+
+            0x04 suppresses the return of the state of the returned C/C++
+                 instance.  Note that the ``int *`` used to return the state is
+                 not passed if this flag is specified.
+
+        .. note::
+            This is deprecated from SIP v4.8.  Instead you should use ``Hf``.
+
+    ``Df`` (wrapped instance) [const :ctype:`sipTypeDef` \*, int \*, void \*\*]
+        Convert a Python object to a C structure, C++ class or mapped type
+        instance and return its state as described in
+        :cfunc:`sipConvertToType()`.  ``f`` is a combination of the following
+        flags encoded as an ASCII character by adding ``0`` to the combined
+        value:
+
+            0x01 disallows the conversion of ``Py_None`` to ``NULL``
+
+            0x02 implements the :fanno:`Factory` and :fanno:`TransferBack`
+                 annotations
+
+            0x04 suppresses the return of the state of the returned C/C++
+                 instance.  Note that the ``int *`` used to return the state is
+                 not passed if this flag is specified.
+
+        .. note::
+            This is deprecated from SIP v4.10.1.  Instead you should use
+            ``Hf``.
+
+    ``E`` (wrapped enum) [PyTypeObject \*, enum \*]
+        Convert a Python named enum type to the corresponding C/C++ ``enum``.
+
+        .. note::
+            This is deprecated from SIP v4.8.  Instead you should use ``F``.
+
+    ``F`` (wrapped enum) [:ctype:`sipTypeDef` \*, enum \*]
+        Convert a Python named enum type to the corresponding C/C++ ``enum``.
+
+    ``G`` (unicode/string) [wchar_t \*\*, :cmacro:`SIP_SSIZE_T` \*]
+        Convert a Python v2 string or unicode object or a Python v3 string
+        object to a C/C++ wide character array and its length.  If the Python
+        object is ``Py_None`` then the array and length are ``NULL`` and zero
+        respectively.
+
+    ``Hf`` (wrapped instance) [const :ctype:`sipTypeDef` \*, int \*, void \*\*]
+        Convert a Python object to a C structure, C++ class or mapped type
+        instance as described in :cfunc:`sipConvertToType()`.  ``f`` is a
+        combination of the following flags encoded as an ASCII character by
+        adding ``0`` to the combined value:
+
+            0x01 disallows the conversion of ``Py_None`` to ``NULL``
+
+            0x02 implements the :fanno:`Factory` and :fanno:`TransferBack`
+                 annotations
+
+            0x04 returns a copy of the C/C++ instance.
+
+    ``N`` (object) [PyTypeObject \*, :PyObject \*\*]
+        A Python object is checked to see if it is a certain type and then
+        returned without any conversions.  The reference count is incremented.
+        The Python object may be ``Py_None``.
+
+    ``O`` (object) [PyObject \*\*]
+        A Python object is returned without any conversions.  The reference
+        count is incremented.
+
+    ``S`` [:ctype:`sipSimpleWrapper` \*]
+        This format character, if used, must be the first.  It is used with
+        other format characters to define a context and doesn't itself convert
+        an argument.
+
+    ``T`` (object) [PyTypeObject \*, PyObject \*\*]
+        A Python object is checked to see if it is a certain type and then
+        returned without any conversions.  The reference count is incremented.
+        The Python object may not be ``Py_None``.
+
+    ``V`` (:class:`sip.voidptr`) [void \*]
+        Convert a Python :class:`sip.voidptr` object to a C/C++ ``void *``.
+
+    ``Z`` (object) []
+        Check that a Python object is ``Py_None``.  No value is returned.
+
+
+.. cfunction:: int sipRegisterAttributeGetter(const sipTypeDef *td, sipAttrGetterFunc getter)
+
+    This registers a handler that will called just before SIP needs to get an
+    attribute from a wrapped type's dictionary for the first time.  The handler
+    must then populate the type's dictionary with any lazy attributes.
+
+    :param td:
+        the optional :ref:`generated type structure <ref-type-structures>` that
+        determines which types the handler will be called for.
+    :param getter:
+        the handler function.
+    :return:
+        0 if there was no error, otherwise -1 is returned.
+
+    If *td* is not ``NULL`` then the handler will only be called for types with
+    that type or that are sub-classed from it.  Otherwise the handler will be
+    called for all types.
+
+    A handler has the following signature.
+
+    int handler(const :ctype:`sipTypeDef` \*td, PyObject \*dict)
+
+        *td* is the generated type definition of the type whose dictionary is
+        to be populated.
+
+        *dict* is the dictionary to be populated.
+
+        0 if there was no error, otherwise -1 is returned.
+
+    See the section :ref:`ref-lazy-type-attributes` for more details.
+
+
+.. cfunction:: int sipRegisterPyType(PyTypeObject *type)
+
+    This registers a Python type object that can be used as the meta-type or
+    super-type of a wrapped C++ type.
+    
+    :param type:
+        the type object.
+    :return:
+        0 if there was no error, otherwise -1 is returned.
+
+    See the section :ref:`ref-types-metatypes` for more details.
+
+
+.. cfunction:: void sipReleaseInstance(void *cpp, sipWrapperType *type, int state)
+
+    This destroys a wrapped C/C++ instance if it was a temporary instance.  It
+    is called after a call to either :cfunc:`sipConvertToInstance()` or
+    :cfunc:`sipForceConvertToInstance()`.
+    
+    :param cpp:
+        the C/C++ instance.
+    :param type:
+        the type's :ref:`generated type object <ref-type-objects>`.
+    :param state:
+        describes the state of the C/C++ instance.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipReleaseType()`.
+
+
+.. cfunction:: void sipReleaseMappedType(void *cpp, const sipMappedType *mt, int state)
+
+    This destroys a wrapped C/C++ mapped type if it was a temporary instance.
+    It is called after a call to either :cfunc:`sipConvertToMappedType()` or
+    :cfunc:`sipForceConvertToMappedType()`.
+    
+    :param cpp:
+        the C/C++ instance.
+    :param mt:
+        the opaque structure returned by :cfunc:`sipFindMappedType()`.
+    :param state:
+        describes the state of the C/C++ instance.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use
+        :cfunc:`sipReleaseType()`.
+
+
+.. cfunction:: void sipReleaseType(void *cpp, const sipTypeDef *td, int state)
+
+    This destroys a wrapped C/C++ or mapped type instance if it was a temporary
+    instance.  It is called after a call to either :cfunc:`sipConvertToType()`
+    or :cfunc:`sipForceConvertToType()`.
+    
+    :param cpp:
+        the C/C++ instance.
+    :param td:
+        the type's :ref:`generated type structure <ref-type-structures>`.
+    :param state:
+        describes the state of the C/C++ instance.
+
+
+.. cfunction:: const char *sipResolveTypedef(const char *name)
+
+    This returns the value of a C/C++ typedef.
+
+    :param name:
+        the name of the typedef.
+    :return:
+        the value of the typedef or ``NULL`` if there was no such typedef.
+
+
+.. ctype:: sipSimpleWrapper
+
+    This is a C structure that represents a Python wrapped instance whose type
+    is :class:`sip.simplewrapper`.  It is an extension of the ``PyObject``
+    structure and so may be safely cast to it.
+
+    .. cmember:: PyObject *user
+
+        This can be used for any purpose by handwritten code and will
+        automatically be garbage collected at the appropriate time.
+
+
+.. cvar:: PyTypeObject *sipSimpleWrapper_Type
+
+    This is the type of a :ctype:`sipSimpleWrapper` structure and is the C
+    implementation of :class:`sip.simplewrapper`.  It may be safely cast to
+    :ctype:`sipWrapperType`.
+
+
+.. ctype:: sipStringTypeClassMap
+
+    This C structure is used with :cfunc:`sipMapStringToClass()` to define a
+    mapping between ``'\0'`` terminated string based RTTI and
+    :ref:`ref-type-objects`.  The structure elements are as follows.
+
+    .. cmember:: char *typeString
+
+        The ``'\0'`` terminated string RTTI.
+
+    .. cmember:: sipWrapperType **pyType.
+
+        A pointer to the corresponding generated type object.
+
+    .. note::
+        This is deprecated from SIP v4.8.
+
+
+.. cfunction:: void sipTransferBack(PyObject *obj)
+
+    This transfers ownership of a Python wrapped instance to Python (see
+    :ref:`ref-object-ownership`).
+
+    :param obj:
+        the wrapped instance.
+        
+    In addition, any association of the instance with regard to the cyclic
+    garbage collector with another instance is removed.
+
+
+.. cfunction:: void sipTransferBreak(PyObject *obj)
+
+    Any association of a Python wrapped instance with regard to the cyclic
+    garbage collector with another instance is removed.  Ownership of the
+    instance should be with C++.
+
+    :param obj:
+        the wrapped instance.
+
+
+.. cfunction:: void sipTransferTo(PyObject *obj, PyObject *owner)
+
+    This transfers ownership of a Python wrapped instance to C++ (see
+    :ref:`ref-object-ownership`).
+
+    :param obj:
+        the wrapped instance.
+    :param owner:
+        an optional wrapped instance that *obj* becomes associated with with
+        regard to the cyclic garbage collector.  If *owner* is ``NULL`` then no
+        such association is made.  If *owner* is the same value as *obj* then
+        any reference cycles involving *obj* can never be detected or broken by
+        the cyclic garbage collector.  Responsibility for calling the C++
+        instance's destructor is always transfered to C++.
+
+
+.. cfunction:: PyTypeObject *sipTypeAsPyTypeObject(sipTypeDef *td)
+
+    This returns a pointer to the Python type object that SIP creates for a
+    :ref:`generated type structure <ref-type-structures>`.
+
+    :param td:
+        the type structure.
+    :return:
+        the Python type object.  If the type structure refers to a mapped type
+        then ``NULL`` will be returned.
+
+    If the type structure refers to a C structure or C++ class then the
+    Python type object may be safely cast to a :ctype:`sipWrapperType`.
+
+
+.. cfunction:: const sipTypeDef *sipTypeFromPyTypeObject(PyTypeObject *py_type)
+
+    This returns the :ref:`generated type structure <ref-type-structures>` for
+    a Python type object.
+
+    :param py_type:
+        the Python type object.
+    :return:
+        the type structure or ``NULL`` if the Python type object doesn't
+        correspond to a type structure.
+
+
+.. cfunction:: int sipTypeIsClass(sipTypeDef *td)
+
+    This checks if a :ref:`generated type structure <ref-type-structures>`
+    refers to a C structure or C++ class.
+
+    :param td:
+        the type structure.
+    :return:
+        a non-zero value if the type structure refers to a structure or class.
+
+
+.. cfunction:: int sipTypeIsEnum(sipTypeDef *td)
+
+    This checks if a :ref:`generated type structure <ref-type-structures>`
+    refers to a named enum.
+
+    :param td:
+        the type structure.
+    :return:
+        a non-zero value if the type structure refers to an enum.
+
+
+.. cfunction:: int sipTypeIsMapped(sipTypeDef *td)
+
+    This checks if a :ref:`generated type structure <ref-type-structures>`
+    refers to a mapped type.
+
+    :param td:
+        the type structure.
+    :return:
+        a non-zero value if the type structure refers to a mapped type.
+
+
+.. cfunction:: int sipTypeIsNamespace(sipTypeDef *td)
+
+    This checks if a :ref:`generated type structure <ref-type-structures>`
+    refers to a C++ namespace.
+
+    :param td:
+        the type structure.
+    :return:
+        a non-zero value if the type structure refers to a namespace.
+
+
+.. cfunction:: const char *sipTypeName(const sipTypeDef *td)
+
+    This returns the C/C++ name of a wrapped type.
+
+    :param td:
+        the type's :ref:`generated type structure <ref-type-structures>`.
+    :return:
+        the name of the C/C++ type.
+
+
+.. cfunction:: const sipTypeDef *sipTypeScope(const sipTypeDef *td)
+
+    This returns the :ref:`generated type structure <ref-type-structures>` of
+    the enclosing scope of another generated type structure.
+
+    :param td:
+        the type structure.
+    :return:
+        the type structure of the scope or ``NULL`` if the type has no scope.
+
+
+.. cvar:: PyTypeObject *sipVoidPtr_Type
+
+    This is the type of a ``PyObject`` structure that is used to wrap a
+    ``void *``.
+
+
+.. ctype:: sipWrapper
+
+    This is a C structure that represents a Python wrapped instance whose type
+    is :class:`sip.wrapper`.  It is an extension of the
+    :ctype:`sipSimpleWrapper` and ``PyObject`` structures and so may be safely
+    cast to both.
+
+
+.. cfunction:: int sipWrapper_Check(PyObject *obj)
+
+    This checks if a Python object is a wrapped instance.
+
+    :param obj:
+        the Python object.
+    :return:
+        a non-zero value if the Python object is a wrapped instance.
+
+    .. note::
+        This is deprecated from SIP v4.8.  Instead you should use the
+        following::
+
+            PyObject_TypeCheck(obj, sipWrapper_Type)
+
+
+.. cvar:: PyTypeObject *sipWrapper_Type
+
+    This is the type of a :ctype:`sipWrapper` structure and is the C
+    implementation of :class:`sip.wrapper`.  It may be safely cast to
+    :ctype:`sipWrapperType`.
+
+
+.. ctype:: sipWrapperType
+
+    This is a C structure that represents a SIP generated type object.  It is
+    an extension of the ``PyTypeObject`` structure (which is itself an
+    extension of the ``PyObject`` structure) and so may be safely cast to
+    ``PyTypeObject`` (and ``PyObject``).
+
+
+.. cvar:: PyTypeObject *sipWrapperType_Type
+
+    This is the type of a :ctype:`sipWrapperType` structure and is the C
+    implementation of :class:`sip.wrappertype`.
+
+
+.. _ref-type-structures:
+
+Generated Type Structures
+-------------------------
+
+SIP generates an opaque type structure for each C structure, C++ class, C++
+namespace, named enum or mapped type being wrapped.  These are
+:ctype:`sipTypeDef` structures and are used extensively by the SIP API.
+
+The names of these structure are prefixed by ``sipType_``.
+
+For those structures that correspond to C structures, C++ classes, C++
+namespaces or named enums the remaining part of the name is the fully
+qualified name of the structure, class, namespace or enum name.  Any ``::``
+scope separators are replaced by an underscore.  For example, the type object
+for class ``Klass`` is ``sipType_Klass``.
+
+For those structure that correspond to mapped types the remaining part of the
+name is generated by SIP.  The only way for handwritten code to obtain a
+pointer to a structure for a mapped type is to use :cfunc:`sipFindType()`.
+
+The type structures of all imported types are available to handwritten code.
+
+
+.. _ref-type-objects:
+
+Generated Type Objects
+----------------------
+
+SIP generates a :ctype:`sipWrapperType` type object for each C structure or
+C++ class being wrapped.
+
+These objects are named with the structure or class name prefixed by
+``sipClass_``.  For example, the type object for class ``Klass`` is
+``sipClass_Klass``.
+
+.. note::
+    Using these names is deprecated from SIP v4.8.  Instead use the
+    corresponding generated type structure (see :ref:`ref-type-structures`) and
+    :cfunc:`sipTypeAsPyTypeObject()`.
+
+
+.. _ref-enum-type-objects:
+
+Generated Named Enum Type Objects
+---------------------------------
+
+SIP generates a type object for each named enum being wrapped.  These are
+PyTypeObject structures.  (Anonymous enums are wrapped as Python integers.)
+
+These objects are named with the fully qualified enum name (i.e. including any
+enclosing scope) prefixed by ``sipEnum_``.  For example, the type object for
+enum ``Enum`` defined in class ``Klass`` is ``sipEnum_Klass_Enum``.
+
+.. note::
+    Using these names is deprecated from SIP v4.8.  Instead use the
+    corresponding generated type structure (see :ref:`ref-type-structures`) and
+    :cfunc:`sipTypeAsPyTypeObject()`.
+
+
+.. _ref-derived-classes:
+
+Generated Derived Classes
+-------------------------
+
+For most C++ classes being wrapped SIP generates a derived class with the same
+name prefixed by ``sip``.  For example, the derived class for class ``Klass``
+is ``sipKlass``.
+
+If a C++ class doesn't have any virtual or protected methods in it or any of
+it's super-class hierarchy, or does not emit any Qt signals, then a derived
+class is not generated.
+
+Most of the time handwritten code should ignore the derived classes.  The only
+exception is that handwritten constructor code specified using the
+:directive:`%MethodCode` directive should call the derived class's constructor
+(which has the same C++ signature) rather then the wrapped class's constructor.
+
+
+.. _ref-exception-objects:
+
+Generated Exception Objects
+---------------------------
+
+SIP generates a Python object for each exception defined with the
+:directive:`%Exception` directive.
+
+These objects are named with the fully qualified exception name (i.e. including
+any enclosing scope) prefixed by ``sipException_``.  For example, the type
+object for enum ``Except`` defined in class ``Klass`` is
+``sipException_Klass_Except``.
+
+The objects of all imported exceptions are available to handwritten code.
diff --git a/sphinx/command_line.rst b/sphinx/command_line.rst
new file mode 100644
index 0000000..9c50cf4
--- /dev/null
+++ b/sphinx/command_line.rst
@@ -0,0 +1,137 @@
+.. _ref-command-line:
+
+The SIP Command Line
+====================
+
+The syntax of the SIP command line is::
+
+    sip [options] [specification]
+
+``specification`` is the name of the specification file for the module.  If it
+is omitted then ``stdin`` is used.
+
+The full set of command line options is:
+
+.. program:: sip
+
+.. cmdoption:: -h
+
+    Display a help message.
+
+.. cmdoption:: -V
+
+    Display the SIP version number.
+
+.. cmdoption:: -a <FILE>
+
+    The name of the QScintilla API file to generate.  This file contains a
+    description of the module API in a form that the QScintilla editor
+    component can use for auto-completion and call tips.  (The file may also be
+    used by the SciTE editor but must be sorted first.)  By default the file is
+    not generated.
+
+.. cmdoption:: -b <FILE>
+
+    The name of the build file to generate.  This file contains the information
+    about the module needed by the :ref:`SIP build system <ref-build-system>`
+    to generate a platform and compiler specific Makefile for the module.  By
+    default the file is not generated.
+
+.. cmdoption:: -c <DIR>
+
+    The name of the directory (which must exist) into which all of the
+    generated C or C++ code is placed.  By default no code is generated.
+
+.. cmdoption:: -d <FILE>
+
+    The name of the documentation file to generate.  Documentation is included
+    in specification files using the :directive:`%Doc` and
+    :directive:`%ExportedDoc` directives.  By default the file is not
+    generated.
+
+.. cmdoption:: -e
+
+    Support for C++ exceptions is enabled.  This causes all calls to C++ code
+    to be enclosed in ``try``/``catch`` blocks and C++ exceptions to be
+    converted to Python exceptions.  By default exception support is disabled.
+
+.. cmdoption:: -g
+
+    The Python GIL is released before making any calls to the C/C++ library
+    being wrapped and reacquired afterwards.  See :ref:`ref-gil` and the
+    :fanno:`ReleaseGIL` and :fanno:`HoldGIL` annotations.
+
+.. cmdoption:: -I <DIR>
+
+    The directory is added to the list of directories searched when looking for
+    a specification file given in an :directive:`%Include` or
+    :directive:`%Import` directive.  This option may be given any number of
+    times.
+
+.. cmdoption:: -j <NUMBER>
+
+    The generated code is split into the given number of files.  This makes it
+    easier to use the parallel build facility of most modern implementations of
+    ``make``.  By default 1 file is generated for each C structure or C++
+    class.
+
+.. cmdoption:: -k
+
+    .. versionadded:: 4.10
+
+    All functions and methods will, by default, support passing parameters
+    using the Python keyword argument syntax.
+
+.. cmdoption:: -o
+
+    .. versionadded:: 4.10
+
+    Docstrings will be automatically generated that describe the signature of
+    all functions, methods and constructors.
+
+.. cmdoption:: -p <MODULE>
+
+    The name of the :directive:`%ConsolidatedModule` which will contain the
+    wrapper code for this component module.
+
+.. cmdoption:: -P
+
+    .. versionadded:: 4.10
+
+    By default SIP generates code to provide access to protected C++ functions
+    from Python.  On some platforms (notably Linux, but not Windows) this code
+    can be avoided if the ``protected`` keyword is redefined as ``public``
+    during compilation.  This can result in a significant reduction in the size
+    of a generated Python module.  This option disables the generation of the
+    extra code.
+
+.. cmdoption:: -r
+
+    Debugging statements that trace the execution of the bindings are
+    automatically generated.  By default the statements are not generated.
+
+.. cmdoption:: -s <SUFFIX>
+
+    The suffix to use for generated C or C++ source files.  By default ``.c``
+    is used for C and ``.cpp`` for C++.
+
+.. cmdoption:: -t <TAG>
+
+    The SIP version tag (declared using a :directive:`%Timeline` directive) or
+    the SIP platform tag (declared using the :directive:`%Platforms` directive)
+    to generate code for.  This option may be given any number of times so long
+    as the tags do not conflict.
+
+.. cmdoption:: -w
+
+    The display of warning messages is enabled.  By default warning messages
+    are disabled.
+
+.. cmdoption:: -x <FEATURE>
+
+    The feature (declared using the :directive:`%Feature` directive) is
+    disabled.
+
+.. cmdoption:: -z <FILE>
+
+    The name of a file containing more command line options.
diff --git a/sphinx/conf.py b/sphinx/conf.py
new file mode 100644
index 0000000..43a3a1e
--- /dev/null
+++ b/sphinx/conf.py
@@ -0,0 +1,231 @@
+# -*- coding: utf-8 -*-
+#
+# SIP documentation build configuration file, created by
+# sphinx-quickstart on Sat May 30 14:28:55 2009.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+#extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'SIP'
+copyright = u'2010 Riverbank Computing Limited'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '4.10.5'
+# The full version, including alpha/beta/rc tags.
+release = '4.10.5'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+#exclude_trees = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "SIP 4.10.5 Reference Guide"
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# 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']
+
+# 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'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'SIPdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'SIP.tex', u'SIP Documentation',
+   u'Riverbank Computing Limited', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+
+def setup(app):
+    """ Define roles specific to SIP. """
+
+    app.add_description_unit('argument-annotation', 'aanno',
+            indextemplate='single: %s (argument annotation)')
+
+    app.add_description_unit('class-annotation', 'canno',
+            indextemplate='single: %s (class annotation)')
+
+    app.add_description_unit('enum-annotation', 'eanno',
+            indextemplate='single: %s (enum annotation)')
+
+    app.add_description_unit('exception-annotation', 'xanno',
+            indextemplate='single: %s (exception annotation)')
+
+    app.add_description_unit('function-annotation', 'fanno',
+            indextemplate='single: %s (function annotation)')
+
+    app.add_description_unit('license-annotation', 'lanno',
+            indextemplate='single: %s (license annotation)')
+
+    app.add_description_unit('mapped-type-annotation', 'manno',
+            indextemplate='single: %s (mapped type annotation)')
+
+    app.add_description_unit('typedef-annotation', 'tanno',
+            indextemplate='single: %s (typedef annotation)')
+
+    app.add_description_unit('variable-annotation', 'vanno',
+            indextemplate='single: %s (variable annotation)')
+
+    app.add_description_unit('directive', 'directive',
+            indextemplate='single: %s (directive)')
+
+    app.add_description_unit('sip-type', 'stype',
+            indextemplate='single: %s (SIP type)')
diff --git a/sphinx/directives.rst b/sphinx/directives.rst
new file mode 100644
index 0000000..7e3a2e0
--- /dev/null
+++ b/sphinx/directives.rst
@@ -0,0 +1,2109 @@
+Directives
+==========
+
+In this section we describe each of the directives that can be used in
+specification files.  All directives begin with ``%`` as the first
+non-whitespace character in a line.
+
+Some directives have arguments or contain blocks of code or documentation.  In
+the following descriptions these are shown in *italics*.  Optional arguments
+are enclosed in [*brackets*].
+
+Some directives are used to specify handwritten code.  Handwritten code must
+not define names that start with the prefix ``sip``.
+
+
+.. directive:: %AccessCode
+
+.. parsed-literal::
+
+    %AccessCode
+        *code*
+    %End
+
+This directive is used immediately after the declaration of an instance of a
+wrapped class or structure, or a pointer to such an instance.  You use it to
+provide handwritten code that overrides the default behaviour.
+
+For example::
+
+    class Klass;
+
+    Klass *klassInstance;
+    %AccessCode
+        // In this contrived example the C++ library we are wrapping defines
+        // klassInstance as Klass ** (which SIP doesn't support) so we
+        // explicitly dereference it.
+        if (klassInstance && *klassInstance)
+            return *klassInstance;
+
+        // This will get converted to None.
+        return 0;
+    %End
+
+
+.. directive:: %API
+
+.. versionadded:: 4.9
+
+.. parsed-literal::
+
+    %API *name* *version*
+
+This directive is used to define an API and set its default version number.  A
+version number must be greater than or equal to 1.
+
+See :ref:`ref-incompat-apis` for more detail.
+
+For example::
+
+    %API PyQt4 1
+
+
+.. directive:: %BIGetBufferCode
+
+.. parsed-literal::
+
+    %BIGetBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIReleaseBufferCode`) is used to
+specify code that implements the buffer interface of Python v3.  If Python v2
+is being used then this is ignored.
+
+The following variables are made available to the handwritten code:
+
+Py_buffer \*sipBuffer
+    This is a pointer to the Python buffer structure that the handwritten code
+    must populate.
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+int sipFlags
+    These are the flags that specify what elements of the ``sipBuffer``
+    structure must be populated.
+
+int sipRes
+    The handwritten code should set this to 0 if there was no error or -1 if
+    there was an error.
+
+PyObject \*sipSelf
+    This is the Python object that wraps the structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIGetCharBufferCode
+
+.. parsed-literal::
+
+    %BIGetCharBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetReadBufferCode`,
+:directive:`%BIGetSegCountCode` and :directive:`%BIGetWriteBufferCode`) is used
+to specify code that implements the buffer interface of Python v2.  If Python
+v3 is being used then this is ignored.
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+void \*\*sipPtrPtr
+    This is the pointer used to return the address of the character buffer.
+
+:cmacro:`SIP_SSIZE_T` sipRes
+    The handwritten code should set this to the length of the character buffer
+    or -1 if there was an error.
+
+:cmacro:`SIP_SSIZE_T` sipSegment
+    This is the number of the segment of the character buffer.
+
+PyObject \*sipSelf
+    This is the Python object that wraps the structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIGetReadBufferCode
+
+.. parsed-literal::
+
+    %BIGetReadBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetCharBufferCode`,
+:directive:`%BIGetSegCountCode` and :directive:`%BIGetWriteBufferCode`) is used
+to specify code that implements the buffer interface of Python v2.  If
+Python v3 is being used then this is ignored.
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+void \*\*sipPtrPtr
+    This is the pointer used to return the address of the read buffer.
+
+:cmacro:`SIP_SSIZE_T` sipRes
+    The handwritten code should set this to the length of the read buffer or
+    -1 if there was an error.
+
+:cmacro:`SIP_SSIZE_T` sipSegment
+    This is the number of the segment of the read buffer.
+
+PyObject \*sipSelf
+    This is the Python object that wraps the structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIGetSegCountCode
+
+.. parsed-literal::
+
+    %BIGetSegCountCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetCharBufferCode`,
+:directive:`%BIGetReadBufferCode` and :directive:`%BIGetWriteBufferCode`) is
+used to specify code that implements the buffer interface of Python v2.  If
+Python v3 is being used then this is ignored.
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+:cmacro:`SIP_SSIZE_T` \*sipLenPtr
+    This is the pointer used to return the total length in bytes of all
+    segments of the buffer.
+
+:cmacro:`SIP_SSIZE_T` sipRes
+    The handwritten code should set this to the number of segments that make
+    up the buffer.
+
+PyObject \*sipSelf
+    This is the Python object that wraps the structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIGetWriteBufferCode
+
+.. parsed-literal::
+
+    %BIGetWriteBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetCharBufferCode`,
+:directive:`%BIGetReadBufferCode` and :directive:`%BIGetSegCountCode` is used
+to specify code that implements the buffer interface of Python v2.  If Python
+v3 is being used then this is ignored.
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+void \*\*sipPtrPtr
+    This is the pointer used to return the address of the write buffer.
+
+:cmacro:`SIP_SSIZE_T` sipRes
+    The handwritten code should set this to the length of the write buffer or
+    -1 if there was an error.
+
+:cmacro:`SIP_SSIZE_T` sipSegment
+    This is the number of the segment of the write buffer.
+
+PyObject \*sipSelf
+    This is the Python object that wraps the structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIReleaseBufferCode
+
+.. parsed-literal::
+
+    %BIReleaseBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetBufferCode`) is used to specify
+code that implements the buffer interface of Python v3.  If Python v2 is being
+used then this is ignored.
+
+The following variables are made available to the handwritten code:
+
+Py_buffer \*sipBuffer
+    This is a pointer to the Python buffer structure.
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+PyObject \*sipSelf
+    This is the Python object that wraps the structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %CModule
+
+.. parsed-literal::
+
+    %CModule *name* [*version*]
+
+This directive is used to identify that the library being wrapped is a C
+library and to define the name of the module and it's optional version number.
+
+See the :directive:`%Module` directive for an explanation of the version
+number.
+
+For example::
+
+    %CModule dbus 1
+
+
+.. directive:: %CompositeModule
+
+.. parsed-literal::
+
+    %CompositeModule *name*
+
+A composite module is one that merges a number of related SIP generated
+modules.  For example, a module that merges the modules ``a_mod``, ``b_mod``
+and ``c_mod`` is equivalent to the following pure Python module::
+
+    from a_mod import *
+    from b_mod import *
+    from c_mod import *
+
+Clearly the individual modules should not define module-level objects with the
+same name.
+
+This directive is used to specify the name of a composite module.  Any
+subsequent :directive:`%CModule` or :directive:`%Module` directive is
+interpreted as defining a component module.
+
+For example::
+
+    %CompositeModule PyQt4.Qt
+    %Include QtCore/QtCoremod.sip
+    %Include QtGui/QtGuimod.sip
+
+The main purpose of a composite module is as a programmer convenience as they
+don't have to remember which which individual module an object is defined in.
+
+
+.. directive:: %ConsolidatedModule
+
+.. parsed-literal::
+
+    %ConsolidatedModule *name*
+
+A consolidated module is one that consolidates the wrapper code of a number of
+SIP generated modules (refered to as component modules in this context).
+
+This directive is used to specify the name of a consolidated module.  Any
+subsequent :directive:`%CModule` or :directive:`%Module` directive is
+interpreted as defining a component module.
+
+For example::
+
+    %ConsolidatedModule PyQt4._qt
+    %Include QtCore/QtCoremod.sip
+    %Include QtGui/QtGuimod.sip
+
+A consolidated module is not intended to be explicitly imported by an
+application.  Instead it is imported by its component modules when they
+themselves are imported.
+
+Normally the wrapper code is contained in the component module and is linked
+against the corresponding C or C++ library.  The advantage of a consolidated
+module is that it allows all of the wrapped C or C++ libraries to be linked
+against a single module.  If the linking is done statically then deployment of
+generated modules can be greatly simplified.
+
+It follows that a component module can be built in one of two ways, as a
+normal standalone module, or as a component of a consolidated module.  When
+building as a component the ``-p`` command line option should be used to
+specify the name of the consolidated module.
+
+
+.. directive:: %ConvertFromTypeCode
+
+.. parsed-literal::
+
+    %ConvertFromTypeCode
+        *code*
+    %End
+
+This directive is used as part of the :directive:`%MappedType` directive to
+specify the handwritten code that converts an instance of a mapped type to a
+Python object.
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the instance of the mapped type to be converted.  It
+    will never be zero as the conversion from zero to ``Py_None`` is handled
+    before the handwritten code is called.
+
+PyObject \*sipTransferObj
+    This specifies any desired ownership changes to the returned object.  If it
+    is ``NULL`` then the ownership should be left unchanged.  If it is
+    ``Py_None`` then ownership should be transferred to Python.  Otherwise
+    ownership should be transferred to C/C++ and the returned object associated
+    with *sipTransferObj*.  The code can choose to interpret these changes in
+    any way.  For example, if the code is converting a C++ container of wrapped
+    classes to a Python list it is likely that the ownership changes should be
+    made to each element of the list.
+
+The handwritten code must explicitly return a ``PyObject *``.  If there was an
+error then a Python exception must be raised and ``NULL`` returned.
+
+The following example converts a ``QList<QWidget *>`` instance to a Python
+list of ``QWidget`` instances::
+
+    %ConvertFromTypeCode
+        PyObject *l;
+
+        // Create the Python list of the correct length.
+        if ((l = PyList_New(sipCpp->size())) == NULL)
+            return NULL;
+
+        // Go through each element in the C++ instance and convert it to a
+        // wrapped QWidget.
+        for (int i = 0; i < sipCpp->size(); ++i)
+        {
+            QWidget *w = sipCpp->at(i);
+            PyObject *wobj;
+
+            // Get the Python wrapper for the QWidget instance, creating a new
+            // one if necessary, and handle any ownership transfer.
+            if ((wobj = sipConvertFromType(w, sipType_QWidget, sipTransferObj)) == NULL)
+            {
+                // There was an error so garbage collect the Python list.
+                Py_DECREF(l);
+                return NULL;
+            }
+
+            // Add the wrapper to the list.
+            PyList_SET_ITEM(l, i, wobj);
+        }
+
+        // Return the Python list.
+        return l;
+    %End
+
+
+.. directive:: %ConvertToSubClassCode
+
+.. parsed-literal::
+
+    %ConvertToSubClassCode
+        *code*
+    %End
+
+When SIP needs to wrap a C++ class instance it first checks to make sure it
+hasn't already done so.  If it has then it just returns a new reference to the
+corresponding Python object.  Otherwise it creates a new Python object of the
+appropriate type.  In C++ a function may be defined to return an instance of a
+certain class, but can often return a sub-class instead.
+
+This directive is used to specify handwritten code that exploits any available
+real-time type information (RTTI) to see if there is a more specific Python
+type that can be used when wrapping the C++ instance.  The RTTI may be
+provided by the compiler or by the C++ instance itself.
+
+The directive is included in the specification of one of the classes that the
+handwritten code handles the type conversion for.  It doesn't matter which
+one, but a sensible choice would be the one at the root of that class
+hierarchy in the module.
+
+Note that if a class hierarchy extends over a number of modules then this
+directive should be used in each of those modules to handle the part of the
+hierarchy defined in that module.  SIP will ensure that the different pieces
+of code are called in the right order to determine the most specific Python
+type to use.
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the C++ class instance.
+
+void \*\*sipCppRet
+    When the sub-class is derived from more than one super-class then it is
+    possible that the C++ address of the instance as the sub-class is
+    different to that of the super-class.  If so, then this must be set to the
+    C++ address of the instance when cast (usually using ``static_cast``)
+    from the super-class to the sub-class.
+
+const sipTypeDef \*sipType
+    The handwritten code must set this to the SIP generated type structure
+    that corresponds to the class instance.  (The type structure for class
+    ``Klass`` is ``sipType_Klass``.)  If the RTTI of the class instance isn't
+    recognised then ``sipType`` must be set to ``NULL``.  The code doesn't
+    have to recognise the exact class, only the most specific sub-class that
+    it can.
+
+sipWrapperType \*sipClass
+    The handwritten code must set this to the SIP generated Python type object
+    that corresponds to the class instance.  (The type object for class
+    ``Klass`` is ``sipClass_Klass``.)  If the RTTI of the class instance isn't
+    recognised then ``sipClass`` must be set to ``NULL``.  The code doesn't
+    have to recognise the exact class, only the most specific sub-class that
+    it can.
+
+    This is deprecated from SIP v4.8.  Instead you should use ``sipType``.
+
+The handwritten code must not explicitly return.
+
+The following example shows the sub-class conversion code for ``QEvent`` based
+class hierarchy in PyQt::
+
+    class QEvent
+    {
+    %ConvertToSubClassCode
+        // QEvent sub-classes provide a unique type ID.
+        switch (sipCpp->type())
+        {
+        case QEvent::Timer:
+            sipType = sipType_QTimerEvent;
+            break;
+
+        case QEvent::KeyPress:
+        case QEvent::KeyRelease:
+            sipType = sipType_QKeyEvent;
+            break;
+
+        // Skip the remaining event types to keep the example short.
+
+        default:
+            // We don't recognise the type.
+            sipType = NULL;
+        }
+    %End
+
+        // The rest of the class specification.
+
+    };
+
+
+.. directive:: %ConvertToTypeCode
+
+.. parsed-literal::
+
+    %ConvertToTypeCode
+        *code*
+    %End
+
+This directive is used to specify the handwritten code that converts a Python
+object to a mapped type instance and to handle any ownership transfers.  It is
+used as part of the :directive:`%MappedType` directive and as part of a class
+specification.  The code is also called to determine if the Python object is of
+the correct type prior to conversion.
+
+When used as part of a class specification it can automatically convert
+additional types of Python object.  For example, PyQt uses it in the
+specification of the ``QString`` class to allow Python string objects and
+unicode objects to be used wherever ``QString`` instances are expected.
+
+The following variables are made available to the handwritten code:
+
+int \*sipIsErr
+    If this is ``NULL`` then the code is being asked to check the type of the
+    Python object.  The check must not have any side effects.  Otherwise the
+    code is being asked to convert the Python object and a non-zero value
+    should be returned through this pointer if an error occurred during the
+    conversion.
+
+PyObject \*sipPy
+    This is the Python object to be converted.
+
+*type* \*\*sipCppPtr
+    This is a pointer through which the address of the mapped type instance (or
+    zero if appropriate) is returned.  Its value is undefined if ``sipIsErr``
+    is ``NULL``.
+
+PyObject \*sipTransferObj
+    This specifies any desired ownership changes to *sipPy*.  If it is ``NULL``
+    then the ownership should be left unchanged.  If it is ``Py_None`` then
+    ownership should be transferred to Python.  Otherwise ownership should be
+    transferred to C/C++ and *sipPy* associated with *sipTransferObj*.  The
+    code can choose to interpret these changes in any way.
+
+The handwritten code must explicitly return an ``int`` the meaning of which
+depends on the value of ``sipIsErr``.
+
+If ``sipIsErr`` is ``NULL`` then a non-zero value is returned if the Python
+object has a type that can be converted to the mapped type.  Otherwise zero is
+returned.
+
+If ``sipIsErr`` is not ``NULL`` then a combination of the following flags is
+returned.
+
+        - :cmacro:`SIP_TEMPORARY` is set to indicate that the returned instance
+          is a temporary and should be released to avoid a memory leak.
+
+        - :cmacro:`SIP_DERIVED_CLASS` is set to indicate that the type of the
+          returned instance is a derived class.  See
+          :ref:`ref-derived-classes`.
+
+The following example converts a Python list of ``QPoint`` instances to a
+``QList<QPoint>`` instance::
+
+    %ConvertToTypeCode
+        // See if we are just being asked to check the type of the Python
+        // object.
+        if (!sipIsErr)
+        {
+            // Checking whether or not None has been passed instead of a list
+            // has already been done.
+            if (!PyList_Check(sipPy))
+                return 0;
+
+            // Check the type of each element.  We specify SIP_NOT_NONE to
+            // disallow None because it is a list of QPoint, not of a pointer
+            // to a QPoint, so None isn't appropriate.
+            for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
+                if (!sipCanConvertToType(PyList_GET_ITEM(sipPy, i),
+                                         sipType_QPoint, SIP_NOT_NONE))
+                    return 0;
+
+            // The type is valid.
+            return 1;
+        }
+
+        // Create the instance on the heap.
+        QList<QPoint> *ql = new QList<QPoint>;
+
+        for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
+        {
+            QPoint *qp;
+            int state;
+
+            // Get the address of the element's C++ instance.  Note that, in
+            // this case, we don't apply any ownership changes to the list
+            // elements, only to the list itself.
+            qp = reinterpret_cast<QPoint *>(sipConvertToType(
+                                                    PyList_GET_ITEM(sipPy, i),
+                                                    sipType_QPoint, 0,
+                                                    SIP_NOT_NONE,
+                                                    &state, sipIsErr));
+
+            // Deal with any errors.
+            if (*sipIsErr)
+            {
+                sipReleaseType(qp, sipType_QPoint, state);
+
+                // Tidy up.
+                delete ql;
+
+                // There is no temporary instance.
+                return 0;
+            }
+
+            ql->append(*qp);
+
+            // A copy of the QPoint was appended to the list so we no longer
+            // need it.  It may be a temporary instance that should be
+            // destroyed, or a wrapped instance that should not be destroyed.
+            // sipReleaseType() will do the right thing.
+            sipReleaseType(qp, sipType_QPoint, state);
+        }
+
+        // Return the instance.
+        *sipCppPtr = ql;
+
+        // The instance should be regarded as temporary (and be destroyed as
+        // soon as it has been used) unless it has been transferred from
+        // Python.  sipGetState() is a convenience function that implements
+        // this common transfer behaviour.
+        return sipGetState(sipTransferObj);
+    %End
+
+When used in a class specification the handwritten code replaces the code that
+would normally be automatically generated.  This means that the handwritten
+code must also handle instances of the class itself and not just the additional
+types that are being supported.  This should be done by making calls to
+:cfunc:`sipCanConvertToType()` to check the object type and
+:cfunc:`sipConvertToType()` to convert the object.  The
+:cmacro:`SIP_NO_CONVERTORS` flag *must* be passed to both these functions to
+prevent recursive calls to the handwritten code.
+
+
+.. directive:: %Copying
+
+.. parsed-literal::
+
+    %Copying
+        *text*
+    %End
+
+This directive is used to specify some arbitrary text that will be included at
+the start of all source files generated by SIP.  It is normally used to
+include copyright and licensing terms.
+
+For example::
+
+    %Copying
+    Copyright (c) 2009 Riverbank Computing Limited
+    %End
+
+
+.. directive:: %DefaultEncoding
+
+.. parsed-literal::
+
+    %DefaultEncoding *string*
+
+This directive is used to specify the default encoding used for ``char``,
+``const char``, ``char *`` or ``const char *`` values.  The encoding can be
+either ``"ASCII"``, ``"Latin-1"``, ``"UTF-8"`` or ``"None"``.  An encoding of
+``"None"`` means that the value is unencoded.  The default can be overridden
+for a particular value using the :aanno:`Encoding` annotation.  If the
+directive is not specified then ``"None"`` is used.
+
+For example::
+
+    %DefaultEncoding "Latin-1"
+
+
+.. directive:: %DefaultMetatype
+
+.. parsed-literal::
+
+    %DefaultMetatype *dotted-name*
+
+This directive is used to specify the Python type that should be used as the
+meta-type for any C/C++ data type defined in the same module, and by importing
+modules, that doesn't have an explicit meta-type.
+
+If this is not specified then ``sip.wrappertype`` is used.
+
+You can also use the :canno:`Metatype` class annotation to specify the
+meta-type used by a particular C/C++ type.
+
+See the section :ref:`ref-types-metatypes` for more details.
+
+For example::
+
+    %DefaultMetatype PyQt4.QtCore.pyqtWrapperType
+
+
+.. directive:: %DefaultSupertype
+
+.. parsed-literal::
+
+    %DefaultSupertype *dotted-name*
+
+This directive is used to specify the Python type that should be used as the
+super-type for any C/C++ data type defined in the same module that doesn't have
+an explicit super-type.
+
+If this is not specified then ``sip.wrapper`` is used.
+
+You can also use the :canno:`Supertype` class annotation to specify the
+super-type used by a particular C/C++ type.
+
+See the section :ref:`ref-types-metatypes` for more details.
+
+For example::
+
+    %DefaultSupertype sip.simplewrapper
+
+
+.. directive:: %Doc
+
+.. parsed-literal::
+
+    %Doc
+        *text*
+    %End
+
+This directive is used to specify some arbitrary text that will be extracted
+by SIP when the ``-d`` command line option is used.  The directive can be
+specified any number of times and SIP will concatenate all the separate pieces
+of text in the order that it sees them.
+
+Documentation that is specified using this directive is local to the module in
+which it appears.  It is ignored by modules that :directive:`%Import` it.  Use
+the :directive:`%ExportedDoc` directive for documentation that should be
+included by all modules that :directive:`%Import` this one.
+
+For example::
+
+    %Doc
+    <h1>An Example</h1>
+    <p>
+    This fragment of documentation is HTML and is local to the module in
+    which it is defined.
+    </p>
+    %End
+
+
+.. directive:: %Docstring
+
+.. parsed-literal::
+
+    %Docstring
+        *text*
+    %End
+
+.. versionadded:: 4.10
+
+This directive is used to specify explicit docstrings for classes, functions
+and methods.
+
+The docstring of a class is made up of the docstring specified for the class
+itself, with the docstrings specified for each contructor appended.
+
+The docstring of a function or method is made up of the concatenated docstrings
+specified for each of the overloads.
+
+Specifying an explicit docstring will prevent SIP from generating an automatic
+docstring that describes the Python signature of a function or method overload.
+This means that SIP will generate less informative exceptions (i.e. without a
+full signature) when it fails to match a set of arguments to any function or
+method overload.
+
+For example::
+
+    class Klass
+    {
+    %Docstring
+    This will be at the start of the class's docstring.
+    %End
+
+    public:
+        Klass();
+    %Docstring
+    This will be appended to the class's docstring.
+    %End
+    };
+
+
+.. directive:: %End
+
+This isn't a directive in itself, but is used to terminate a number of
+directives that allow a block of handwritten code or text to be specified.
+
+
+.. directive:: %Exception
+
+.. parsed-literal::
+
+    %Exception *name* [(*base-exception)]
+    {
+        [*header-code*]
+        *raise-code*
+    };
+
+This directive is used to define new Python exceptions, or to provide a stub
+for existing Python exceptions.  It allows handwritten code to be provided
+that implements the translation between C++ exceptions and Python exceptions.
+The arguments to ``throw ()`` specifiers must either be names of classes or the
+names of Python exceptions defined by this directive.
+
+*name* is the name of the exception.
+
+*base-exception* is the optional base exception.  This may be either one of
+the standard Python exceptions or one defined with a previous
+:directive:`%Exception` directive.
+
+*header-code* is the optional :directive:`%TypeHeaderCode` used to specify any
+external interface to the exception being defined.
+
+*raise-code* is the :directive:`%RaiseCode` used to specify the handwritten
+code that converts a reference to the C++ exception to the Python exception.
+
+For example::
+
+    %Exception std::exception(SIP_Exception) /PyName=StdException/
+    {
+    %TypeHeaderCode
+    #include <exception>
+    %End
+    %RaiseCode
+            const char *detail = sipExceptionRef.what();
+
+            SIP_BLOCK_THREADS
+            PyErr_SetString(sipException_std_exception, detail);
+            SIP_UNBLOCK_THREADS
+    %End
+    };
+
+In this example we map the standard C++ exception to a new Python exception.
+The new exception is called ``StdException`` and is derived from the standard
+Python exception ``Exception``.
+
+An exception may be annotated with :xanno:`Default` to specify that it should
+be caught by default if there is no ``throw`` clause.
+
+
+.. directive:: %ExportedDoc
+
+.. parsed-literal::
+
+    %ExportedDoc
+        *text*
+    %End
+
+This directive is used to specify some arbitrary text that will be extracted
+by SIP when the ``-d`` command line option is used.  The directive can be
+specified any number of times and SIP will concatenate all the separate pieces
+of text in the order that it sees them.
+
+Documentation that is specified using this directive will also be included by
+modules that :directive:`%Import` it.
+
+For example::
+
+    %ExportedDoc
+    ==========
+    An Example
+    ==========
+    
+    This fragment of documentation is reStructuredText and will appear in the
+    module in which it is defined and all modules that %Import it.
+    %End
+
+
+.. directive:: %ExportedHeaderCode
+
+.. parsed-literal::
+
+    %ExportedHeaderCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code, typically the declarations
+of types, that is placed in a header file that is included by all generated
+code for all modules.  It should not include function declarations because
+Python modules should not explicitly call functions in another Python module.
+
+See also :directive:`%ModuleCode` and :directive:`%ModuleHeaderCode`.
+
+
+.. directive:: %Feature
+
+.. parsed-literal::
+
+    %Feature *name*
+
+This directive is used to declare a feature.  Features (along with
+:directive:`%Platforms` and :directive:`%Timeline`) are used by the
+:directive:`%If` directive to control whether or not parts of a specification
+are processed or ignored.
+
+Features are mutually independent of each other - any combination of features
+may be enabled or disable.  By default all features are enabled.  The SIP
+``-x`` command line option is used to disable a feature.
+
+If a feature is enabled then SIP will automatically generate a corresponding C
+preprocessor symbol for use by handwritten code.  The symbol is the name of
+the feature prefixed by ``SIP_FEATURE_``.
+
+For example::
+
+    %Feature FOO_SUPPORT
+
+    %If (FOO_SUPPORT)
+    void foo();
+    %End
+
+
+.. directive:: %GCClearCode
+
+.. parsed-literal::
+
+    %GCClearCode
+        *code*
+    %End
+
+Python has a cyclic garbage collector which can identify and release unneeded
+objects even when their reference counts are not zero.  If a wrapped C
+structure or C++ class keeps its own reference to a Python object then, if the
+garbage collector is to do its job, it needs to provide some handwritten code
+to traverse and potentially clear those embedded references.
+
+See the section *Supporting cyclic garbage collection* in `Embedding and
+Extending the Python Interpreter <http://www.python.org/dev/doc/devel/ext/>`__
+for the details.
+
+This directive is used to specify the code that clears any embedded references.
+(See :directive:`%GCTraverseCode` for specifying the code that traverses any
+embedded references.)
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+int sipRes
+    The handwritten code should set this to the result to be returned.
+
+The following simplified example is taken from PyQt.  The ``QCustomEvent``
+class allows arbitary data to be attached to the event.  In PyQt this data is
+always a Python object and so should be handled by the garbage collector::
+
+    %GCClearCode
+        PyObject *obj;
+
+        // Get the object.
+        obj = reinterpret_cast<PyObject *>(sipCpp->data());
+
+        // Clear the pointer.
+        sipCpp->setData(0);
+
+        // Clear the reference.
+        Py_XDECREF(obj);
+
+        // Report no error.
+        sipRes = 0;
+    %End
+
+
+.. directive:: %GCTraverseCode
+
+.. parsed-literal::
+
+    %GCTraverseCode
+        *code*
+    %End
+
+This directive is used to specify the code that traverses any embedded
+references for Python's cyclic garbage collector.  (See
+:directive:`%GCClearCode` for a full explanation.)
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+visitproc sipVisit
+    This is the visit function provided by the garbage collector.
+
+void \*sipArg
+    This is the argument to the visit function provided by the garbage
+    collector.
+
+int sipRes
+    The handwritten code should set this to the result to be returned.
+
+The following simplified example is taken from PyQt's ``QCustomEvent`` class::
+
+    %GCTraverseCode
+        PyObject *obj;
+
+        // Get the object.
+        obj = reinterpret_cast<PyObject *>(sipCpp->data());
+
+        // Call the visit function if there was an object.
+        if (obj)
+            sipRes = sipVisit(obj, sipArg);
+        else
+            sipRes = 0;
+    %End
+
+
+.. directive:: %GetCode
+
+.. parsed-literal::
+
+    %GetCode
+        *code*
+    %End
+
+This directive is used after the declaration of a C++ class variable or C
+structure member to specify handwritten code to convert it to a Python object.
+It is usually used to handle types that SIP cannot deal with automatically.
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.  It is not made available if the
+    variable being wrapped is a static class variable.
+
+PyObject \*sipPy
+    The handwritten code must set this to the Python representation of the
+    class variable or structure member.  If there is an error then the code
+    must raise an exception and set this to ``NULL``.
+
+PyObject \*sipPyType
+    If the variable being wrapped is a static class variable then this is the
+    Python type object of the class from which the variable was referenced
+    (*not* the class in which it is defined).  It may be safely cast to a
+    PyTypeObject \* or a sipWrapperType \*.
+
+For example::
+
+    struct Entity
+    {
+        /*
+         * In this contrived example the C library we are wrapping actually
+         * defines this as char buffer[100] which SIP cannot handle
+         * automatically.
+         */
+        char *buffer;
+    %GetCode
+            sipPy = PyString_FromStringAndSize(sipCpp->buffer, 100);
+    %End
+    %SetCode
+            char *ptr;
+            int length;
+
+            if (PyString_AsStringAndSize(sipPy, &ptr, &length) == -1)
+                sipErr = 1;
+            else if (length != 100)
+            {
+                /*
+                 * Raise an exception because the length isn't exactly right.
+                 */
+
+                PyErr_SetString(PyExc_ValueError, "an Entity.buffer must be exactly 100 bytes");
+                sipErr = 1;
+            }
+            else
+                memcpy(sipCpp->buffer, ptr, 100);
+    %End
+    }
+
+
+.. directive:: %If
+
+.. parsed-literal::
+
+    %If (*expression*)
+        *specification*
+    %End
+
+where
+
+.. parsed-literal::
+
+    *expression* ::= [*ored-qualifiers* | *range*]
+
+    *ored-qualifiers* ::= [*qualifier* | *qualifier* **||** *ored-qualifiers*]
+
+    *qualifier* ::= [**!**] [*feature* | *platform*]
+
+    *range* ::= [*version*] **-** [*version*]
+
+This directive is used in conjunction with features (see
+:directive:`%Feature`), platforms (see :directive:`%Platforms`) and versions
+(see :directive:`%Timeline`) to control whether or not parts of a specification
+are processed or not.
+
+A *range* of versions means all versions starting with the lower bound up to
+but excluding the upper bound.  If the lower bound is omitted then it is
+interpreted as being before the earliest version.  If the upper bound is
+omitted then it is interpreted as being after the latest version.
+
+For example::
+
+    %Feature SUPPORT_FOO
+    %Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM}
+    %Timeline {V1_0 V1_1 V2_0 V3_0}
+
+    %If (!SUPPORT_FOO)
+        // Process this if the SUPPORT_FOO feature is disabled.
+    %End
+
+    %If (POSIX_PLATFORM || MACOS_PLATFORM)
+        // Process this if either the POSIX_PLATFORM or MACOS_PLATFORM
+        // platforms are enabled.
+    %End
+
+    %If (V1_0 - V2_0)
+        // Process this if either V1_0 or V1_1 is enabled.
+    %End
+
+    %If (V2_0 - )
+        // Process this if either V2_0 or V3_0 is enabled.
+    %End
+
+    %If ( - )
+        // Always process this.
+    %End
+
+Note that this directive is not implemented as a preprocessor.  Only the
+following parts of a specification are affected by it:
+
+    - :directive:`%API`
+    - ``class``
+    - :directive:`%ConvertFromTypeCode`
+    - :directive:`%ConvertToSubClassCode`
+    - :directive:`%ConvertToTypeCode`
+    - ``enum``
+    - :directive:`%DefaultEncoding`
+    - :directive:`%DefaultMetatype`
+    - :directive:`%DefaultSupertype`
+    - :directive:`%ExportedHeaderCode`
+    - functions
+    - :directive:`%GCClearCode`
+    - :directive:`%GCTraverseCode`
+    - :directive:`%If`
+    - :directive:`%InitialisationCode`
+    - :directive:`%MappedType`
+    - :directive:`%MethodCode`
+    - :directive:`%ModuleCode`
+    - :directive:`%ModuleHeaderCode`
+    - ``namespace``
+    - :directive:`%PostInitialisationCode`
+    - :directive:`%PreInitialisationCode`
+    - ``struct``
+    - ``typedef``
+    - :directive:`%TypeCode`
+    - :directive:`%TypeHeaderCode`
+    - :directive:`%UnitCode`
+    - variables
+    - :directive:`%VirtualCatcherCode`
+
+Also note that the only way to specify the logical and of qualifiers is to use
+nested :directive:`%If` directives.
+
+
+.. directive:: %Import
+
+.. parsed-literal::
+
+    %Import *filename*
+
+This directive is used to import the specification of another module.  This is
+needed if the current module makes use of any types defined in the imported
+module, e.g. as an argument to a function, or to sub-class.
+
+If *filename* cannot be opened then SIP prepends *filename* with the name of
+the directory containing the current specification file (i.e. the one
+containing the :directive:`%Import` directive) and tries again.  If this also
+fails then SIP prepends *filename* with each of the directories, in turn,
+specified by the ``-I`` command line option.
+
+For example::
+
+    %Import qt/qtmod.sip
+
+
+.. directive:: %Include
+
+.. parsed-literal::
+
+    %Include *filename*
+
+This directive is used to include contents of another file as part of the
+specification of the current module.  It is the equivalent of the C
+preprocessor's ``#include`` directive and is used to structure a large module
+specification into manageable pieces.
+
+:directive:`%Include` follows the same search process as :directive:`%Import`
+when trying to open *filename*.
+
+For example::
+
+    %Include qwidget.sip
+
+
+.. directive:: %InitialisationCode
+
+.. parsed-literal::
+
+    %InitialisationCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code that is embedded in-line
+in the generated module initialisation code after the SIP module has been
+imported but before the module itself has been initialised.
+
+It is typically used to call :cfunc:`sipRegisterPyType()`.
+
+For example::
+
+    %InitialisationCode
+        // The code will be executed when the module is first imported, after
+        // the SIP module has been imported, but before other module-specific
+        // initialisation has been completed.
+    %End
+
+
+.. directive:: %License
+
+.. parsed-literal::
+
+    %License /*license-annotations*/
+
+This directive is used to specify the contents of an optional license
+dictionary.  The license dictionary is called :data:`__license__` and is stored
+in the module dictionary.  The elements of the dictionary are specified using
+the :lanno:`Licensee`, :lanno:`Signature`, :lanno:`Timestamp` and :lanno:`Type`
+annotations.  Only the :lanno:`Type` annotation is compulsory.
+
+Note that this directive isn't an attempt to impose any licensing restrictions
+on a module.  It is simply a method for easily embedding licensing information
+in a module so that it is accessible to Python scripts.
+
+For example::
+
+    %License /Type="GPL"/
+
+
+.. directive:: %MappedType
+
+.. parsed-literal::
+
+    template<*type-list*>
+    %MappedType *type*
+    {
+        [*header-code*]
+        [*convert-to-code*]
+        [*convert-from-code*]
+    };
+
+    %MappedType *type*
+    {
+        [*header-code*]
+        [*convert-to-code*]
+        [*convert-from-code*]
+    };
+
+This directive is used to define an automatic mapping between a C or C++ type
+and a Python type.  It can be used as part of a template, or to map a specific
+type.
+
+When used as part of a template *type* cannot itself refer to a template.  Any
+occurrences of any of the type names (but not any ``*`` or ``&``) in
+*type-list* will be replaced by the actual type names used when the template is
+instantiated.  Template mapped types are instantiated automatically as required
+(unlike template classes which are only instantiated using ``typedef``).
+
+Any explicit mapped type will be used in preference to any template that maps
+the same type, ie. a template will not be automatically instantiated if there
+is an explicit mapped type.
+
+*header-code* is the :directive:`%TypeHeaderCode` used to specify the library
+interface to the type being mapped.
+
+*convert-to-code* is the :directive:`%ConvertToTypeCode` used to specify the
+handwritten code that converts a Python object to an instance of the mapped
+type.
+
+*convert-from-code* is the :directive:`%ConvertFromTypeCode` used to specify
+the handwritten code that converts an instance of the mapped type to a Python
+object.
+
+For example::
+
+    template<Type *>
+    %MappedType QList
+    {
+    %TypeHeaderCode
+    // Include the library interface to the type being mapped.
+    #include <qlist.h>
+    %End
+
+    %ConvertToTypeCode
+        // See if we are just being asked to check the type of the Python
+        // object.
+        if (sipIsErr == NULL)
+        {
+            // Check it is a list.
+            if (!PyList_Check(sipPy))
+                return 0;
+
+            // Now check each element of the list is of the type we expect.
+            // The template is for a pointer type so we don't disallow None.
+            for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
+                if (!sipCanConvertToType(PyList_GET_ITEM(sipPy, i),
+                                         sipType_Type, 0))
+                    return 0;
+
+            return 1;
+        }
+
+        // Create the instance on the heap.
+        QList<Type *> *ql = new QList<Type *>;
+
+        for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
+        {
+            // Use the SIP API to convert the Python object to the
+            // corresponding C++ instance.  Note that we apply any ownership
+            // transfer to the list itself, not the individual elements.
+            Type *t = reinterpret_cast<Type *>(sipConvertToType(
+                                                PyList_GET_ITEM(sipPy, i),
+                                                sipType_Type, 0, 0, 0,
+                                                sipIsErr));
+
+            if (*sipIsErr)
+            {
+                // Tidy up.
+                delete ql;
+
+                // There is nothing on the heap.
+                return 0;
+            }
+
+            // Add the pointer to the C++ instance.
+            ql->append(t);
+        }
+
+        // Return the instance on the heap.
+        *sipCppPtr = ql;
+
+        // Apply the normal transfer.
+        return sipGetState(sipTransferObj);
+    %End
+
+    %ConvertFromTypeCode
+        PyObject *l;
+
+        // Create the Python list of the correct length.
+        if ((l = PyList_New(sipCpp->size())) == NULL)
+            return NULL;
+
+        // Go through each element in the C++ instance and convert it to the
+        // corresponding Python object.
+        for (int i = 0; i < sipCpp->size(); ++i)
+        {
+            Type *t = sipCpp->at(i);
+            PyObject *tobj;
+
+            if ((tobj = sipConvertFromType(t, sipType_Type, sipTransferObj)) == NULL)
+            {
+                // There was an error so garbage collect the Python list.
+                Py_DECREF(l);
+                return NULL;
+            }
+
+            PyList_SET_ITEM(l, i, tobj);
+        }
+
+        // Return the Python list.
+        return l;
+    %End
+    }
+
+Using this we can use, for example, ``QList<QObject *>`` throughout the
+module's specification files (and in any module that imports this one).  The
+generated code will automatically map this to and from a Python list of QObject
+instances when appropriate.
+
+
+.. directive:: %MethodCode
+
+.. parsed-literal::
+
+    %MethodCode
+        *code*
+    %End
+
+This directive is used as part of the specification of a global function, class
+method, operator, constructor or destructor to specify handwritten code that
+replaces the normally generated call to the function being wrapped.  It is
+usually used to handle argument types and results that SIP cannot deal with
+automatically.
+
+Normally the specified code is embedded in-line after the function's arguments
+have been successfully converted from Python objects to their C or C++
+equivalents.  In this case the specified code must not include any ``return``
+statements.
+
+However if the :fanno:`NoArgParser` annotation has been used then the specified
+code is also responsible for parsing the arguments.  No other code is generated
+by SIP and the specified code must include a ``return`` statement.
+
+In the context of a destructor the specified code is embedded in-line in the
+Python type's deallocation function.  Unlike other contexts it supplements
+rather than replaces the normally generated code, so it must not include code
+to return the C structure or C++ class instance to the heap.  The code is only
+called if ownership of the structure or class is with Python.
+
+The specified code must also handle the Python Global Interpreter Lock (GIL).
+If compatibility with SIP v3.x is required then the GIL must be released
+immediately before the C++ call and reacquired immediately afterwards as shown
+in this example fragment::
+
+    Py_BEGIN_ALLOW_THREADS
+    sipCpp->foo();
+    Py_END_ALLOW_THREADS
+
+If compatibility with SIP v3.x is not required then this is optional but
+should be done if the C++ function might block the current thread or take a
+significant amount of time to execute.  (See :ref:`ref-gil` and the
+:fanno:`ReleaseGIL` and :fanno:`HoldGIL` annotations.)
+
+If the :fanno:`NoArgParser` annotation has not been used then the following
+variables are made available to the handwritten code:
+
+*type* a0
+    There is a variable for each argument of the Python signature (excluding
+    any ``self`` argument) named ``a0``, ``a1``, etc.  The *type* of the
+    variable is the same as the type defined in the specification with the
+    following exceptions:
+
+    - if the argument is only used to return a value (e.g. it is an ``int *``
+      without an :aanno:`In` annotation) then the type has one less level of
+      indirection (e.g. it will be an ``int``)
+    - if the argument is a structure or class (or a reference or a pointer to a
+      structure or class) then *type* will always be a pointer to the structure
+      or class.
+
+    Note that handwritten code for destructors never has any arguments.
+
+PyObject \*a0Wrapper
+    This variable is made available only if the :aanno:`GetWrapper` annotation
+    is specified for the corresponding argument.  The variable is a pointer to
+    the Python object that wraps the argument.
+
+*type* \*sipCpp
+    If the directive is used in the context of a class constructor then this
+    must be set by the handwritten code to the constructed instance.  If it is
+    set to ``0`` and no Python exception is raised then SIP will continue to
+    try other Python signatures.
+    
+    If the directive is used in the context of a method (but not the standard
+    binary operator methods, e.g. :meth:`__add__`) or a destructor then this is
+    a pointer to the C structure or C++ class instance.
+    
+    Its *type* is a pointer to the structure or class.
+    
+    Standard binary operator methods follow the same convention as global
+    functions and instead define two arguments called ``a0`` and ``a1``.
+
+sipErrorState sipError
+    The handwritten code should set this to either ``sipErrorContinue`` or
+    ``sipErrorFail``, and raise an appropriate Python exception, if an error
+    is detected.  Its initial value will be ``sipErrorNone``.
+
+    When ``sipErrorContinue`` is used, SIP will remember the exception as the
+    reason why the particular overloaded callable could not be invoked.  It
+    will then continue to try the next overloaded callable.  It is typically
+    used by code that needs to do additional type checking of the callable's
+    arguments.
+
+    When ``sipErrorFail1`` is used, SIP will report the exception immediately
+    and will not attempt to invoke other overloaded callables.
+
+    ``sipError`` is not provided for destructors.
+
+int sipIsErr
+    The handwritten code should set this to a non-zero value, and raise an
+    appropriate Python exception, if an error is detected.  This is the
+    equivalent of setting ``sipError`` to ``sipErrorFail``.  Its initial value
+    will be ``0``.
+
+    ``sipIsErr`` is not provided for destructors.
+
+*type* sipRes
+    The handwritten code should set this to the result to be returned.  The
+    *type* of the variable is the same as the type defined in the Python
+    signature in the specification with the following exception:
+
+    - if the argument is a structure or class (or a reference or a pointer to a
+      structure or class) then *type* will always be a pointer to the structure
+      or class.
+
+    ``sipRes`` is not provided for inplace operators (e.g. ``+=`` or
+    :meth:`__imul__`) as their results are handled automatically, nor for class
+    constructors or destructors.
+
+PyObject \*sipSelf
+    If the directive is used in the context of a class constructor, destructor
+    or method then this is the Python object that wraps the structure or class
+    instance, i.e. ``self``.
+
+bool sipSelfWasArg
+    This is only made available for non-abstract, virtual methods.  It is set
+    if ``self`` was explicitly passed as the first argument of the method
+    rather than being bound to the method.  In other words, the call was::
+
+        Klass.foo(self, ...)
+
+    rather than::
+
+        self.foo(...)
+
+If the :fanno:`NoArgParser` annotation has been used then only the following
+variables are made available to the handwritten code:
+
+PyObject \*sipArgs
+    This is the tuple of arguments.
+
+PyObject \*sipKwds
+    This is the dictionary of keyword arguments.
+
+The following is a complete example::
+
+    class Klass
+    {
+    public:
+        virtual int foo(SIP_PYTUPLE);
+    %MethodCode
+            // The C++ API takes a 2 element array of integers but passing a
+            // two element tuple is more Pythonic.
+
+            int iarr[2];
+
+            if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1]))
+            {
+                Py_BEGIN_ALLOW_THREADS
+                sipRes = sipSelfWasArg ? sipCpp->Klass::foo(iarr)
+                                       : sipCpp->foo(iarr);
+                Py_END_ALLOW_THREADS
+            }
+            else
+            {
+                // PyArg_ParseTuple() will have raised the exception.
+                sipIsErr = 1;
+            }
+    %End
+    };
+
+As the example is a virtual method [#]_, note the use of ``sipSelfWasArg`` to
+determine exactly which implementation of ``foo()`` to call.
+
+If a method is in the ``protected`` section of a C++ class then SIP generates
+helpers that provide access to method.  However, these are not available if
+the Python module is being built with ``protected`` redefined as ``public``.
+
+The following pattern should be used to cover all possibilities::
+
+    #if defined(SIP_PROTECTED_IS_PUBLIC)
+        sipRes = sipSelfWasArg ? sipCpp->Klass::foo(iarr)
+                               : sipCpp->foo(iarr);
+    #else
+        sipRes = sipCpp->sipProtectVirt_foo(sipSelfWasArg, iarr);
+    #endif
+
+If a method is in the ``protected`` section of a C++ class but is not virtual
+then the pattern should instead be::
+
+    #if defined(SIP_PROTECTED_IS_PUBLIC)
+        sipRes = sipCpp->foo(iarr);
+    #else
+        sipRes = sipCpp->sipProtect_foo(iarr);
+    #endif
+
+.. [#] See :directive:`%VirtualCatcherCode` for a description of how SIP
+       generated code handles the reimplementation of C++ virtual methods in
+       Python.
+
+
+.. directive:: %Module
+
+.. parsed-literal::
+
+    %Module *name* [*version*]
+
+This directive is used to identify that the library being wrapped is a C++
+library and to define the name of the module and it's optional version number.
+
+The name may contain periods to specify that the module is part of a Python
+package.
+
+The optional version number is useful if you (or others) might create other
+modules that build on this module, i.e. if another module might
+:directive:`%Import` this module.  Under the covers, a module exports an API
+that is used by modules that :directive:`%Import` it and the API is given a
+version number.  A module built on that module knows the version number of the
+API that it is expecting.  If, when the modules are imported at run-time, the
+version numbers do not match then a Python exception is raised.  The dependent
+module must then be re-built using the correct specification files for the base
+module.
+
+The version number should be incremented whenever a module is changed.  Some
+changes don't affect the exported API, but it is good practice to change the
+version number anyway.
+
+For example::
+
+    %Module qt 5
+
+
+.. directive:: %ModuleCode
+
+.. parsed-literal::
+
+    %ModuleCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code, typically the
+implementations of utility functions, that can be called by other handwritten
+code in the module.
+
+For example::
+
+    %ModuleCode
+    // Print an object on stderr for debugging purposes.
+    void dump_object(PyObject *o)
+    {
+        PyObject_Print(o, stderr, 0);
+        fprintf(stderr, "\n");
+    }
+    %End
+
+See also :directive:`%ExportedHeaderCode` and :directive:`%ModuleHeaderCode`.
+
+
+.. directive:: %ModuleHeaderCode
+
+.. parsed-literal::
+
+    %ModuleHeaderCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code, typically the declarations
+of utility functions, that is placed in a header file that is included by all
+generated code for the same module.
+
+For example::
+
+    %ModuleHeaderCode
+    void dump_object(PyObject *o);
+    %End
+
+See also :directive:`%ExportedHeaderCode` and :directive:`%ModuleCode`.
+
+
+.. directive:: %OptionalInclude
+
+.. parsed-literal::
+
+    %OptionalInclude *filename*
+
+This directive is identical to the :directive:`%Include` directive except that
+SIP silently continues processing if *filename* could not be opened.
+
+For example::
+
+    %OptionalInclude license.sip
+
+
+.. directive:: %PickleCode
+
+.. parsed-literal::
+
+    %PickleCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code to pickle a C structure or
+C++ class instance.
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+PyObject \*sipRes
+    The handwritten code must set this to a tuple of the arguments that will
+    be passed to the type's __init__() method when the structure or class
+    instance is unpickled.  If there is an error then the code must raise an
+    exception and set this to ``NULL``.
+
+For example::
+
+    class Point
+    {
+        Point(int x, y);
+
+        int x() const;
+        int y() const;
+
+    %PickleCode
+        sipRes = Py_BuildValue("ii", sipCpp->x(), sipCpp->y());
+    %End
+    }
+
+Note that SIP works around the Python limitation that prevents nested types
+being pickled.
+
+Both named and unnamed enums can be pickled automatically without providing any
+handwritten code.
+
+
+.. directive:: %Platforms
+
+.. parsed-literal::
+
+    %Platforms {*name* *name* ...}
+
+This directive is used to declare a set of platforms.  Platforms (along with
+:directive:`%Feature` and :directive:`%Timeline`) are used by the
+:directive:`%If` directive to control whether or not parts of a specification
+are processed or ignored.
+
+Platforms are mutually exclusive - only one platform can be enabled at a time.
+By default all platforms are disabled.  The SIP ``-t`` command line option is
+used to enable a platform.
+
+For example::
+
+    %Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM}
+
+    %If (WIN32_PLATFORM)
+    void undocumented();
+    %End
+
+    %If (POSIX_PLATFORM)
+    void documented();
+    %End
+
+
+.. directive:: %PostInitialisationCode
+
+.. parsed-literal::
+
+    %PostInitialisationCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code that is embedded in-line
+at the very end of the generated module initialisation code.
+
+The following variables are made available to the handwritten code:
+
+PyObject \*sipModule
+    This is the module object returned by ``Py_InitModule()``.
+
+PyObject \*sipModuleDict
+    This is the module's dictionary object returned by ``Py_ModuleGetDict()``.
+
+For example::
+
+    %PostInitialisationCode
+        // The code will be executed when the module is first imported and
+        // after all other initialisation has been completed.
+    %End
+
+
+.. directive:: %PreInitialisationCode
+
+.. parsed-literal::
+
+    %PreInitialisationCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code that is embedded in-line
+at the very start of the generated module initialisation code.
+
+For example::
+
+    %PreInitialisationCode
+        // The code will be executed when the module is first imported and
+        // before other initialisation has been completed.
+    %End
+
+
+.. directive:: %RaiseCode
+
+.. parsed-literal::
+
+    %RaiseCode
+        *code*
+    %End
+
+This directive is used as part of the definition of an exception using the
+:directive:`%Exception` directive to specify handwritten code that raises a
+Python exception when a C++ exception has been caught.  The code is embedded
+in-line as the body of a C++ ``catch ()`` clause.
+
+The specified code must handle the Python Global Interpreter Lock (GIL) if
+necessary.  The GIL must be acquired before any calls to the Python API and
+released after the last call as shown in this example fragment::
+
+    SIP_BLOCK_THREADS
+    PyErr_SetNone(PyErr_Exception);
+    SIP_UNBLOCK_THREADS
+
+Finally, the specified code must not include any ``return`` statements.
+
+The following variable is made available to the handwritten code:
+
+*type* &sipExceptionRef
+    This is a reference to the caught C++ exception.  The *type* of the
+    reference is the same as the type defined in the ``throw ()`` specifier.
+
+See the :directive:`%Exception` directive for an example.
+
+
+.. directive:: %SetCode
+
+.. parsed-literal::
+
+    %SetCode
+        *code*
+    %End
+
+This directive is used after the declaration of a C++ class variable or C
+structure member to specify handwritten code to convert it from a Python
+object.  It is usually used to handle types that SIP cannot deal with
+automatically.
+
+The following variables are made available to the handwritten code:
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.  It is not made available if the
+    variable being wrapped is a static class variable.
+
+int sipErr
+    If the conversion failed then the handwritten code should raise a Python
+    exception and set this to a non-zero value.  Its initial value will be
+    automatically set to zero.
+
+PyObject \*sipPy
+    This is the Python object that the handwritten code should convert.
+
+PyObject \*sipPyType
+    If the variable being wrapped is a static class variable then this is the
+    Python type object of the class from which the variable was referenced
+    (*not* the class in which it is defined).  It may be safely cast to a
+    PyTypeObject \* or a sipWrapperType \*.
+
+See the :directive:`%GetCode` directive for an example.
+
+
+.. directive:: %Timeline
+
+.. parsed-literal::
+
+    %Timeline {*name* *name* ...}
+
+This directive is used to declare a set of versions released over a period of
+time.  Versions (along with :directive:`%Feature` and :directive:`%Platforms`)
+are used by the :directive:`%If` directive to control whether or not parts of a
+specification are processed or ignored.
+
+Versions are mutually exclusive - only one version can be enabled at a time.
+By default all versions are disabled.  The SIP ``-t`` command line option is
+used to enable a version.
+
+For example::
+
+    %Timeline {V1_0 V1_1 V2_0 V3_0}
+
+    %If (V1_0 - V2_0)
+    void foo();
+    %End
+
+    %If (V2_0 -)
+    void foo(int = 0);
+    %End
+
+:directive:`%Timeline` can be used any number of times in a module to allow
+multiple libraries to be wrapped in the same module.
+
+
+.. directive:: %TypeCode
+
+.. parsed-literal::
+
+    %TypeCode
+        *code*
+    %End
+
+This directive is used as part of the specification of a C structure or a C++
+class to specify handwritten code, typically the implementations of utility
+functions, that can be called by other handwritten code in the structure or
+class.
+
+For example::
+
+    class Klass
+    {
+    %TypeCode
+    // Print an instance on stderr for debugging purposes.
+    static void dump_klass(const Klass *k)
+    {
+        fprintf(stderr,"Klass %s at %p\n", k->name(), k);
+    }
+    %End
+
+        // The rest of the class specification.
+
+    };
+
+Because the scope of the code is normally within the generated file that
+implements the type, any utility functions would normally be declared
+``static``.  However a naming convention should still be adopted to prevent
+clashes of function names within a module in case the SIP ``-j`` command line
+option is used.
+
+
+.. directive:: %TypeHeaderCode
+
+.. parsed-literal::
+
+    %TypeHeaderCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code that defines the interface
+to a C or C++ type being wrapped, either a structure, a class, or a template.
+It is used within a class definition or a :directive:`%MappedType` directive.
+
+Normally *code* will be a pre-processor ``#include`` statement.
+
+For example::
+
+    // Wrap the Klass class.
+    class Klass
+    {
+    %TypeHeaderCode
+    #include <klass.h>
+    %End
+
+        // The rest of the class specification.
+    };
+
+
+.. directive:: %UnitCode
+
+.. parsed-literal::
+
+    %UnitCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code that it included at the very
+start of a generated compilation unit (ie. C or C++ source file).  It is
+typically used to ``#include`` a C++ precompiled header file.
+
+
+.. directive:: %VirtualCatcherCode
+
+.. parsed-literal::
+
+    %VirtualCatcherCode
+        *code*
+    %End
+
+For most classes there are corresponding :ref:`generated derived classes
+<ref-derived-classes>` that contain reimplementations of the class's virtual
+methods.  These methods (which SIP calls catchers) determine if there is a
+corresponding Python reimplementation and call it if so.  If there is no Python
+reimplementation then the method in the original class is called instead.
+
+This directive is used to specify handwritten code that replaces the normally
+generated call to the Python reimplementation and the handling of any returned
+results.  It is usually used to handle argument types and results that SIP
+cannot deal with automatically.
+
+This directive can also be used in the context of a class destructor to
+specify handwritten code that is embedded in-line in the internal derived
+class's destructor.
+
+In the context of a method the Python Global Interpreter Lock (GIL) is
+automatically acquired before the specified code is executed and automatically
+released afterwards.
+
+In the context of a destructor the specified code must handle the GIL.  The
+GIL must be acquired before any calls to the Python API and released after the
+last call as shown in this example fragment::
+
+    SIP_BLOCK_THREADS
+    Py_DECREF(obj);
+    SIP_UNBLOCK_THREADS
+
+The following variables are made available to the handwritten code in the
+context of a method:
+
+*type* a0
+    There is a variable for each argument of the C++ signature named ``a0``,
+    ``a1``, etc.  The *type* of the variable is the same as the type defined in
+    the specification.
+
+int a0Key
+    There is a variable for each argument of the C++ signature that has a type
+    where it is important to ensure that the corresponding Python object is not
+    garbage collected too soon.  This only applies to output arguments that
+    return ``'\0'`` terminated strings.  The variable would normally be passed
+    to :cfunc:`sipParseResult()` using either the ``A`` or ``B`` format
+    characters.
+
+int sipIsErr
+    The handwritten code should set this to a non-zero value, and raise an
+    appropriate Python exception, if an error is detected.
+
+PyObject \*sipMethod
+    This object is the Python reimplementation of the virtual C++ method.  It
+    is normally passed to :cfunc:`sipCallMethod()`.
+
+*type* sipRes
+    The handwritten code should set this to the result to be returned.  The
+    *type* of the variable is the same as the type defined in the C++ signature
+    in the specification.
+
+int sipResKey
+    This variable is only made available if the result has a type where it is
+    important to ensure that the corresponding Python object is not garbage
+    collected too soon.  This only applies to ``'\0'`` terminated strings.  The
+    variable would normally be passed to :cfunc:`sipParseResult()` using either
+    the ``A`` or ``B`` format characters.
+
+sipSimpleWrapper \*sipPySelf
+    This variable is only made available if either the ``a0Key`` or
+    ``sipResKey`` are made available.  It defines the context within which keys
+    are unique.  The variable would normally be passed to
+    :cfunc:`sipParseResult()` using the ``S`` format character.
+
+No variables are made available in the context of a destructor.
+
+For example::
+
+    class Klass
+    {
+    public:
+        virtual int foo(SIP_PYTUPLE) [int (int *)];
+    %MethodCode
+            // The C++ API takes a 2 element array of integers but passing a
+            // two element tuple is more Pythonic.
+
+            int iarr[2];
+
+            if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1]))
+            {
+                Py_BEGIN_ALLOW_THREADS
+                sipRes = sipCpp->Klass::foo(iarr);
+                Py_END_ALLOW_THREADS
+            }
+            else
+            {
+                // PyArg_ParseTuple() will have raised the exception.
+                sipIsErr = 1;
+            }
+    %End
+    %VirtualCatcherCode
+            // Convert the 2 element array of integers to the two element
+            // tuple.
+
+            PyObject *result;
+
+            result = sipCallMethod(&sipIsErr, sipMethod, "ii", a0[0], a0[1]);
+
+            if (result != NULL)
+            {
+                // Convert the result to the C++ type.
+                sipParseResult(&sipIsErr, sipMethod, result, "i", &sipRes);
+
+                Py_DECREF(result);
+            }
+    %End
+    };
diff --git a/sphinx/distutils.rst b/sphinx/distutils.rst
new file mode 100644
index 0000000..21a6b36
--- /dev/null
+++ b/sphinx/distutils.rst
@@ -0,0 +1,41 @@
+.. _ref-distutils:
+
+Building Your Extension with distutils
+======================================
+
+To build the example in :ref:`ref-simple-c++-example` using distutils, it is
+sufficient to create a standard ``setup.py``, listing ``word.sip`` among the
+files to build, and hook-up SIP into distutils::
+
+    from distutils.core import setup, Extension
+    import sipdistutils
+
+    setup(
+      name = 'word',
+      versione = '1.0',
+      ext_modules=[
+        Extension("word", ["word.sip", "word.cpp"]),
+        ],
+
+      cmdclass = {'build_ext': sipdistutils.build_ext}
+    )
+
+As we can see, the above is a normal distutils setup script, with just a
+special line which is needed so that SIP can see and process ``word.sip``.
+Then, running ``setup.py build`` will build our extension module.
+
+If you want to use any of sip's command-line options described in
+:ref:`ref-command-line`, there is a new option available for the
+``build_ext`` command in distutils: ``--sip-opts``. So you can either invoke
+distutils as follows::
+
+     $ python setup.py build_ext --sip-opts="-e -g" build
+
+or you can leverage distutils' config file support by creating a ``setup.cfg``
+file in the supported system or local paths (eg: in the same directory of
+``setup.py``) with these contents::
+
+     [build_ext]
+     sip-opts = -e -g
+
+and then run ``setup.py build`` as usual.
diff --git a/sphinx/embedding.rst b/sphinx/embedding.rst
new file mode 100644
index 0000000..114e3e8
--- /dev/null
+++ b/sphinx/embedding.rst
@@ -0,0 +1,62 @@
+Using the C API when Embedding
+==============================
+
+The :ref:`C API <ref-c-api>` is intended to be called from handwritten code in
+SIP generated modules.  However it is also often necessary to call it from C or
+C++ applications that embed the Python interpreter and need to pass C or C++
+instances between the application and the interpreter.
+
+The API is exported by the SIP module as a ``sipAPIDef`` data structure
+containing a set of function pointers.  The data structure is defined in the
+SIP header file ``sip.h``.  The data structure is wrapped as a Python
+``PyCObject`` object and is referenced by the name ``_C_API`` in the SIP
+module dictionary.
+
+Each member of the data structure is a pointer to one of the functions of the
+SIP API.  The name of the member can be derived from the function name by
+replacing the ``sip`` prefix with ``api`` and converting each word in the
+name to lower case and preceding it with an underscore.  For example:
+
+    ``sipExportSymbol`` becomes ``api_export_symbol``
+
+    ``sipWrapperCheck`` becomes ``api_wrapper_check``
+
+Note that the type objects that SIP generates for a wrapped module (see
+:ref:`ref-type-structures`, :ref:`ref-enum-type-objects` and
+:ref:`ref-exception-objects`) cannot be refered to directly and must be
+obtained using the :cfunc:`sipFindType()` function.  Of course, the
+corresponding modules must already have been imported into the interpreter.
+
+The following code fragment shows how to get a pointer to the ``sipAPIDef``
+data structure::
+
+    #include <sip.h>
+
+    const sipAPIDef *get_sip_api()
+    {
+        PyObject *sip_module;
+        PyObject *sip_module_dict;
+        PyObject *c_api;
+
+        /* Import the SIP module. */
+        sip_module = PyImport_ImportModule("sip");
+
+        if (sip_module == NULL)
+            return NULL;
+
+        /* Get the module's dictionary. */
+        sip_module_dict = PyModule_GetDict(sip_module);
+
+        /* Get the "_C_API" attribute. */
+        c_api = PyDict_GetItemString(sip_module_dict, "_C_API");
+
+        if (c_api == NULL)
+            return NULL;
+
+        /* Sanity check that it is the right type. */
+        if (!PyCObject_Check(c_api))
+            return NULL;
+
+        /* Get the actual pointer from the object. */
+        return (const sipAPIDef *)PyCObject_AsVoidPtr(c_api);
+    }
diff --git a/sphinx/incompatibilities.rst b/sphinx/incompatibilities.rst
new file mode 100644
index 0000000..a006e4f
--- /dev/null
+++ b/sphinx/incompatibilities.rst
@@ -0,0 +1,198 @@
+Potential Incompatibilities with Earlier Versions
+=================================================
+
+This section describes incompatibilities introduced by particular versions of
+SIP.  Normally these are the removal of previously deprecated features.
+
+
+SIP v4.10.1
+-----------
+
+Newly Deprecated Features
+*************************
+
+The following parts of the :ref:`C API <ref-c-api>` are now deprecated (but
+still supported).
+
+- The ``D`` format character of :cfunc:`sipParseResult()`.
+
+
+SIP v4.8
+--------
+
+__truediv__
+***********
+
+Prior to this version the :meth:`__div__` special method implicitly defined the
+:meth:`__truediv__` special method.  From this version the :meth:`__truediv__`
+special method must be explicitly defined.
+
+
+sipWrapper user Member
+**********************
+
+Prior to this version the :ctype:`sipWrapper` structure had a member called
+:ctype:`user` which is available for handwritten code to use.  From this
+version :ctype:`user` is a member of the :ctype:`sipSimpleWrapper` structure.
+
+:ctype:`sipWrapper` pointers can be safely cast to :ctype:`sipSimpleWrapper`
+pointers, so if your code does something like::
+
+    ((sipWrapper *)obj)->user = an_object_reference;
+
+then you just need to change it to::
+
+    ((sipSimpleWrapper *)obj)->user = an_object_reference;
+
+
+Removal of Previously Deprecated Features
+*****************************************
+
+The following parts of the :ref:`C API <ref-c-api>` have been removed.
+
+- The ``a``, ``A``, ``M``, ``N``, ``O``, ``P`` and ``T`` format characters
+  from :cfunc:`sipBuildResult()` and :cfunc:`sipCallMethod()`.
+
+- The ``a``, ``A``, ``L`` and ``M`` format characters from
+  :cfunc:`sipParseResult()`.
+
+- :cfunc:`sipConvertToCpp()`
+
+- :cfunc:`sipIsSubClassInstance()`
+
+- :cfunc:`sipTransfer()`
+
+- The :func:`transfer` function of the :mod:`sip` module.
+
+- The old-style generated type convertors.
+
+In addition the :option:`-a` command line option to :file:`configure.py` has
+been removed.
+
+
+Removal of PyQt-specific Features
+*********************************
+
+The following PyQt-specific support functions have been removed.
+
+- :cfunc:`sipConnectRx()`
+
+- :cfunc:`sipDisconnectRx()`
+
+- :cfunc:`sipEmitSlot()`
+
+- :cfunc:`sipGetSender()`
+
+
+Newly Deprecated Features
+*************************
+
+The following parts of the :ref:`C API <ref-c-api>` are now deprecated (but
+still supported).
+
+- The :ref:`ref-type-objects`.
+
+- The :ref:`ref-enum-type-objects`.
+
+- :cfunc:`sipConvertFromInstance()`
+
+- :cfunc:`sipConvertFromMappedType()`
+
+- :cfunc:`sipConvertFromNamedEnum()`
+
+- :cfunc:`sipConvertFromNewInstance()`
+
+- :cfunc:`sipCanConvertToInstance()`
+
+- :cfunc:`sipCanConvertToMappedType()`
+
+- :cfunc:`sipConvertToInstance()`
+
+- :cfunc:`sipConvertToMappedType()`
+
+- :cfunc:`sipForceConvertToInstance()`
+
+- :cfunc:`sipForceConvertToMappedType()`
+
+- :cfunc:`sipClassName()`
+
+- :cfunc:`sipFindClass()`
+
+- :cfunc:`sipFindNamedEnum()`
+
+- :cfunc:`sipFindMappedType()`
+
+- :cfunc:`sipGetWrapper()`
+
+- :cfunc:`sipReleaseInstance()`
+
+- :cfunc:`sipReleaseMappedType()`
+
+- :cfunc:`sipWrapper_Check()`
+
+- The ``B``, ``C`` and ``E`` format characters of :cfunc:`sipBuildResult()` and
+  :cfunc:`sipCallMethod()`.
+
+- The ``s``, ``C`` and ``E`` format characters of :cfunc:`sipParseResult()`.
+
+
+SIP v4.7.8
+----------
+
+Automatic int to Enum Conversions
+*********************************
+
+This version allows a Python ``int`` object to be passed whenever an enum is
+expected.  This can mean that two signatures that were different with prior
+versions are now the same as far as Python is concerned.
+
+The :aanno:`Constrained` argument annotation can now be applied to an enum
+argument to revert to the earlier behaviour.
+
+
+SIP v4.7.3
+----------
+
+Complementary Comparison Operators
+**********************************
+
+Prior to this version SIP did not automatically generate missing complementary
+comparison operators.  Typically this was worked around by adding them
+explicitly to the .sip files, even though they weren't implemented in C++ and
+relied on the C++ compiler calling the complementary operator that was
+implemented.
+
+A necessary change to the code generator meant that this not longer worked and
+so SIP was changed to automatically generate any missing complementary
+operators.  If you have added such operators explicitly then you should remove
+them or make them dependent on the particular version of SIP.
+
+
+SIP v4.4
+--------
+
+%ConvertFromTypeCode and %ConvertToTypeCode
+*******************************************
+
+Handwritten :directive:`%ConvertFromTypeCode` and
+:directive:`%ConvertToTypeCode` now have the responsibility for implementing
+the :aanno:`Transfer` and :aanno:`TransferBack` annotations.
+
+
+SIP_BUILD
+*********
+
+The :cmacro:`SIP_BUILD` C preprocessor symbol has been removed.
+
+
+Newly Deprecated Features
+*************************
+
+The following parts of the :ref:`C API <ref-c-api>` are now deprecated (but
+still supported).
+
+- The old-style generated type convertors.
+
+- :cfunc:`sipConvertToCpp()`
+
+- :cfunc:`sipIsSubClassInstance()`
diff --git a/sphinx/index.rst b/sphinx/index.rst
new file mode 100644
index 0000000..ac9289c
--- /dev/null
+++ b/sphinx/index.rst
@@ -0,0 +1,20 @@
+SIP Reference Guide
+===================
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    incompatibilities
+    installation
+    using
+    command_line
+    specification_files
+    directives
+    annotations
+    c_api
+    embedding
+    python_api
+    build_system
+    distutils
+    builtin
diff --git a/sphinx/installation.rst b/sphinx/installation.rst
new file mode 100644
index 0000000..3f9f823
--- /dev/null
+++ b/sphinx/installation.rst
@@ -0,0 +1,169 @@
+Installation
+============
+
+Downloading
+-----------
+
+You can get the latest release of the SIP source code from
+http://www.riverbankcomputing.com/software/sip/download.
+
+SIP is also included with all of the major Linux distributions.  However, it
+may be a version or two out of date.
+
+
+Configuring
+-----------
+
+After unpacking the source package (either a ``.tar.gz`` or a ``.zip`` file
+depending on your platform) you should then check for any ``README`` files
+that relate to your platform.
+
+Next you need to configure SIP by executing the ``configure.py`` script.  For
+example::
+
+    python configure.py
+
+This assumes that the Python interpreter is on your path.  Something like the
+following may be appropriate on Windows::
+
+    c:\python26\python configure.py
+
+If you have multiple versions of Python installed then make sure you use the
+interpreter for which you wish SIP to generate bindings for.
+
+The full set of command line options is:
+
+.. program:: configure.py
+
+.. cmdoption:: --version
+
+    Display the SIP version number.
+
+.. cmdoption:: -h, --help
+
+    Display a help message.
+
+.. cmdoption:: --arch <ARCH>
+
+    Binaries for the MacOS/X architecture ``<ARCH>`` will be built.  This
+    option should be given once for each architecture to be built.  Specifying
+    more than one architecture will cause a universal binary to be created.
+
+.. cmdoption:: -b <DIR>, --bindir <DIR>
+
+    The SIP code generator will be installed in the directory ``<DIR>``.
+
+.. cmdoption:: -d <DIR>, --destdir <DIR>
+
+    The SIP module will be installed in the directory ``<DIR>``.
+
+.. cmdoption:: -e <DIR>, --incdir <DIR>
+
+    The SIP header file will be installed in the directory ``<DIR>``.
+
+.. cmdoption:: -k, --static
+
+    The SIP module will be built as a static library.  This is useful when
+    building the SIP module as a Python builtin (see :ref:`ref-builtin`).
+
+.. cmdoption:: -n, --universal
+
+    The SIP code generator and module will be built as universal binaries
+    under MacOS/X.  If the :option:`--arch <configure.py --arch>` option has
+    not been specified then the universal binary will include the ``i386`` and
+    ``ppc`` architectures.
+
+.. cmdoption:: -p <PLATFORM>, --platform <PLATFORM>
+
+    Explicitly specify the platform/compiler to be used by the build system,
+    otherwise a platform specific default will be used.  The
+    :option:`--show-platforms <configure.py --show-platforms>` option will
+    display all the supported platform/compilers.
+
+.. cmdoption:: -s <SDK>, --sdk <SDK>
+
+    If the :option:`--universal <configure.py -n>` option was given then this
+    specifies the name of the SDK directory.  If a path is not given then it is
+    assumed to be a sub-directory of ``/Developer/SDKs``.
+
+.. cmdoption:: -u, --debug
+
+    The SIP module will be built with debugging symbols.
+
+.. cmdoption:: -v <DIR>, --sipdir <DIR>
+
+    By default ``.sip`` files will be installed in the directory ``<DIR>``.
+
+.. cmdoption:: --show-platforms
+
+    The list of all supported platform/compilers will be displayed.
+
+.. cmdoption:: --show-build-macros
+
+    The list of all available build macros will be displayed.
+
+The ``configure.py`` script takes many other options that allows the build
+system to be finely tuned.  These are of the form ``name=value`` or
+``name+=value``.  The :option:`--show-build-macros <configure.py
+--show-build-macros>` option will display each supported ``name``, although not
+all are applicable to all platforms.
+
+The ``name=value`` form means that ``value`` will replace the existing value of
+``name``.
+
+The ``name+=value`` form means that ``value`` will be appended to the existing
+value of ``name``.
+
+For example, the following will disable support for C++ exceptions (and so
+reduce the size of module binaries) when used with GCC::
+
+    python configure.py CXXFLAGS+=-fno-exceptions
+
+A pure Python module called ``sipconfig.py`` is generated by ``configure.py``.
+This defines each ``name`` and its corresponding ``value``.  Looking at it will
+give you a good idea of how the build system uses the different options.  It is
+covered in detail in :ref:`ref-build-system`.
+
+
+Configuring for MinGW
+*********************
+
+SIP, and the modules it generates, can be built with MinGW, the Windows port of
+GCC.  You must use the :option:`--platform <configure.py -p>` command line
+option to specify the correct platform.  For example::
+
+    c:\python26\python configure.py --platform win32-g++
+
+
+Configuring for the Borland C++ Compiler
+****************************************
+
+SIP, and the modules it generates, can be built with the free Borland C++
+compiler.  You must use the :option:`--platform <configure.py -p>` command line
+option to specify the correct platform.  For example::
+
+    c:\python26\python configure.py --platform win32-borland
+
+You must also make sure you have a Borland-compatible version of the Python
+library.  If you are using the standard Python distribution (built using the
+Microsoft compiler) then you must convert the format of the Python library.
+For example::
+
+    coff2omf python26.lib python26_bcpp.lib
+
+
+Building
+--------
+
+The next step is to build SIP by running your platform's ``make`` command.  For
+example::
+
+    make
+
+The final step is to install SIP by running the following command::
+
+    make install
+
+(Depending on your system you may require root or administrator privileges.)
+
+This will install the various SIP components.
diff --git a/sphinx/introduction.rst b/sphinx/introduction.rst
new file mode 100644
index 0000000..8515243
--- /dev/null
+++ b/sphinx/introduction.rst
@@ -0,0 +1,169 @@
+Introduction
+============
+
+This is the reference guide for SIP 4.10.5.  SIP is a tool for
+automatically generating `Python <http://www.python.org>`__ bindings for C and
+C++ libraries.  SIP was originally developed in 1998 for
+`PyQt <http://www.riverbankcomputing.com/software/pyqt>`__ - the Python
+bindings for the Qt GUI toolkit - but is suitable for generating bindings for
+any C or C++ library.
+
+This version of SIP generates bindings for Python v2.3 or later, including
+Python v3.
+
+There are many other similar tools available.  One of the original such tools
+is `SWIG <http://www.swig.org>`__ and, in fact, SIP is so called because it
+started out as a small SWIG.  Unlike SWIG, SIP is specifically designed for
+bringing together Python and C/C++ and goes to great lengths to make the
+integration as tight as possible.
+
+The homepage for SIP is http://www.riverbankcomputing.com/software/sip.  Here
+you will always find the latest stable version and the latest version of this
+documentation.
+
+SIP can also be downloaded from the
+`Mercurial <http://mercurial.selenic.com/>`__ repository at
+http://www.riverbankcomputing.com/hg/sip.
+
+
+License
+-------
+
+SIP is licensed under similar terms as Python itself.  SIP is also licensed
+under the GPL (both v2 and v3).  It is your choice as to which license you
+use.  If you choose the GPL then any bindings you create must be distributed
+under the terms of the GPL.
+
+
+Features
+--------
+
+SIP, and the bindings it produces, have the following features:
+
+- bindings are fast to load and minimise memory consumption especially when
+  only a small sub-set of a large library is being used
+
+- automatic conversion between standard Python and C/C++ data types
+
+- overloading of functions and methods with different argument signatures
+
+- support for Python's keyword argument syntax
+
+- support for both explicitly specified and automatically generated docstrings
+
+- access to a C++ class's protected methods
+
+- the ability to define a Python class that is a sub-class of a C++ class,
+  including abstract C++ classes
+
+- Python sub-classes can implement the :meth:`__dtor__` method which will be
+  called from the C++ class's virtual destructor
+
+- support for ordinary C++ functions, class methods, static class methods,
+  virtual class methods and abstract class methods
+
+- the ability to re-implement C++ virtual and abstract methods in Python
+
+- support for global and class variables
+
+- support for global and class operators
+
+- support for C++ namespaces
+
+- support for C++ templates
+
+- support for C++ exceptions and wrapping them as Python exceptions
+
+- the automatic generation of complementary rich comparison slots
+
+- support for deprecation warnings
+
+- the ability to define mappings between C++ classes and similar Python data
+  types that are automatically invoked
+
+- the ability to automatically exploit any available run time type information
+  to ensure that the class of a Python instance object matches the class of the
+  corresponding C++ instance
+
+- the ability to change the type and meta-type of the Python object used to
+  wrap a C/C++ data type
+
+- full support of the Python global interpreter lock, including the ability to
+  specify that a C++ function of method may block, therefore allowing the lock
+  to be released and other Python threads to run
+
+- support for consolidated modules where the generated wrapper code for a
+  number of related modules may be included in a single, possibly private,
+  module
+
+- support for the concept of ownership of a C++ instance (i.e. what part of the
+  code is responsible for calling the instance's destructor) and how the
+  ownership may change during the execution of an application
+
+- the ability to generate bindings for a C++ class library that itself is built
+  on another C++ class library which also has had bindings generated so that
+  the different bindings integrate and share code properly
+
+- a sophisticated versioning system that allows the full lifetime of a C++
+  class library, including any platform specific or optional features, to be
+  described in a single set of specification files 
+
+- the ability to include documentation in the specification files which can be
+  extracted and subsequently processed by external tools
+
+- the ability to include copyright notices and licensing information in the
+  specification files that is automatically included in all generated source
+  code
+
+- a build system, written in Python, that you can extend to configure, compile
+  and install your own bindings without worrying about platform specific issues
+
+- support for building your extensions using distutils
+
+- SIP, and the bindings it produces, runs under UNIX, Linux, Windows and
+  MacOS/X
+
+
+SIP Components
+--------------
+
+SIP comprises a number of different components.
+
+- The SIP code generator (:program:`sip`).  This processes :file:`.sip`
+  specification files and generates C or C++ bindings.  It is covered in detail
+  in :ref:`ref-using`.
+
+- The SIP header file (:file:`sip.h`).  This contains definitions and data
+  structures needed by the generated C and C++ code.
+
+- The SIP module (:file:`sip.so` or :file:`sip.pyd`).  This is a Python
+  extension module that is imported automatically by SIP generated bindings and
+  provides them with some common utility functions.  See also
+  :ref:`ref-python-api`.
+
+- The SIP build system (:file:`sipconfig.py`).  This is a pure Python module
+  that is created when SIP is configured and encapsulates all the necessary
+  information about your system including relevant directory names, compiler
+  and linker flags, and version numbers.  It also includes several Python
+  classes and functions which help you write configuration scripts for your own
+  bindings.  It is covered in detail in :ref:`ref-build-system`.
+
+- The SIP distutils extension (:file:`sipdistutils.py`).  This is a distutils
+  extension that can be used to build your extension modules using distutils
+  and is an alternative to writing configuration scripts with the SIP build
+  system.  This can be as simple as adding your .sip files to the list of files
+  needed to build the extension module.  It is covered in detail in
+  :ref:`ref-distutils`.
+
+
+Qt Support
+----------
+
+SIP has specific support for the creation of bindings based on Nokia's Qt
+toolkit.
+
+The SIP code generator understands the signal/slot type safe callback mechanism
+that Qt uses to connect objects together.  This allows applications to define
+new Python signals, and allows any Python callable object to be used as a slot.
+
+SIP itself does not require Qt to be installed.
diff --git a/sphinx/python_api.rst b/sphinx/python_api.rst
new file mode 100644
index 0000000..fa90411
--- /dev/null
+++ b/sphinx/python_api.rst
@@ -0,0 +1,282 @@
+.. _ref-python-api:
+
+Python API for Applications
+===========================
+
+.. module:: sip
+
+The main purpose of the :mod:`sip` module is to provide functionality common to
+all SIP generated bindings.  It is loaded automatically and most of the time
+you will completely ignore it.  However, it does expose some functionality that
+can be used by applications.
+
+
+.. function:: cast(obj, type) -> object
+
+    This does the Python equivalent of casting a C++ instance to one of its
+    sub or super-class types.
+
+    :param obj:
+        the Python object.
+    :param type:
+        the type.
+    :return:
+        a new Python object is that wraps the same C++ instance as *obj*, but
+        has the type *type*.
+
+
+.. function:: delete(obj)
+
+    For C++ instances this calls the C++ destructor.  For C structures it
+    returns the structure's memory to the heap.
+
+    :param obj:
+        the Python object.
+
+
+.. function:: dump(obj)
+
+    This displays various bits of useful information about the internal state
+    of the Python object that wraps a C++ instance or C structure.
+
+    :param obj:
+        the Python object.
+
+
+.. function:: getapi(name) -> version
+
+    .. versionadded:: 4.9
+
+    This returns the version number that has been set for an API.  The version
+    number is either set explicitly by a call to :func:`sip.setapi` or
+    implicitly by importing the module that defines it.
+
+    :param name:
+        the name of the API.
+    :return:
+        The version number that has been set for the API.  An exception will
+        be raised if the API is unknown.
+
+
+.. function:: isdeleted(obj) -> bool
+
+    This checks if the C++ instance or C structure has been deleted and
+    returned to the heap.
+
+    :param obj:
+        the Python object.
+    :return:
+        ``True`` if the C/C++ instance has been deleted.
+
+
+.. function:: ispyowned(obj) -> bool
+
+    This checks if the C++ instance or C structure is owned by Python.
+
+    :param obj:
+        the Python object.
+    :return:
+        ``True`` if the C/C++ instance is owned by Python.
+
+
+.. function:: setapi(name, version)
+
+    .. versionadded:: 4.9
+
+    This sets the version number of an API.  An exception is raised if a
+    different version number has already been set, either explicitly by a
+    previous call, or implicitly by importing the module that defines it.
+
+    :param name:
+        the name of the API.
+    :param version:
+        The version number to set for the API.  Version numbers must be
+        greater than or equal to 1.
+
+
+.. function:: setdeleted(obj)
+
+    This marks the C++ instance or C structure as having been deleted and
+    returned to the heap so that future references to it raise an exception
+    rather than cause a program crash.  Normally SIP handles such things
+    automatically, but there may be circumstances where this isn't possible.
+
+    :param obj:
+        the Python object.
+
+
+.. function:: settracemask(mask)
+
+    If the bindings have been created with SIP's :option:`-r <sip -r>` command
+    line option then the generated code will include debugging statements that
+    trace the execution of the code.  (It is particularly useful when trying to
+    understand the operation of a C++ library's virtual function calls.)
+
+    :param mask:
+        the mask that determines which debugging statements are enabled.
+
+    Debugging statements are generated at the following points:
+
+    - in a C++ virtual function (*mask* is ``0x0001``)
+    - in a C++ constructor (*mask* is ``0x0002``)
+    - in a C++ destructor (*mask* is ``0x0004``)
+    - in a Python type's __init__ method (*mask* is ``0x0008``)
+    - in a Python type's __del__ method (*mask* is ``0x0010``)
+    - in a Python type's ordinary method (*mask* is ``0x0020``).
+
+    By default the trace mask is zero and all debugging statements are
+    disabled.
+
+
+.. data:: SIP_VERSION
+
+    This is a Python integer object that represents the SIP version number as
+    a 3 part hexadecimal number (e.g. v4.0.0 is represented as ``0x040000``).
+    It was first implemented in SIP v4.2.
+
+
+.. data:: SIP_VERSION_STR
+
+    This is a Python string object that defines the SIP version number as
+    represented as a string.  For development snapshots it will start with
+    ``snapshot-``.  It was first implemented in SIP v4.3.
+
+
+.. function:: transferback(obj)
+
+    This function is a wrapper around :cfunc:`sipTransferBack()`.
+
+
+.. function:: transferto(obj, owner)
+
+    This function is a wrapper around :cfunc:`sipTransferTo()`.
+
+
+.. function:: unwrapinstance(obj) -> integer
+
+    This returns the address, as an integer, of a wrapped C/C++ structure or
+    class instance.
+
+    :param obj:
+        the Python object.
+    :return:
+        an integer that is the address of the C/C++ instance.
+
+
+.. class:: voidptr
+
+    This is the type object for the type SIP uses to represent a C/C++
+    ``void *``.  It may have a size associated with the address in which case
+    the Python buffer protocol is supported.  This means that the memory can
+    be treated as a mutable array of bytes when wrapped with the ``buffer()``
+    builtin.  The type has the following methods.
+
+    .. method:: __init__(address[, size=-1[, writeable=True]])
+
+        :param address:
+            the address, either another :class:`sip.voidptr`, ``None``, a
+            Python Capsule, a Python CObject, or an integer.
+        :param size:
+            the optional associated size of the block of memory and is negative
+            if the size is not known.
+        :param writeable:
+            set if the memory is writeable.  If it is not specified, and
+            *address* is a :class:`sip.voidptr` instance then its value will be
+            used.
+
+    .. method:: __int__() -> integer
+
+        This returns the address as an integer.
+
+        :return:
+            the integer address.
+
+    .. method:: __hex__() -> string
+
+        This returns the address as a hexadecimal string.
+
+        :return:
+            the hexadecimal string address.
+
+    .. method:: ascapsule() -> capsule
+
+        .. versionadded:: 4.10
+
+        This returns the address as an unnamed Python Capsule.  This requires
+        Python v3.1 or later or Python v2.7 or later.
+
+        :return:
+            the Capsule.
+
+    .. method:: ascobject() -> cObject
+
+        This returns the address as a Python CObject.  This is deprecated with
+        Python v3.1 or later.
+
+        :return:
+            the CObject.
+
+    .. method:: asstring([size=-1]) -> string/bytes
+
+        This returns a copy of the block of memory as a Python v2 string object
+        or a Python v3 bytes object.
+        
+        :param size:
+            the number of bytes to copy.  If it is negative then the size
+            associated with the address is used.  If there is no associated
+            size then an exception is raised.
+        :return:
+            the string or bytes object.
+
+    .. method:: getsize() -> integer
+
+        This returns the size associated with the address.
+        
+        :return:
+            the associated size which will be negative if there is none.
+
+    .. method:: setsize(size)
+
+        This sets the size associated with the address.
+        
+        :param size:
+            the size to associate.  If it is negative then no size is
+            associated.
+
+    .. method:: getwriteable() -> bool
+
+        This returns the writeable state of the memory.
+
+        :return:
+            ``True`` if the memory is writeable.
+
+    .. method:: setwriteable(writeable)
+
+        This sets the writeable state of the memory.
+
+        :param writeable:
+            the writeable state to set.
+
+
+.. function:: wrapinstance(addr, type) -> object
+
+    This wraps a C structure or C++ class instance in a Python object.  If the
+    instance has already been wrapped then a new reference to the existing
+    object is returned.
+    
+    :param addr:
+        the address of the instance as a number.
+    :param type:
+        the Python type of the instance.
+    :return:
+        the Python object that wraps the instance.
+
+
+.. class:: wrapper
+
+    This is the type object of the base type of all instances wrapped by SIP.
+
+
+.. class:: wrappertype
+
+    This is the type object of the metatype of the :class:`sip.wrapper` type.
diff --git a/sphinx/specification_files.rst b/sphinx/specification_files.rst
new file mode 100644
index 0000000..6ba3aba
--- /dev/null
+++ b/sphinx/specification_files.rst
@@ -0,0 +1,499 @@
+SIP Specification Files
+=======================
+
+A SIP specification consists of some C/C++ type and function declarations and
+some directives.  The declarations may contain annotations which provide SIP
+with additional information that cannot be expressed in C/C++.  SIP does not
+include a full C/C++ parser.
+
+It is important to understand that a SIP specification describes the Python
+API, i.e. the API available to the Python programmer when they ``import`` the
+generated module.  It does not have to accurately represent the underlying
+C/C++ library.  There is nothing wrong with omitting functions that make
+little sense in a Python context, or adding functions implemented with
+handwritten code that have no C/C++ equivalent.  It is even possible (and
+sometimes necessary) to specify a different super-class hierarchy for a C++
+class.  All that matters is that the generated code compiles properly.
+
+In most cases the Python API matches the C/C++ API.  In some cases handwritten
+code (see :directive:`%MethodCode`) is used to map from one to the other
+without SIP having to know the details itself.  However, there are a few cases
+where SIP generates a thin wrapper around a C++ method or constructor (see
+:ref:`ref-derived-classes`) and needs to know the exact C++ signature.  To deal
+with these cases SIP allows two signatures to be specified.  For example::
+
+    class Klass
+    {
+    public:
+        // The Python signature is a tuple, but the underlying C++ signature
+        // is a 2 element array.
+        Klass(SIP_PYTUPLE) [(int *)];
+    %MethodCode
+            int iarr[2];
+
+            if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1]))
+            {
+                // Note that we use the SIP generated derived class
+                // constructor.
+                Py_BEGIN_ALLOW_THREADS
+                sipCpp = new sipKlass(iarr);
+                Py_END_ALLOW_THREADS
+            }
+    %End
+    };
+
+
+Syntax Definition
+-----------------
+
+The following is a semi-formal description of the syntax of a specification
+file.
+
+.. parsed-literal::
+
+    *specification* ::= {*module-statement*}
+
+    *module-statement* ::= [*module-directive* | *statement*]
+
+    *module-directive* ::= [
+            :directive:`%API` |
+            :directive:`%CModule` |
+            :directive:`%CompositeModule` |
+            :directive:`%ConsolidatedModule` |
+            :directive:`%Copying` |
+            :directive:`%DefaultEncoding` |
+            :directive:`%DefaultMetatype` |
+            :directive:`%DefaultSupertype` |
+            :directive:`%Doc` |
+            :directive:`%ExportedDoc` |
+            :directive:`%ExportedHeaderCode` |
+            :directive:`%Feature` |
+            :directive:`%Import` |
+            :directive:`%Include` |
+            :directive:`%InitialisationCode` |
+            :directive:`%License` |
+            :directive:`%MappedType` |
+            :directive:`%Module` |
+            :directive:`%ModuleCode` |
+            :directive:`%ModuleHeaderCode` |
+            :directive:`%OptionalInclude` |
+            :directive:`%Platforms` |
+            :directive:`%PreInitialisationCode` |
+            :directive:`%PostInitialisationCode` |
+            :directive:`%Timeline` |
+            :directive:`%UnitCode` |
+            *mapped-type-template*]
+
+    *statement* :: [*class-statement* | *function* | *variable*]
+
+    *class-statement* :: [
+            :directive:`%If` |
+            *class* |
+            *class-template* |
+            *enum* |
+            *namespace* |
+            *opaque-class* |
+            *operator* |
+            *struct* |
+            *typedef* |
+            *exception*]
+
+    *class* ::= **class** *name* [**:** *super-classes*] [*class-annotations*]
+            **{** {*class-line*} **};**
+
+    *super-classes* ::= *name* [**,** *super-classes*]
+
+    *class-line* ::= [
+            *class-statement* |
+            :directive:`%BIGetBufferCode` |
+            :directive:`%BIGetReadBufferCode` |
+            :directive:`%BIGetWriteBufferCode` |
+            :directive:`%BIGetSegCountCode` |
+            :directive:`%BIGetCharBufferCode` |
+            :directive:`%BIReleaseBufferCode` |
+            :directive:`%ConvertToSubClassCode` |
+            :directive:`%ConvertToTypeCode` |
+            :directive:`%Docstring` |
+            :directive:`%GCClearCode` |
+            :directive:`%GCTraverseCode` |
+            :directive:`%PickleCode` |
+            :directive:`%TypeCode` |
+            :directive:`%TypeHeaderCode` |
+            *constructor* |
+            *destructor* |
+            *method* |
+            *static-method* |
+            *virtual-method* |
+            *special-method* |
+            *operator* |
+            *virtual-operator* |
+            *class-variable* |
+            **public:** |
+            **public Q_SLOTS:** |
+            **public slots:** |
+            **protected:** |
+            **protected Q_SLOTS:** |
+            **protected slots:** |
+            **private:** |
+            **private Q_SLOTS:** |
+            **private slots:** |
+            **Q_SIGNALS:** |
+            **signals:**]
+
+    *constructor* ::= [**explicit**] *name* **(** [*argument-list*] **)**
+            [*exceptions*] [*function-annotations*]
+            [*c++-constructor-signature*] **;** [:directive:`%Docstring`]
+            [:directive:`%MethodCode`]
+
+    *c++-constructor-signature* ::= **[(** [*argument-list*] **)]**
+
+    *destructor* ::= [**virtual**] **~** *name* **()** [*exceptions*] [**= 0**]
+            [*function-annotations*] **;** [:directive:`%MethodCode`]
+            [:directive:`%VirtualCatcherCode`]
+
+    *method* ::= [**Q_SIGNAL**] [**Q_SLOT**] *type* *name* **(**
+            [*argument-list*] **)** [**const**] [*exceptions*] [**= 0**]
+            [*function-annotations*] [*c++-signature*] **;**
+            [:directive:`%Docstring`] [:directive:`%MethodCode`]
+
+    *c++-signature* ::= **[** *type* **(** [*argument-list*] **)]**
+
+    *static-method* ::= **static** *function*
+
+    *virtual-method* ::= [**Q_SIGNAL**] [**Q_SLOT**] **virtual** *type* *name*
+            **(** [*argument-list*] **)** [**const**] [*exceptions*] [**= 0**]
+            [*function-annotations*] [*c++-signature*] **;**
+            [:directive:`%MethodCode`] [:directive:`%VirtualCatcherCode`]
+
+    *special-method* ::= *type* *special-method-name*
+            **(** [*argument-list*] **)** [*function-annotations*] **;**
+            [:directive:`%MethodCode`]
+
+    *special-method-name* ::= [**__abs__** | **__add__** | **__and__** |
+            **__bool__** | **__call__** | **__cmp__** | **__contains__** |
+            **__delitem__** | **__div__** | **__eq__** | **__float__** |
+            **__floordiv__** | **__ge__** | **__getitem__** | **__gt__** |
+            **__hash__** | **__iadd__** | **__iand__** | **__idiv__** |
+            **__ifloordiv__** | **__ilshift__** | **__imod__** | **__imul__** |
+            **__index__** | **__int__** | **__invert__** | **__ior__** |
+            **__irshift__** | **__isub__** | **__iter__** | **__itruediv__** |
+            **__ixor__** | **__le__** | **__len__** | **__long__** |
+            **__lshift__** | **__lt__** | **__mod__** | **__mul__** |
+            **__ne__** | **__neg__** | **__next__** | **__nonzero__** |
+            **__or__** | **__pos__** | **__repr__** | **__rshift__** |
+            **__setitem__** | **__str__** | **__sub__** | **__truediv__** |
+            **__xor__**]
+
+    *operator* ::= *operator-type*
+            **(** [*argument-list*] **)** [**const**] [*exceptions*]
+            [*function-annotations*] **;** [:directive:`%MethodCode`]
+
+    *virtual-operator* ::= **virtual** *operator-type*
+            **(** [*argument-list*] **)** [**const**] [*exceptions*] [**= 0**]
+            [*function-annotations*] **;** [:directive:`%MethodCode`]
+            [:directive:`%VirtualCatcherCode`]
+
+    *operatator-type* ::= [ *operator-function* | *operator-cast* ]
+
+    *operator-function* ::= *type* **operator** *operator-name*
+
+    *operator-cast* ::= **operator** *type*
+
+    *operator-name* ::= [**+** | **-** | ***** | **/** | **%** | **&** |
+            **|** | **^** | **<<** | **>>** | **+=** | **-=** | ***=** |
+            **/=** | **%=** | **&=** | **|=** | **^=** | **<<=** | **>>=** |
+            **~** | **()** | **[]** | **<** | **<=** | **==** | **!=** |
+            **>** | **>>=** | **=**]
+
+    *class-variable* ::= [**static**] *variable*
+
+    *class-template* :: = **template** **<** *type-list* **>** *class*
+
+    *mapped-type-template* :: = **template** **<** *type-list* **>**
+            :directive:`%MappedType`
+
+    *enum* ::= **enum** [*name*] [*enum-annotations*] **{** {*enum-line*} **};**
+
+    *enum-line* ::= [:directive:`%If` | *name* [*enum-annotations*] **,**
+
+    *function* ::= *type* *name* **(** [*argument-list*] **)** [*exceptions*]
+            [*function-annotations*] **;** [:directive:`%Docstring`]
+            [:directive:`%MethodCode`]
+
+    *namespace* ::= **namespace** *name* **{** {*namespace-line*} **};**
+
+    *namespace-line* ::= [:directive:`%TypeHeaderCode` | *statement*]
+
+    *opaque-class* ::= **class** *scoped-name* **;**
+
+    *struct* ::= **struct** *name* **{** {*class-line*} **};**
+
+    *typedef* ::= **typedef** [*typed-name* | *function-pointer*]
+            *typedef-annotations* **;**
+
+    *variable*::= *typed-name* [*variable-annotations*] **;**
+            [:directive:`%AccessCode`] [:directive:`%GetCode`]
+            [:directive:`%SetCode`]
+
+    *exception* ::= :directive:`%Exception` *exception-name* [*exception-base*]
+            **{** [:directive:`%TypeHeaderCode`] :directive:`%RaiseCode` **};**
+
+    *exception-name* ::= *scoped-name*
+
+    *exception-base* ::= **(** [*exception-name* | *python-exception*] **)**
+
+    *python-exception* ::= [**SIP_Exception** | **SIP_StopIteration** |
+            **SIP_StandardError** | **SIP_ArithmeticError** |
+            **SIP_LookupError** | **SIP_AssertionError** |
+            **SIP_AttributeError** | **SIP_EOFError** |
+            **SIP_FloatingPointError** | **SIP_EnvironmentError** |
+            **SIP_IOError** | **SIP_OSError** | **SIP_ImportError** |
+            **SIP_IndexError** | **SIP_KeyError** | **SIP_KeyboardInterrupt** |
+            **SIP_MemoryError** | **SIP_NameError** | **SIP_OverflowError** |
+            **SIP_RuntimeError** | **SIP_NotImplementedError** |
+            **SIP_SyntaxError** | **SIP_IndentationError** | **SIP_TabError** |
+            **SIP_ReferenceError** | **SIP_SystemError** | **SIP_SystemExit** |
+            **SIP_TypeError** | **SIP_UnboundLocalError** |
+            **SIP_UnicodeError** | **SIP_UnicodeEncodeError** |
+            **SIP_UnicodeDecodeError** | **SIP_UnicodeTranslateError** |
+            **SIP_ValueError** | **SIP_ZeroDivisionError** |
+            **SIP_WindowsError** | **SIP_VMSError**]
+
+    *exceptions* ::= **throw (** [*exception-list*] **)**
+
+    *exception-list* ::= *scoped-name* [**,** *exception-list*]
+
+    *argument-list* ::= *argument* [**,** *argument-list*] [**,** **...**]
+
+    *argument* ::= [
+            *type* [*name*] [*argument-annotations*] [*default-value*] |
+            :stype:`SIP_ANYSLOT` [*default-value*] |
+            :stype:`SIP_QOBJECT` |
+            :stype:`SIP_RXOBJ_CON` |
+            :stype:`SIP_RXOBJ_DIS` |
+            :stype:`SIP_SIGNAL` [*default-value*] |
+            :stype:`SIP_SLOT` [*default-value*] |
+            :stype:`SIP_SLOT_CON` |
+            :stype:`SIP_SLOT_DIS`]
+
+    *default-value* ::= **=** *expression*
+
+    *expression* ::= [*value* | *value* *binary-operator* *expression*]
+
+    *value* ::= [*unary-operator*] *simple-value*
+
+    *simple-value* ::= [*scoped-name* | *function-call* | *real-value* |
+            *integer-value* | *boolean-value* | *string-value* |
+            *character-value*]
+
+    *typed-name*::= *type* *name*
+
+    *function-pointer*::= *type* **(*** *name* **)(** [*type-list*] **)**
+
+    *type-list* ::= *type* [**,** *type-list*]
+
+    *function-call* ::= *scoped-name* **(** [*value-list*] **)**
+
+    *value-list* ::= *value* [**,** *value-list*]
+
+    *real-value* ::= a floating point number
+
+    *integer-value* ::= a number
+
+    *boolean-value* ::= [**true** | **false**]
+
+    *string-value* ::= **"** {*character*} **"**
+
+    *character-value* ::= **'** *character* **'**
+
+    *unary-operator* ::= [**!** | **~** | **-** | **+**]
+
+    *binary-operator* ::= [**-** | **+** | ***** | **/** | **&** | **|**]
+
+    *argument-annotations* ::= see :ref:`ref-arg-annos`
+
+    *class-annotations* ::= see :ref:`ref-class-annos`
+
+    *enum-annotations* ::= see :ref:`ref-enum-annos`
+
+    *function-annotations* ::= see :ref:`ref-function-annos`
+
+    *typedef-annotations* ::= see :ref:`ref-typedef-annos`
+
+    *variable-annotations* ::= see :ref:`ref-variable-annos`
+
+    *type* ::= [**const**] *base-type* {*****} [**&**]
+
+    *type-list* ::= *type* [**,** *type-list*]
+
+    *base-type* ::= [*scoped-name* | *template* | **struct** *scoped-name* |
+            **char** | **signed char** | **unsigned char** | **wchar_t** |
+            **int** | **unsigned** | **unsigned int** |
+            **short** | **unsigned short** |
+            **long** | **unsigned long** |
+            **long long** | **unsigned long long** |
+            **float** | **double** |
+            **bool** |
+            **void** |
+            :stype:`SIP_PYCALLABLE` |
+            :stype:`SIP_PYDICT` |
+            :stype:`SIP_PYLIST` |
+            :stype:`SIP_PYOBJECT` |
+            :stype:`SIP_PYSLICE` |
+            :stype:`SIP_PYTUPLE` |
+            :stype:`SIP_PYTYPE`]
+
+    *scoped-name* ::= *name* [**::** *scoped-name*]
+
+    *template* ::= *scoped-name* **<** *type-list* **>**
+
+    *dotted-name* ::= *name* [**.** *dotted-name*]
+
+    *name* ::= _A-Za-z {_A-Za-z0-9}
+
+Here is a short list of differences between C++ and the subset supported by
+SIP that might trip you up.
+
+    - SIP does not support the use of ``[]`` in types.  Use pointers instead.
+
+    - A global ``operator`` can only be defined if its first argument is a
+      class or a named enum that has been wrapped in the same module.
+
+    - Variables declared outside of a class are effectively read-only.
+
+    - A class's list of super-classes doesn't not include any access specifier
+      (e.g. ``public``).
+
+
+Variable Numbers of Arguments
+-----------------------------
+
+SIP supports the use of ``...`` as the last part of a function signature.  Any
+remaining arguments are collected as a Python tuple.
+
+
+Additional SIP Types
+--------------------
+
+SIP supports a number of additional data types that can be used in Python
+signatures.
+
+
+.. sip-type:: SIP_ANYSLOT
+
+This is both a ``const char *`` and a ``PyObject *`` that is used as the type
+of the member instead of ``const char *`` in functions that implement the
+connection or disconnection of an explicitly generated signal to a slot.
+Handwritten code must be provided to interpret the conversion correctly.
+
+
+.. sip-type:: SIP_PYCALLABLE
+
+This is a ``PyObject *`` that is a Python callable object.
+
+
+.. sip-type:: SIP_PYDICT
+
+This is a ``PyObject *`` that is a Python dictionary object.
+
+
+.. sip-type:: SIP_PYLIST
+
+This is a ``PyObject *`` that is a Python list object.
+
+
+.. sip-type:: SIP_PYOBJECT
+
+This is a ``PyObject *`` of any Python type.
+
+
+.. sip-type:: SIP_PYSLICE
+
+This is a ``PyObject *`` that is a Python slice object.
+
+
+.. sip-type:: SIP_PYTUPLE
+
+This is a ``PyObject *`` that is a Python tuple object.
+
+
+.. sip-type:: SIP_PYTYPE
+
+This is a ``PyObject *`` that is a Python type object.
+
+
+.. sip-type:: SIP_QOBJECT
+
+This is a ``QObject *`` that is a C++ instance of a class derived from Qt's
+``QObject`` class.
+
+
+.. sip-type:: SIP_RXOBJ_CON
+
+This is a ``QObject *`` that is a C++ instance of a class derived from Qt's
+``QObject`` class.  It is used as the type of the receiver instead of ``const
+QObject *`` in functions that implement a connection to a slot.
+
+
+.. sip-type:: SIP_RXOBJ_DIS
+
+This is a ``QObject *`` that is a C++ instance of a class derived from Qt's
+``QObject`` class.  It is used as the type of the receiver instead of ``const
+QObject *`` in functions that implement a disconnection from a slot.
+
+
+.. sip-type:: SIP_SIGNAL
+
+This is a ``const char *`` that is used as the type of the signal instead of
+``const char *`` in functions that implement the connection or disconnection
+of an explicitly generated signal to a slot.
+
+
+.. sip-type:: SIP_SLOT
+
+This is a ``const char *`` that is used as the type of the member instead of
+``const char *`` in functions that implement the connection or disconnection
+of an explicitly generated signal to a slot.
+
+
+.. sip-type:: SIP_SLOT_CON
+
+This is a ``const char *`` that is used as the type of the member instead of
+``const char *`` in functions that implement the connection of an internally
+generated signal to a slot.  The type includes a comma separated list of types
+that is the C++ signature of of the signal.
+
+To take an example, ``QAccel::connectItem()`` connects an internally generated
+signal to a slot.  The signal is emitted when the keyboard accelerator is
+activated and it has a single integer argument that is the ID of the
+accelerator.  The C++ signature is::
+
+    bool connectItem(int id, const QObject *receiver, const char *member);
+
+The corresponding SIP specification is::
+
+    bool connectItem(int, SIP_RXOBJ_CON, SIP_SLOT_CON(int));
+
+
+.. sip-type:: SIP_SLOT_DIS
+
+This is a ``const char *`` that is used as the type of the member instead of
+``const char *`` in functions that implement the disconnection of an
+internally generated signal to a slot.  The type includes a comma separated
+list of types that is the C++ signature of of the signal.
+
+
+Classic Division and True Division
+----------------------------------
+
+SIP supports the ``__div__`` and ``__truediv__`` special methods (and the
+corresponding inplace versions) for both Python v2 and v3.
+
+For Python v2 the ``__div__`` method will be used for both classic and true
+division if a ``__truediv__`` method is not defined.
+
+For Python v3 the ``__div__`` method will be used for true division if a
+``__truediv__`` method is not defined.
+
+For all versions of Python, if both methods are defined then ``__div__``
+should be defined first.
diff --git a/sphinx/using.rst b/sphinx/using.rst
new file mode 100644
index 0000000..ff121ce
--- /dev/null
+++ b/sphinx/using.rst
@@ -0,0 +1,662 @@
+.. _ref-using:
+
+Using SIP
+=========
+
+Bindings are generated by the SIP code generator from a number of specification
+files, typically with a ``.sip`` extension.  Specification files look very
+similar to C and C++ header files, but often with additional information (in
+the form of a *directive* or an *annotation*) and code so that the bindings
+generated can be finely tuned.
+
+
+.. _ref-simple-c++-example:
+
+A Simple C++ Example
+--------------------
+
+We start with a simple example.  Let's say you have a (fictional) C++ library
+that implements a single class called ``Word``.  The class has one constructor
+that takes a ``\0`` terminated character string as its single argument.  The
+class has one method called ``reverse()`` which takes no arguments and returns
+a ``\0`` terminated character string.  The interface to the class is defined in
+a header file called ``word.h`` which might look something like this::
+
+    // Define the interface to the word library.
+
+    class Word {
+        const char *the_word;
+
+    public:
+        Word(const char *w);
+
+        char *reverse() const;
+    };
+
+The corresponding SIP specification file would then look something like this::
+
+    // Define the SIP wrapper to the word library.
+
+    %Module word 0
+
+    class Word {
+
+    %TypeHeaderCode
+    #include <word.h>
+    %End
+
+    public:
+        Word(const char *w);
+
+        char *reverse() const;
+    };
+
+Obviously a SIP specification file looks very much like a C++ (or C) header
+file, but SIP does not include a full C++ parser.  Let's look at the
+differences between the two files.
+
+    - The :directive:`%Module` directive has been added [#]_.  This is used to
+      name the Python module that is being created and to give it a
+      *generation* number.  In this example these are ``word`` and ``0``
+      respectively.  The generation number is effectively the version number of
+      the module.
+
+    - The :directive:`%TypeHeaderCode` directive has been added.  The text
+      between this and the following :directive:`%End` directive is included
+      literally in the code that SIP generates.  Normally it is used, as in
+      this case, to ``#include`` the corresponding C++ (or C) header file [#]_.
+
+    - The declaration of the private variable ``this_word`` has been removed.
+      SIP does not support access to either private or protected instance
+      variables.
+
+If we want to we can now generate the C++ code in the current directory by
+running the following command::
+
+    sip -c . word.sip
+
+However, that still leaves us with the task of compiling the generated code and
+linking it against all the necessary libraries.  It's much easier to use the
+:ref:`SIP build system <ref-build-system>` to do the whole thing.
+
+Using the SIP build system is simply a matter of writing a small Python script.
+In this simple example we will assume that the ``word`` library we are wrapping
+and it's header file are installed in standard system locations and will be
+found by the compiler and linker without having to specify any additional
+flags.  In a more realistic example your Python script may take command line
+options, or search a set of directories to deal with different configurations
+and installations.
+
+This is the simplest script (conventionally called ``configure.py``)::
+
+    import os
+    import sipconfig
+
+    # The name of the SIP build file generated by SIP and used by the build
+    # system.
+    build_file = "word.sbf"
+
+    # Get the SIP configuration information.
+    config = sipconfig.Configuration()
+
+    # Run SIP to generate the code.
+    os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "word.sip"]))
+    
+    # Create the Makefile.
+    makefile = sipconfig.SIPModuleMakefile(config, build_file)
+
+    # Add the library we are wrapping.  The name doesn't include any platform
+    # specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the
+    # ".dll" extension on Windows).
+    makefile.extra_libs = ["word"]
+
+    # Generate the Makefile itself.
+    makefile.generate()
+
+Hopefully this script is self-documenting.  The key parts are the
+``Configuration`` and ``SIPModuleMakefile`` classes.  The build system contains
+other Makefile classes, for example to build programs or to call other
+Makefiles in sub-directories.
+
+After running the script (using the Python interpreter the extension module is
+being created for) the generated C++ code and ``Makefile`` will be in the
+current directory.
+
+To compile and install the extension module, just run the following
+commands [#]_::
+
+    make
+    make install
+
+That's all there is to it.
+
+See :ref:`ref-distutils` for an example of how to build this example using
+distutils.
+
+.. [#] All SIP directives start with a ``%`` as the first non-whitespace
+       character of a line.
+.. [#] SIP includes many code directives like this.  They differ in where the
+       supplied code is placed by SIP in the generated code.
+.. [#] On Windows you might run ``nmake`` or ``mingw32-make`` instead.
+
+
+A Simple C Example
+------------------
+
+Let's now look at a very similar example of wrapping a fictional C library::
+
+    /* Define the interface to the word library. */
+
+    struct Word {
+        const char *the_word;
+    };
+
+    struct Word *create_word(const char *w);
+    char *reverse(struct Word *word);
+
+The corresponding SIP specification file would then look something like this::
+
+    /* Define the SIP wrapper to the word library. */
+
+    %CModule word 0
+
+    struct Word {
+
+    %TypeHeaderCode
+    #include <word.h>
+    %End
+
+        const char *the_word;
+    };
+
+    struct Word *create_word(const char *w) /Factory/;
+    char *reverse(struct Word *word);
+
+Again, let's look at the differences between the two files.
+
+    - The :directive:`%CModule` directive has been added.  This has the same
+      syntax as the :directive:`%Module` directive used in the previous example
+      but tells SIP that the library being wrapped is implemented in C rather
+      than C++.
+
+    - The :directive:`%TypeHeaderCode` directive has been added.
+
+    - The :fanno:`Factory` annotation has been added to the ``create_word()``
+      function.  This tells SIP that a newly created structure is being
+      returned and it is owned by Python.
+
+The ``configure.py`` build system script described in the previous example can
+be used for this example without change.
+
+
+A More Complex C++ Example
+--------------------------
+
+In this last example we will wrap a fictional C++ library that contains a class
+that is derived from a Qt class.  This will demonstrate how SIP allows a class
+hierarchy to be split across multiple Python extension modules, and will
+introduce SIP's versioning system.
+
+The library contains a single C++ class called ``Hello`` which is derived from
+Qt's ``QLabel`` class.  It behaves just like ``QLabel`` except that the text
+in the label is hard coded to be ``Hello World``.  To make the example more
+interesting we'll also say that the library only supports Qt v4.2 and later,
+and also includes a function called ``setDefault()`` that is not implemented
+in the Windows version of the library.
+
+The ``hello.h`` header file looks something like this::
+
+    // Define the interface to the hello library.
+
+    #include <qlabel.h>
+    #include <qwidget.h>
+    #include <qstring.h>
+
+    class Hello : public QLabel {
+        // This is needed by the Qt Meta-Object Compiler.
+        Q_OBJECT
+
+    public:
+        Hello(QWidget *parent = 0);
+
+    private:
+        // Prevent instances from being copied.
+        Hello(const Hello &);
+        Hello &operator=(const Hello &);
+    };
+
+    #if !defined(Q_OS_WIN)
+    void setDefault(const QString &def);
+    #endif
+
+The corresponding SIP specification file would then look something like this::
+
+    // Define the SIP wrapper to the hello library.
+
+    %Module hello 0
+
+    %Import QtGui/QtGuimod.sip
+
+    %If (Qt_4_2_0 -)
+
+    class Hello : QLabel {
+
+    %TypeHeaderCode
+    #include <hello.h>
+    %End
+
+    public:
+        Hello(QWidget *parent /TransferThis/ = 0);
+
+    private:
+        Hello(const Hello &);
+    };
+
+    %If (!WS_WIN)
+    void setDefault(const QString &def);
+    %End
+
+    %End
+
+Again we look at the differences, but we'll skip those that we've looked at in
+previous examples.
+
+    - The :directive:`%Import` directive has been added to specify that we are
+      extending the class hierarchy defined in the file ``QtGui/QtGuimod.sip``.
+      This file is part of PyQt.  The build system will take care of finding
+      the file's exact location.
+
+    - The :directive:`%If` directive has been added to specify that everything
+      [#]_ up to the matching :directive:`%End` directive only applies to Qt
+      v4.2 and later.  ``Qt_4_2_0`` is a *tag* defined in ``QtCoremod.sip``
+      [#]_ using the :directive:`%Timeline` directive.  :directive:`%Timeline`
+      is used to define a tag for each version of a library's API you are
+      wrapping allowing you to maintain all the different versions in a single
+      SIP specification.  The build system provides support to ``configure.py``
+      scripts for working out the correct tags to use according to which
+      version of the library is actually installed.
+
+    - The ``public`` keyword used in defining the super-classes has been
+      removed.  This is not supported by SIP.
+
+    - The :aanno:`TransferThis` annotation has been added to the constructor's
+      argument.  It specifies that if the argument is not 0 (i.e. the ``Hello``
+      instance being constructed has a parent) then ownership of the instance
+      is transferred from Python to C++.  It is needed because Qt maintains
+      objects (i.e. instances derived from the ``QObject`` class) in a
+      hierachy.  When an object is destroyed all of its children are also
+      automatically destroyed.  It is important, therefore, that the Python
+      garbage collector doesn't also try and destroy them.  This is covered in
+      more detail in :ref:`ref-object-ownership`.  SIP provides many other
+      annotations that can be applied to arguments, functions and classes.
+      Multiple annotations are separated by commas.  Annotations may have
+      values.
+
+    - The ``=`` operator has been removed.  This operator is not supported by
+      SIP.
+
+    - The :directive:`%If` directive has been added to specify that everything
+      up to the matching :directive:`%End` directive does not apply to Windows.
+      ``WS_WIN`` is another tag defined by PyQt, this time using the
+      :directive:`%Platforms` directive.  Tags defined by the
+      :directive:`%Platforms` directive are mutually exclusive, i.e. only one
+      may be valid at a time [#]_.
+
+One question you might have at this point is why bother to define the private
+copy constructor when it can never be called from Python?  The answer is to
+prevent the automatic generation of a public copy constructor.
+
+We now look at the ``configure.py`` script.  This is a little different to the
+script in the previous examples for two related reasons.
+
+Firstly, PyQt includes a pure Python module called ``pyqtconfig`` that extends
+the SIP build system for modules, like our example, that build on top of PyQt.
+It deals with the details of which version of Qt is being used (i.e. it
+determines what the correct tags are) and where it is installed.  This is
+called a module's configuration module.
+
+Secondly, we generate a configuration module (called ``helloconfig``) for our
+own ``hello`` module.  There is no need to do this, but if there is a chance
+that somebody else might want to extend your C++ library then it would make
+life easier for them.
+
+Now we have two scripts.  First the ``configure.py`` script::
+
+    import os
+    import sipconfig
+    from PyQt4 import pyqtconfig
+
+    # The name of the SIP build file generated by SIP and used by the build
+    # system.
+    build_file = "hello.sbf"
+
+    # Get the PyQt configuration information.
+    config = pyqtconfig.Configuration()
+
+    # Get the extra SIP flags needed by the imported PyQt modules.  Note that
+    # this normally only includes those flags (-x and -t) that relate to SIP's
+    # versioning system.
+    pyqt_sip_flags = config.pyqt_sip_flags
+
+    # Run SIP to generate the code.  Note that we tell SIP where to find the qt
+    # module's specification files using the -I flag.
+    os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "-I", config.pyqt_sip_dir, pyqt_sip_flags, "hello.sip"]))
+
+    # We are going to install the SIP specification file for this module and
+    # its configuration module.
+    installs = []
+
+    installs.append(["hello.sip", os.path.join(config.default_sip_dir, "hello")])
+
+    installs.append(["helloconfig.py", config.default_mod_dir])
+
+    # Create the Makefile.  The QtGuiModuleMakefile class provided by the
+    # pyqtconfig module takes care of all the extra preprocessor, compiler and
+    # linker flags needed by the Qt library.
+    makefile = pyqtconfig.QtGuiModuleMakefile(
+        configuration=config,
+        build_file=build_file,
+        installs=installs
+    )
+
+    # Add the library we are wrapping.  The name doesn't include any platform
+    # specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the
+    # ".dll" extension on Windows).
+    makefile.extra_libs = ["hello"]
+
+    # Generate the Makefile itself.
+    makefile.generate()
+
+    # Now we create the configuration module.  This is done by merging a Python
+    # dictionary (whose values are normally determined dynamically) with a
+    # (static) template.
+    content = {
+        # Publish where the SIP specifications for this module will be
+        # installed.
+        "hello_sip_dir":    config.default_sip_dir,
+
+        # Publish the set of SIP flags needed by this module.  As these are the
+        # same flags needed by the qt module we could leave it out, but this
+        # allows us to change the flags at a later date without breaking
+        # scripts that import the configuration module.
+        "hello_sip_flags":  pyqt_sip_flags
+    }
+
+    # This creates the helloconfig.py module from the helloconfig.py.in
+    # template and the dictionary.
+    sipconfig.create_config_module("helloconfig.py", "helloconfig.py.in", content)
+
+Next we have the ``helloconfig.py.in`` template script::
+
+    from PyQt4 import pyqtconfig
+
+    # These are installation specific values created when Hello was configured.
+    # The following line will be replaced when this template is used to create
+    # the final configuration module.
+    # @SIP_CONFIGURATION@
+
+    class Configuration(pyqtconfig.Configuration):
+        """The class that represents Hello configuration values.
+        """
+        def __init__(self, sub_cfg=None):
+            """Initialise an instance of the class.
+
+            sub_cfg is the list of sub-class configurations.  It should be None
+            when called normally.
+            """
+            # This is all standard code to be copied verbatim except for the
+            # name of the module containing the super-class.
+            if sub_cfg:
+                cfg = sub_cfg
+            else:
+                cfg = []
+
+            cfg.append(_pkg_config)
+
+            pyqtconfig.Configuration.__init__(self, cfg)
+
+    class HelloModuleMakefile(pyqtconfig.QtGuiModuleMakefile):
+        """The Makefile class for modules that %Import hello.
+        """
+        def finalise(self):
+            """Finalise the macros.
+            """
+            # Make sure our C++ library is linked.
+            self.extra_libs.append("hello")
+
+            # Let the super-class do what it needs to.
+            pyqtconfig.QtGuiModuleMakefile.finalise(self)
+
+Again, we hope that the scripts are self documenting.
+
+.. [#] Some parts of a SIP specification aren't subject to version control.
+.. [#] Actually in ``versions.sip``.  PyQt uses the :directive:`%Include`
+       directive to split the SIP specification for Qt across a large number of
+       separate ``.sip`` files.
+.. [#] Tags can also be defined by the :directive:`%Feature` directive.  These
+       tags are not mutually exclusive, i.e. any number may be valid at a time.
+
+
+.. _ref-object-ownership:
+
+Ownership of Objects
+--------------------
+
+When a C++ instance is wrapped a corresponding Python object is created.  The
+Python object behaves as you would expect in regard to garbage collection - it
+is garbage collected when its reference count reaches zero.  What then happens
+to the corresponding C++ instance?  The obvious answer might be that the
+instance's destructor is called.  However the library API may say that when the
+instance is passed to a particular function, the library takes ownership of the
+instance, i.e. responsibility for calling the instance's destructor is
+transferred from the SIP generated module to the library.
+
+Ownership of an instance may also be associated with another instance.  The
+implication being that the owned instance will automatically be destroyed if
+the owning instance is destroyed.  SIP keeps track of these relationships to
+ensure that Python's cyclic garbage collector can detect and break any
+reference cycles between the owning and owned instances.  The association is
+implemented as the owning instance taking a reference to the owned instance.
+
+The TransferThis, Transfer and TransferBack annotations are used to specify
+where, and it what direction, transfers of ownership happen.  It is very
+important that these are specified correctly to avoid crashes (where both
+Python and C++ call the destructor) and memory leaks (where neither Python and
+C++ call the destructor).
+
+This applies equally to C structures where the structure is returned to the
+heap using the ``free()`` function.
+
+See also :cfunc:`sipTransferTo()`, :cfunc:`sipTransferBack()` and
+:cfunc:`sipTransferBreak()`.
+
+
+.. _ref-types-metatypes:
+
+Types and Meta-types
+--------------------
+
+Every Python object (with the exception of the :class:`object` object itself)
+has a meta-type and at least one super-type.  By default an object's meta-type
+is the meta-type of its first super-type.
+
+SIP implements two super-types, :class:`sip.simplewrapper` and
+:class:`sip.wrapper`, and a meta-type, :class:`sip.wrappertype`.
+
+:class:`sip.simplewrapper` is the super-type of :class:`sip.wrapper`.  The
+super-type of :class:`sip.simplewrapper` is :class:`object`.
+
+:class:`sip.wrappertype` is the meta-type of both :class:`sip.simplewrapper`
+and :class:`sip.wrapper`.  The super-type of :class:`sip.wrappertype` is
+:class:`type`.
+
+:class:`sip.wrapper` supports the concept of object ownership described in
+:ref:`ref-object-ownership` and, by default, is the super-type of all the types
+that SIP generates.
+
+:class:`sip.simplewrapper` does not support the concept of object ownership but
+SIP generated types that are sub-classed from it have Python objects that take
+less memory.
+
+SIP allows a class's meta-type and super-type to be explicitly specified using
+the :canno:`Metatype` and :canno:`Supertype` class annotations.
+
+SIP also allows the default meta-type and super-type to be changed for a module
+using the :directive:`%DefaultMetatype` and :directive:`%DefaultSupertype`
+directives.  Unlike the default super-type, the default meta-type is inherited
+by importing modules.
+
+If you want to use your own meta-type or super-type then they must be
+sub-classed from one of the SIP provided types.  Your types must be registered
+using :cfunc:`sipRegisterPyType()`.  This is normally done in code specified
+using the :directive:`%InitialisationCode` directive.
+
+As an example, PyQt4 uses :directive:`%DefaultMetatype` to specify a new
+meta-type that handles the interaction with Qt's own meta-type system.  It also
+uses :directive:`%DefaultSupertype` to specify that the smaller
+:class:`sip.simplewrapper` super-type is normally used.  Finally it uses
+:canno:`Supertype` as an annotation of the ``QObject`` class to override the
+default and use :class:`sip.wrapper` as the super-type so that the parent/child
+relationships of ``QObject`` instances are properly maintained.
+
+
+.. _ref-lazy-type-attributes:
+
+Lazy Type Attributes
+--------------------
+
+Instead of populating a wrapped type's dictionary with its attributes (or
+descriptors for those attributes) SIP only creates objects for those attributes
+when they are actually needed.  This is done to reduce the memory footprint and
+start up time when used to wrap large libraries with hundreds of classes and
+tens of thousands of attributes.
+
+SIP allows you to extend the handling of lazy attributes to your own attribute
+types by allowing you to register an attribute getter handler (using
+:cfunc:`sipRegisterAttributeGetter()`).  This will be called just before a
+type's dictionary is accessed for the first time.
+
+
+Support for Python's Buffer Interface
+-------------------------------------
+
+SIP supports Python's buffer interface in that whenever C/C++ requires a
+``char`` or ``char *`` type then any Python type that supports the buffer
+interface (including ordinary Python strings) can be used.
+
+If a buffer is made up of a number of segments then all but the first will be
+ignored.
+
+
+Support for Wide Characters
+---------------------------
+
+SIP v4.6 introduced support for wide characters (i.e. the ``wchar_t`` type).
+Python's C API includes support for converting between unicode objects and wide
+character strings and arrays.  When converting from a unicode object to wide
+characters SIP creates the string or array on the heap (using memory allocated
+using :cfunc:`sipMalloc()`).  This then raises the problem of how this memory
+is subsequently freed.
+
+The following describes how SIP handles this memory in the different situations
+where this is an issue.
+
+    - When a wide string or array is passed to a function or method then the
+      memory is freed (using :cfunc:`sipFree()`) after than function or method
+      returns.
+
+    - When a wide string or array is returned from a virtual method then SIP
+      does not free the memory until the next time the method is called.
+
+    - When an assignment is made to a wide string or array instance variable
+      then SIP does not first free the instance's current string or array.
+
+
+.. _ref-gil:
+
+The Python Global Interpreter Lock
+----------------------------------
+
+Python's Global Interpretor Lock (GIL) must be acquired before calls can be
+made to the Python API.  It should also be released when a potentially
+blocking call to C/C++ library is made in order to allow other Python threads
+to be executed.  In addition, some C/C++ libraries may implement their own
+locking strategies that conflict with the GIL causing application deadlocks.
+SIP provides ways of specifying when the GIL is released and acquired to
+ensure that locking problems can be avoided.
+
+SIP always ensures that the GIL is acquired before making calls to the Python
+API.  By default SIP does not release the GIL when making calls to the C/C++
+library being wrapped.  The :fanno:`ReleaseGIL` annotation can be used to
+override this behaviour when required.
+
+If SIP is given the :option:`-g <sip -g>` command line option then the default
+behaviour is changed and SIP releases the GIL every time is makes calls to the
+C/C++ library being wrapped.  The :fanno:`HoldGIL` annotation can be used to
+override this behaviour when required.
+
+
+.. _ref-incompat-apis:
+
+Managing Incompatible APIs
+--------------------------
+
+.. versionadded:: 4.9
+
+Sometimes it is necessary to change the way something is wrapped in a way that
+introduces an incompatibility.  For example a new feature of Python may
+suggest that something may be wrapped in a different way to exploit that
+feature.
+
+SIP's :directive:`%Feature` directive could be used to provide two different
+implementations.  However this would mean that the choice between the two
+implementations would have to be made when building the generated module
+potentially causing all sorts of deployment problems.  It may also require
+applications to work out which implementation was available and to change
+their behaviour accordingly.
+
+Instead SIP provides limited support for providing multiple implementations
+(of classes, mapped types and functions) that can be selected by an
+application at run-time.  It is then up to the application developer how they
+want to manage the migration from the old API to the new, incompatible API.
+
+This support is implemented in three parts.
+
+Firstly the :directive:`%API` directive is used to define the name of an API
+and its default version number.  The default version number is the one used if
+an application doesn't explicitly set the version number to use.
+
+Secondly the :canno:`API class <API>`, :manno:`mapped type <API>` or
+:fanno:`function <API>` annotation is applied accordingly to specify the API
+and range of version numbers that a particular class, mapped type or function
+implementation should be enabled for.
+
+Finally the application calls :func:`sip.setapi` to specify the version number
+of the API that should be enabled.  This call must be made before any module
+that has multiple implementations is imported for the first time.
+
+Note this mechanism is not intended as a way or providing equally valid
+alternative APIs.  For example::
+
+    %API MyAPI 1
+
+    class Foo
+    {
+    public:
+        void bar();
+    };
+
+    class Baz : Foo
+    {
+    public:
+        void bar() /API=MyAPI:2-/;
+    };
+
+If the following Python code is executed then an exception will be raised::
+
+    b = Baz()
+    b.bar()
+
+This is because when version 1 of the *MyAPI* API (the default) is enabled
+there is no *Baz.bar()* implementation and *Foo.bar()* will not be called
+instead as might be expected.