shiboken: Move the Api extractor documentation into shiboken

It does not really make sense to have it separately and the reference
documentation is currently not accessible from the TOC. Move it over
and append it to the TOC. Merge the chapters on ownership chapters
(for starters, by simply concatenating).

The Api extractor overview chapter is dropped as it is outdated anyways.

Partially reverts 0d12d71920067be499d9237b4ad04f7f11047759.

Task-number: PYSIDE-363
Change-Id: I02f6b0a4bb91fc54267fa03cefd2ac7d4049f07b
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

17 files changed, 1307 insertions, 16 deletions

diff --git a/sources/shiboken2/doc/CMakeLists.txt b/sources/shiboken2/doc/CMakeLists.txt
index bb5ad8607..5903e9dfc 100644
--- a/sources/shiboken2/doc/CMakeLists.txt
+++ b/sources/shiboken2/doc/CMakeLists.txt
@@ -4,7 +4,6 @@ if (SPHINX)
     message("-- sphinx-build - found")
     configure_file(conf.py.in conf.py @ONLY)
     add_custom_target(doc ${SPHINX} -b html -c . ${CMAKE_CURRENT_SOURCE_DIR} html )
-    add_dependencies(doc doc_apiextractor)
 else()
     message("-- sphinx-build - not found! doc target disabled")
     if (WIN32)
diff --git a/sources/shiboken2/doc/codeinjectionsemantics.rst b/sources/shiboken2/doc/codeinjectionsemantics.rst
index 0051c63df..beb2997a3 100644
--- a/sources/shiboken2/doc/codeinjectionsemantics.rst
+++ b/sources/shiboken2/doc/codeinjectionsemantics.rst
@@ -2,8 +2,8 @@
 Code Injection Semantics
 ************************
 
-:std:doc:`API Extractor <apiextractor:overview>` provides the
-:ref:`inject-code <apiextractor:inject-code>` tag
+:std:doc:`API Extractor <overview>` provides the
+:ref:`inject-code <inject-code>` tag
 allowing the user to put custom written code to on specific locations of the generated code.
 Yet this is only part of what is needed to generate proper binding code, where the custom code
 should be written to depends upon the technology used on the generated binding code.
diff --git a/sources/shiboken2/doc/conf.py.in b/sources/shiboken2/doc/conf.py.in
index d3aa95c0b..e158abbbe 100644
--- a/sources/shiboken2/doc/conf.py.in
+++ b/sources/shiboken2/doc/conf.py.in
@@ -23,7 +23,7 @@ import sys, os
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.ifconfig',
-'sphinx.ext.coverage', 'sphinx.ext.intersphinx']
+'sphinx.ext.coverage']
 
 rst_epilog = """
 .. |project| replace:: Shiboken
@@ -158,5 +158,3 @@ html_show_sourcelink = False
 
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
-
-intersphinx_mapping = {'apiextractor': ('ApiExtractor','@CMAKE_BINARY_DIR@/ApiExtractor/doc/html/objects.inv')}
diff --git a/sources/shiboken2/doc/contents.rst b/sources/shiboken2/doc/contents.rst
index a0b40effb..7cdc0063e 100644
--- a/sources/shiboken2/doc/contents.rst
+++ b/sources/shiboken2/doc/contents.rst
@@ -15,3 +15,4 @@ Table of contents
     wordsofadvice.rst
     shibokenmodule.rst
     faq.rst
+    typesystem.rst
diff --git a/sources/shiboken2/doc/faq.rst b/sources/shiboken2/doc/faq.rst
index 3653b8654..eb77e5822 100644
--- a/sources/shiboken2/doc/faq.rst
+++ b/sources/shiboken2/doc/faq.rst
@@ -45,7 +45,7 @@ What do I have to do to create my bindings?
 -------------------------------------------
 
 Most of the work is already done by the API Extractor.
-The developer creates a :std:doc:`typesystem <apiextractor:typesystem>`
+The developer creates a :std:doc:`typesystem <typesystem>`
 file with any customization wanted in
 the generated code, like removing classes or changing method signatures.
 The generator will output the *.h* and *.cpp* files with the CPython code that
diff --git a/sources/shiboken2/doc/ownership.rst b/sources/shiboken2/doc/ownership.rst
index f3744a537..59fdb9d66 100644
--- a/sources/shiboken2/doc/ownership.rst
+++ b/sources/shiboken2/doc/ownership.rst
@@ -151,3 +151,77 @@ Not saving unowned objects references
        renderer.render()
 
 
+Ownership Management in  the Typesystem
+=======================================
+
+Ownership transfer from C++ to target
+-------------------------------------
+
+    When an object currently owned by C++ has its ownership transferred
+    back to the target language, the binding can know for sure when the object will be deleted and
+    tie the C++ instance existence to the wrapper, calling the C++ destructor normally when the
+    wrapper is deleted.
+
+    .. code-block:: xml
+
+        <modify-argument index="1">
+            <define-ownership class="target" owner="target" />
+        </modify-argument>
+
+Ownership transfer from target to C++
+-------------------------------------
+
+    In the opposite direction, when an object ownership is transferred from the target language
+    to C++, the native code takes full control of the object life and you don't
+    know when that object will be deleted, rendering the wrapper object invalid,
+    unless you're wrapping an object with a virtual destructor,
+    so you can override it and be notified of its destruction.
+
+    By default it's safer to just render the wrapper
+    object invalid and raise some error if the user tries to access
+    one of this objects members or pass it as argument to some function, to avoid unpleasant segfaults.
+    Also you should avoid calling the C++ destructor when deleting the wrapper.
+
+    .. code-block:: xml
+
+        <modify-argument index="1">
+            <define-ownership class="target" owner="c++" />
+        </modify-argument>
+
+
+Parent-child relationship
+-------------------------
+
+One special type of relationship is the parent-child. When an object is called
+the parent of another object (the child), the former is in charge of deleting its
+child when deleted and the target language can trust that the child will be alive
+as long as the parent is, unless some other method can take the C++ ownership away from the parent.
+
+One of the main uses of this scheme is Qt's object system, with ownership among QObject-derived
+classes, creating "trees" of instances.
+
+    .. code-block:: xml
+
+        <modify-argument index="this">
+            <parent index="1" action="add">
+        </modify-argument>
+
+In this example, the instance with the method that is being invoked (indicated by 'index="this"' on
+modify-argument) will be marked as a child
+of the first argument using the `parent` tag. To remove ownership, just use "remove" in the action attribute. **Removing
+parentship also transfers the ownership back to python.**
+
+Invalidation after use
+----------------------
+
+Sometimes an object is created as a virtual method call argument and destroyed after the
+call returned. In this case, you should use the ``invalidate-after-use`` attribute in the
+``modify-argument`` tag to mark the wrapper as invalid right after the virtual method returns.
+
+    .. code-block:: xml
+
+        <modify-argument index="2" invalidate-after-use="yes"/>
+
+In this example the second argument will be invalidated after this method call.
+
+.. [#] See *Object Trees and Object Ownership* http://doc.qt.io/qt-5/objecttrees.html
diff --git a/sources/shiboken2/doc/typeconverters.rst b/sources/shiboken2/doc/typeconverters.rst
index 6b29bdb4f..872daa187 100644
--- a/sources/shiboken2/doc/typeconverters.rst
+++ b/sources/shiboken2/doc/typeconverters.rst
@@ -58,22 +58,22 @@ the "<conversion-rule>" tag must be used.
 
 
 The details will be given later, but the gist of it are the tags
-:ref:`native-to-target <apiextractor:native-to-target>`, which has only one conversion from C++ to Python, and
-:ref:`native-to-native <apiextractor:target-to-native>`, that may define the conversion of multiple Python types
+:ref:`native-to-target <native-to-target>`, which has only one conversion from C++ to Python, and
+:ref:`native-to-native <target-to-native>`, that may define the conversion of multiple Python types
 to C++'s "Complex" type.
 
 .. image:: images/converter.png
     :height: 240px
     :align: center
 
-|project| expects the code for :ref:`native-to-target <apiextractor:native-to-target>`, to directly return the
+|project| expects the code for :ref:`native-to-target <native-to-target>`, to directly return the
 Python result of the conversion, and the added conversions inside the
-:ref:`target-to-native <apiextractor:target-to-native>` must attribute the Python to C++ conversion result to
+:ref:`target-to-native <target-to-native>` must attribute the Python to C++ conversion result to
 the :ref:`%out <out>` variable.
 
 Expanding on the last example, if the binding developer want a Python 2-tuple
 of numbers to be accepted by wrapped C++ functions with "Complex" arguments,
-an :ref:`add-conversion <apiextractor:add-conversion>` tag and a custom check must be added.
+an :ref:`add-conversion <add-conversion>` tag and a custom check must be added.
 Here's how to do it:
 
       .. code-block:: xml
@@ -130,7 +130,7 @@ Here's how to do it:
 Container Conversions
 =====================
 
-Converters for :ref:`container-type <apiextractor:container-type>` are pretty much the same as for other type,
+Converters for :ref:`container-type <container-type>` are pretty much the same as for other type,
 except that they make use of the type system variables
 :ref:`%INTYPE_# <intype_n>` and :ref:`%OUTTYPE_# <outtype_n>`.
 |project| combines the conversion code for containers with the conversion
@@ -286,6 +286,6 @@ In this case, the parts of the implementation that will be used in the new
 conversion-rule are the ones in the two last method
 ``static inline PyObject* toPython(const Complex& cpx)`` and
 ``static inline Complex toCpp(PyObject* pyobj)``. The ``isConvertible`` method
-is gone, and the ``checkType`` is now an attribute of the :ref:`add-conversion <apiextractor:add-conversion>`
+is gone, and the ``checkType`` is now an attribute of the :ref:`add-conversion <add-conversion>`
 tag. Refer back to the first example in this page and you will be able to
 correlate the above template with the new scheme of conversion rule definition.
diff --git a/sources/shiboken2/doc/typesystem.rst b/sources/shiboken2/doc/typesystem.rst
new file mode 100644
index 000000000..7674129cd
--- /dev/null
+++ b/sources/shiboken2/doc/typesystem.rst
@@ -0,0 +1,29 @@
+Type System Reference
+*********************
+
+The typesystem is used by a binding generator or any other software using the APIExtractor library
+to map a C++ library API onto a higher level language.
+
+The typesystem specification is a handwritten XML document listing the types
+that will be available in the generated target language API; types that are not
+declared in the specification will be ignored along with everything depending on
+them. In addition, it is possible to manipulate and modify types and functions.
+It is even possible to use the typesystem specification to inject arbitrary
+code into the source files, such as an extra member function.
+
+Below there is a complete reference guide to the various nodes (XML tags) of the typesystem.
+For usage examples, take a look at the typesystem files used to generate PySide2. These files
+can be found in the PySide2/<QT_MODULE_NAME> directory of the PySide2 package.
+
+.. toctree::
+
+    typesystem_specifying_types
+    typesystem_manipulating_objects
+    typesystem_modify_function
+    typesystem_arguments
+    typesystem_solving_compilation
+    typesystem_templates
+    typesystem_conversionrule
+    typesystem_documentation
+
+
diff --git a/sources/shiboken2/doc/typesystem_arguments.rst b/sources/shiboken2/doc/typesystem_arguments.rst
new file mode 100644
index 000000000..28a5c80bc
--- /dev/null
+++ b/sources/shiboken2/doc/typesystem_arguments.rst
@@ -0,0 +1,206 @@
+.. _modifying-arguments:
+
+Modifying Arguments
+-------------------
+
+.. _conversionrule:
+
+conversion-rule
+^^^^^^^^^^^^^^^
+
+    The conversion-rule node allows you to write customized code to convert
+    the given argument between the target language and C++, and it is a child of the modify-argument node:
+
+    .. code-block:: xml
+
+        <modify-argument index="2">
+        <!-- for the second argument of the function -->
+        <conversion-rule class="target | native">
+            // the code
+        </conversion-rule>
+        </modify-argument>
+
+    This node is typically used in combination with the replace-type and
+    remove-argument nodes. The given code is used instead of the generator's
+    conversion code.
+
+    Writing %N in the code (where N is a number), will insert the name of the
+    nth argument. Alternatively, %in and %out which will be replaced with the
+    name of the conversion's input and output variable, respectively. Note the
+    output variable must be declared explicitly, for example:
+
+    .. code-block:: xml
+
+        <conversion-rule class="native">
+        bool %out = (bool) %in;
+        </conversion-rule>
+
+    .. note:: You can also use the conversion-rule node to specify :ref:`a conversion code which will be used instead of the generator's conversion code everywhere for a given type <conversion-rule-on-types>`.
+
+.. _remove-argument:
+
+remove-argument
+^^^^^^^^^^^^^^^
+
+    The remove-argument node removes the given argument from the function's
+    signature, and it is a child of the modify-argument node.
+
+    .. code-block:: xml
+
+     <modify-argument>
+         <remove-argument />
+     </modify-argument>
+
+.. _rename-to:
+
+rename to
+^^^^^^^^^
+
+    The 'rename to' node is used to rename a argument and use this new name in the generated code.
+
+    .. code-block:: xml
+
+     <modify-argument>
+         <rename to='...' />
+     </modify-argument>
+
+.. _remove-default-expression:
+
+remove-default-expression
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    The remove-default-expression node disables the use of the default expression
+    for the given argument, and it is a child of the modify-argument node.
+
+    .. code-block:: xml
+
+         <modify-argument...>
+             <remove-default-expression />
+         </modify-argument>
+
+.. _replace-default-expression:
+
+replace-default-expression
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    The replace-default-expression node replaces the specified argument with the
+    expression specified by the ``with`` attribute, and it is a child of the
+    modify-argument node.
+
+    .. code-block:: xml
+
+         <modify-argument>
+             <replace-default-expression with="..." />
+         </modify-argument>
+
+.. _replace-type:
+
+replace-type
+^^^^^^^^^^^^
+
+    The replace-type node replaces the type of the given argument to the one
+    specified by the ``modified-type`` attribute, and it is a child of the
+    modify-argument node.
+
+    .. code-block:: xml
+
+         <modify-argument>
+             <replace-type modified-type="..." />
+         </modify-argument>
+
+    If the new type is a class, the ``modified-type`` attribute must be set to
+    the fully qualified name (including name of the package as well as the class
+    name).
+
+.. _define-ownership:
+
+define-ownership
+^^^^^^^^^^^^^^^^
+
+    The define-ownership tag indicates that the function changes the ownership
+    rules of the argument object. The ``class`` attribute specifies the class of
+    function where to inject the ownership altering code. The ``owner`` attribute
+    specifies the new ownership of the object. It accepts the following values:
+
+        * target: the target language will assume full ownership of the object.
+                  The native resources will be deleted when the target language
+                  object is finalized.
+        * c++: The native code assumes full ownership of the object. The target
+               language object will not be garbage collected.
+        * default: The object will get default ownership, depending on how it
+                   was created.
+
+    .. code-block:: xml
+
+        <modify-argument>
+              <define-ownership class="target | native"
+                                owner="target | c++ | default" />
+        </modify-argument>
+
+.. _reference-count:
+
+reference-count
+^^^^^^^^^^^^^^^
+
+    The reference-count tag dictates how an argument should be handled by the
+    target language reference counting system (if there is any), it also indicates
+    the kind of relationship the class owning the function being modified has with
+    the argument. For instance, in a model/view relation a view receiving a model
+    as argument for a **setModel** method should increment the model's reference
+    counting, since the model should be kept alive as much as the view lives.
+    Remember that out hypothetical view could not become parent of the model,
+    since the said model could be used by other views as well.
+    The ``action`` attribute specifies what should be done to the argument
+    reference counting when the modified method is called. It accepts the
+    following values:
+
+        * add: increments the argument reference counter.
+        * add-all: increments the reference counter for each item in a collection.
+        * remove: decrements the argument reference counter.
+        * set: will assign the argument to the variable containing the reference.
+        * ignore: does nothing with the argument reference counter
+                  (sounds worthless, but could be used in situations
+                   where the reference counter increase is mandatory
+                   by default).
+
+    .. code-block:: xml
+
+        <modify-argument>
+              <reference-count action="add|add-all|remove|set|ignore" variable-name="..." />
+        </modify-argument>
+
+
+    The variable-name attribute specifies the name used for the variable that
+    holds the reference(s).
+
+.. _replace-value:
+
+replace-value
+^^^^^^^^^^^^^
+
+    The ``replace-value`` attribute lets you replace the return statement of a
+    function with a fixed string. This attribute can only be used for the
+    argument at ``index`` 0, which is always the function's return value.
+
+    .. code-block:: xml
+
+         <modify-argument index="0" replace-value="this"/>
+
+.. _parent:
+
+parent
+^^^^^^
+
+    The parent node lets you define the argument parent which will
+    take ownership of argument and will destroy the C++ child object when the
+    parent is destroyed.
+
+    .. code-block:: xml
+
+        <modify-argument index="1">
+              <parent index="this" action="add | remove" />
+        </modify-argument>
+
+    In the ``index`` argument you must specify the parent argument. The action
+    *add* creates a parent link between objects, while *remove* will undo the
+    parentage relationship.
diff --git a/sources/shiboken2/doc/typesystem_conversionrule.rst b/sources/shiboken2/doc/typesystem_conversionrule.rst
new file mode 100644
index 000000000..27e7a72de
--- /dev/null
+++ b/sources/shiboken2/doc/typesystem_conversionrule.rst
@@ -0,0 +1,116 @@
+.. _conversion-rule-tag:
+
+Conversion Rule Tag
+-------------------
+
+.. _conversion-rule:
+
+conversion-rule
+^^^^^^^^^^^^^^^
+
+    The **conversion-rule** tag specifies how a **primitive-type**, a **container-type**,
+    or a **value-type** may be converted to and from the native C++ language types to the
+    target language types.
+
+    .. code-block:: xml
+
+        <value-type>
+            <conversion-rule>
+                <native-to-target>
+                // Code to convert a native value to a target language object.
+                </native-to-target>
+                <target-to-native>
+                    <add-conversion type='TARGETTYPEA' check='TARGETTYPEA_CHECK(%in)'>
+                    // Code to convert target language type object of type TARGETTYPEA
+                    // to the C++ native type represented by the value/primitive/container-type.
+                    </add-conversion>
+                    <add-conversion type='TARGETTYPEB' check='TARGETTYPEB_CHECK(%in)'>
+                    // Code to convert target language type object of type TARGETTYPEB
+                    // to the C++ native type represented by the value/primitive/container-type.
+                    </add-conversion>
+                </target-to-native>
+            </conversion-rule>
+        </value-type>
+
+    The example above show the structure of a complete conversion rule. Each of the
+    child tags comprising the conversion rule are described in their own sections
+    below.
+
+
+.. _native-to-target:
+
+native-to-target
+^^^^^^^^^^^^^^^^
+
+    The **native-to-target** tag tells how to convert a native C++ value to its
+    target language equivalent. The text inside the tag is a C++ code the takes
+    an input value an does what's needed to convert it to the output value.
+    ``insert-template`` tags may be used to insert commonly repeating code.
+
+    .. code-block:: xml
+
+        <conversion-rule>
+            <native-to-target>
+            // Code to convert a native value to a target language object.
+            </native-to-target>
+        </conversion-rule>
+
+    Use the replace node to modify the template code.
+    Notice that the generator must provide type system variables for the input
+    and output values and types, namely **%in**, **%out**, **%INTYPE** and
+    **%OUTTYPE**. In the case of container types, **%INTYPE** refers to the
+    full container type (e.g. **"list<int>"**) and **%INTYPE_0**, **%INTYPE_1**,
+    **%INTYPE_#**, should be replaced by the types used in the container template
+    (e.g. **%INTYPE_0** correspondes to **"int"** for **"list<int>"**).
+
+    The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes).
+
+.. _target-to-native:
+
+target-to-native
+^^^^^^^^^^^^^^^^
+
+    The **target-to-native** tag encloses at least one, but usually many, conversions
+    from target language values to C++ native values. The *optional* attribute
+    ``replace`` tells if the target language to C++ conversions will be added to, or if
+    they will replace the implicit conversions collected by *ApiExtractor*. The default
+    value for it is *yes*.
+
+
+    .. code-block:: xml
+
+        <conversion-rule>
+            <target-to-native replace='yes|no'>\
+            // List of target to native conversions meant to replace or expand
+            // the already existing implicit conversions.
+            </target-to-native>
+        </conversion-rule>
+
+
+.. _add-conversion:
+
+add-conversion
+^^^^^^^^^^^^^^
+
+    Each **add-conversion** tag adds a rule for conversion of a target language type,
+    indicated by the ``type`` attribute, to the C++ native type represented by the
+    **primitive-type**, a **container-type**, or **value-type**, to which the parent
+    **conversion-rule** belongs.
+
+    .. code-block:: xml
+
+        <target-to-native>
+            <add-conversion type='TARGETTYPE' check='TARGETTYPECHECK(%in)'>
+            // Code to convert target language type object of type TARGETTYPE_A
+            // to the C++ native type represented by the value/primitive/container-type.
+            </add-conversion>
+        <target-to-native>
+
+   The ``check`` attribute tells how a target value should be checked to see if it belongs to
+   the type expected. This attribute is *optional*, for it can be derived from the ``type``
+   attribute, but it isn't unusual that some special check is needed. The variables
+   **%in**, **%out**, **%INTYPE**, **%INTYPE_#**, and **%OUTTYPE**, must be provided by
+   the generator as in the ``native-to-target`` tag.
+
+   The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes).
+
diff --git a/sources/shiboken2/doc/typesystem_documentation.rst b/sources/shiboken2/doc/typesystem_documentation.rst
new file mode 100644
index 000000000..d73e43cb1
--- /dev/null
+++ b/sources/shiboken2/doc/typesystem_documentation.rst
@@ -0,0 +1,43 @@
+Manipulating Documentation
+--------------------------
+
+inject-documentation
+^^^^^^^^^^^^^^^^^^^^
+
+    The inject-documentation node inserts the documentation into the generated
+    documentation. This node is a child of the object-type, value-type and
+    modify-function nodes.
+
+    .. code-block:: xml
+
+         <value-type>
+             <inject-documentation mode="append | prepend | replace" format="native | target" >
+                 // the documentation
+             </inject-code>
+         </value-type>
+
+    The **mode** attribute default value is *replace*.
+
+    The **format** attribute specifies when the documentation injection will
+    occur and it accepts the following values:
+
+        * native: Before XML<->Backend transformation occur, so the injected code *must* be a valid XML.
+        * target: After XML<->Backend transformation occur, so the injected code *must* be a valid backend format.
+
+    At the moment the only supported backend is Sphinx.
+
+modify-documentation
+^^^^^^^^^^^^^^^^^^^^
+
+    The modify-documentation node allows you to change the auto-generated
+    documentation. API Extractor transforms XML's from qdoc (the Qt documentation
+    tool) into .rst files to be processed later using Sphinx. You can modify
+    the XML before the transformation takes place.
+
+    .. code-block:: xml
+
+        <modify-documentation xpath="...">
+            <!-- new documentation -->
+        </modify-documentation>
+
+    The **xpath** attribute is the XPath to the node that you want to modify.
diff --git a/sources/shiboken2/doc/typesystem_manipulating_objects.rst b/sources/shiboken2/doc/typesystem_manipulating_objects.rst
new file mode 100644
index 000000000..12b866ad7
--- /dev/null
+++ b/sources/shiboken2/doc/typesystem_manipulating_objects.rst
@@ -0,0 +1,182 @@
+.. _manipulating-object-and-value-types:
+
+Manipulating Object and Value Types
+-----------------------------------
+
+.. _inject-code:
+
+inject-code
+^^^^^^^^^^^
+    The inject-code node inserts the given code into the generated code for the
+    given type or function, and it is a child of the :ref:`object-type`, :ref:`value-type`,
+    :ref:`modify-function` and :ref:`add-function` nodes.
+
+    The code can be embedded into XML (be careful to use the correct XML entities
+    for characters like '<', '>', '&'):
+
+    .. code-block:: xml
+
+         <value-type>
+             <inject-code class="native | target | target-declaration"
+                 position="beginning | end" since="...">
+                 // the code
+             </inject-code>
+         </value-type>
+
+    or obtained from an external file:
+
+    .. code-block:: xml
+
+         <value-type>
+             <inject-code class="native | target | target-declaration"
+                 position="beginning | end" since="..."
+                 file="external_source.cpp"
+                 snippet="label"/>
+         </value-type>
+
+
+    The ``class`` attribute specifies which module of the generated code that
+    will be affected by the code injection. The ``class`` attribute accepts the
+    following values:
+
+        * native: The c++ code
+        * target: The binding code
+        * target-declaration: The code will be injected into the generated header
+          file containing the c++ wrapper class definition.
+        * file: The file name
+        * snippet: The snippet label (optional)
+
+    If the ``position`` attribute is set to *beginning* (the default), the code
+    is inserted at the beginning of the function. If it is set to *end*, the code
+    is inserted at the end of the function.
+
+    The ``since`` attribute specify the API version where this code was injected.
+
+    If a ``snippet`` label is given, the code between annotations of the form
+
+    .. code-block:: c++
+
+        // @snippet label
+        ...
+        // @snippet label
+
+    will be extracted.
+
+modify-field
+^^^^^^^^^^^^
+
+    The modify-field node allows you to alter the access privileges for a given
+    C++ field when mapping it onto the target language, and it is a child of an
+    :ref:`object-type` or a :ref:`value-type` node.
+
+    .. code-block:: xml
+
+         <object-type>
+             <modify-field name="..."
+                 write="true | false"
+                 read="true | false" />
+         </object-type>
+
+    The ``name`` attribute is the name of the field, the *optional* ``write``
+    and ``read`` attributes specify the field's access privileges in the target
+    language API (both are set to true by default).
+    The ``remove`` attribute is an *optional* attribute, which can mark the field
+    to be discarded on generation; it has the same purpose of the deprecated tag
+    :ref:`remove`.
+
+.. _modify-function:
+
+modify-function
+^^^^^^^^^^^^^^^
+
+    The modify-function node allows you to modify a given C++ function when mapping
+    it onto the target language, and it is a child of an :ref:`object-type` or a :ref:`value-type`
+    node. Use the :ref:`modify-argument` node to specify which argument the modification
+    affects.
+
+    .. code-block:: xml
+
+         <object-type>
+             <modify-function signature="..."
+                              since="..."
+                              remove="all | c++"
+                              access="public | private | protected"
+                              allow-thread="true | auto | false"
+                              exception-handling="off | auto-off | auto-on | on"
+                              rename="..." />
+         </object-type>
+
+    The ``signature`` attribute is a normalized C++ signature, excluding return
+    values but including potential const declarations.
+
+    The ``since`` attribute specify the API version when this function was modified.
+
+    The ``allow-thread`` attribute specifies whether a function should be wrapped
+    into ``Py_BEGIN_ALLOW_THREADS`` and ``Py_END_ALLOW_THREADS``, that is,
+    temporarily release the GIL (global interpreter lock). Doing so is required
+    for any thread-related  function (wait operations), functions that might call
+    a virtual function (potentially reimplemented in Python), and recommended for
+    lengthy I/O operations or similar. It has performance costs, though.
+    The value ``auto`` means that it will be turned off for functions for which
+    it is deemed to be safe, for example, simple getters.
+
+    The ``exception-handling`` attribute specifies whether to generate exception
+    handling code (nest the function call into try / catch statements). It accepts
+    the following values:
+
+           * no, false: Do not generate exception handling code
+           * auto-off: Generate exception handling code for functions
+             declaring a non-empty ``throw`` list
+           * auto-on: Generate exception handling code unless function
+             declares ``noexcept``
+           * yes, true: Always generate exception handling code
+
+    The ``remove``, ``access`` and ``rename`` attributes are *optional* attributes
+    for added convenience; they serve the same purpose as the deprecated tags :ref:`remove`, :ref:`access` and :ref:`rename`.
+
+.. _add-function:
+
+add-function
+^^^^^^^^^^^^
+
+    The add-function node allows you to add a given function onto the target language,
+    and it is a child of an :ref:`object-type` or :ref:`value-type` nodes if the
+    function is supposed to be a method, or :ref:`namespace` and :ref:`typesystem` if
+    the function is supposed to be a function inside a namespace or a global function.
+
+    Typically when adding a function some code must be injected to provide the function
+    logic. This can be done using the :ref:`inject-code` node.
+
+    .. code-block:: xml
+
+         <object-type>
+             <add-function signature="..." return-type="..." access="public | protected" static="yes | no" since="..."/>
+         </object-type>
+
+    The ``return-type`` attribute defaults to *void*, the ``access`` to *public* and the ``static`` one to *no*.
+
+    The ``since`` attribute specify the API version when this function was added.
+
+.. _conversion-rule-on-types:
+
+conversion-rule
+^^^^^^^^^^^^^^^
+
+    The conversion-rule node allows you to write customized code to convert the given argument between the target
+    language and C++, and is a child of the :ref:`value-type`, :ref:`object-type`, :ref:`primitive-type` and
+    :ref:`container-type` nodes.
+
+    The code pointed by the file attribute is very tied to the generator using APIExtractor, so it don't follow any
+    rules, but the generator rules..
+
+    .. code-block:: xml
+
+        <value-type name="Foo">
+            <convertion-rule file="my_converter_implementation.h" since="..."/>
+        </value-type>
+
+    The ``since`` attribute specify the API version when this conversion rule became valid.
+
+    .. note:: You can also use the conversion-rule node to specify :ref:`how the conversion of a single function argument should be done in a function <conversion-rule>`.
+
+    The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes).
diff --git a/sources/shiboken2/doc/typesystem_modify_function.rst b/sources/shiboken2/doc/typesystem_modify_function.rst
new file mode 100644
index 000000000..071cea4f5
--- /dev/null
+++ b/sources/shiboken2/doc/typesystem_modify_function.rst
@@ -0,0 +1,78 @@
+.. _modifying-functions:
+
+Modifying Functions
+-------------------
+
+.. _modify-argument:
+
+modify-argument
+^^^^^^^^^^^^^^^
+
+    The modify-argument node specifies which of the given function's arguments the
+    modification affects, and is a child of the modify-function node. Use the
+    remove-argument, replace-default-expression, remove-default-expression,
+    replace-type, reference-count and define-ownership nodes to specify the details
+    of the modification.
+
+    .. code-block:: xml
+
+         <modify-function>
+             <modify-argument index="return | this | 1 ..." >
+                 // modifications
+             </modify-argument>
+         </modify-function>
+
+    Set the ``index`` attribute to "1" for the first argument, "2" for the second
+    one and so on. Alternatively, set it to "return" or "this" if you want to
+    modify the function's return value or the object the function is called upon,
+    respectively.
+
+.. _remove:
+
+remove
+^^^^^^
+
+    The remove node removes the given method from the generated target language
+    API, and it is a child of the modify-function node.
+
+    .. code-block:: xml
+
+         <modify-function>
+             <remove class="all" />
+         </modify-function>
+
+    .. warning:: This tag is deprecated, use the ``remove`` attribute from :ref:`modify-function` tag instead.
+
+.. _access:
+
+access
+^^^^^^
+
+    The access node changes the access privileges of the given function in the
+    generated target language API, and it is a child of the modify-function node.
+
+    .. code-block:: xml
+
+        <modify-function>
+            <access modifier="public | protected | private"/>
+        </modify-function>
+
+    .. warning:: This tag is deprecated, use the ``access`` attribute from :ref:`modify-function` tag instead.
+
+.. _rename:
+
+rename
+^^^^^^
+
+    The rename node changes the name of the given function in the generated target
+    language API, and it is a child of the modify-function node.
+
+    .. code-block:: xml
+
+        <modify-function>
+            <rename to="..." />
+        </modify-function>
+
+    The ``to`` attribute is the new name of the function.
+
+    .. warning:: This tag is deprecated, use the ``rename`` attribute from :ref:`modify-function` tag instead.
diff --git a/sources/shiboken2/doc/typesystem_solving_compilation.rst b/sources/shiboken2/doc/typesystem_solving_compilation.rst
new file mode 100644
index 000000000..23ab9012d
--- /dev/null
+++ b/sources/shiboken2/doc/typesystem_solving_compilation.rst
@@ -0,0 +1,70 @@
+Solving compilation problems
+----------------------------
+
+suppress-warning
+^^^^^^^^^^^^^^^^
+
+    The generator will generate several warnings which may be irrelevant to the
+    user. The suppress-warning node suppresses the specified warning, and it is
+    a child of the typesystem node.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <suppress-warning text="..." />
+        </typesystem>
+
+    The **text** attribute is the warning text to suppress, and may contain the *
+    wildcard (use "" to escape regular expression matching if the warning contain
+    a regular "*").
+
+extra-includes
+^^^^^^^^^^^^^^
+
+    The extra-includes node contains declarations of additional include files,
+    and it can be a child of the interface-type, namespace-type, value-type and
+    object-type nodes.
+
+    The generator automatically tries to read the global header for each type but
+    sometimes it is required to include extra files in the generated C++ code to
+    make sure that the code compiles. These files must be listed using include
+    nodes within the extra-include node:
+
+    .. code-block:: xml
+
+         <value-type>
+             <extra-includes>
+                 <include file-name="..." location="global | local"/>
+             </extra-includes>
+         </value-type>
+
+    The **file-name** attribute is the file to include, such as "QStringList".
+    The **location** attribute is where the file is located: *global* means that
+    the file is located in $INCLUDEPATH and will be included using #include <...>,
+    *local* means that the file is in a local directory and will be included
+    using #include "...".
+
+
+include
+^^^^^^^
+
+    The include node specifies the name and location of a file that must be
+    included, and it is a child of the interface-type, namespace-type, value-type,
+    object-type or extra-includes nodes
+
+    The generator automatically tries to read the global header for each type. Use
+    the include node to override this behavior, providing an alternative file. The
+    include node can also be used to specify extra include files.
+
+    .. code-block:: xml
+
+         <value-type>
+             <include file-name="..."
+                 location="global | local"/>
+         </value-type>
+
+    The **file-name** attribute is the file to include, such as "QStringList".
+    The **location** attribute is where the file is located: *global* means that
+    the file is located in $INCLUDEPATH and will be included using #include <...>,
+    *local* means that the file is in a local directory and will be included
+    using #include "...".
diff --git a/sources/shiboken2/doc/typesystem_specifying_types.rst b/sources/shiboken2/doc/typesystem_specifying_types.rst
new file mode 100644
index 000000000..f4016bc2c
--- /dev/null
+++ b/sources/shiboken2/doc/typesystem_specifying_types.rst
@@ -0,0 +1,440 @@
+Specifying Types
+----------------
+
+.. _typesystem:
+
+typesystem
+^^^^^^^^^^
+
+    This is the root node containing all the type system information. It can
+    have a number of attributes, described below.
+
+    .. code-block:: xml
+
+        <typesystem package="..." default-superclass="..." allow-thread="..." exception-handling="...">
+        </typesystem>
+
+    The **package** attribute is a string describing the package to be used,
+    e.g. "QtCore".
+    The *optional* **default-superclass** attribute is the canonical C++ base class
+    name of all objects, e.g., "object".
+
+    The *optional* attributes **allow-thread** and **exception-handling**
+    specify the default handling for the corresponding function modification
+    (see :ref:`modify-function`).
+
+load-typesystem
+^^^^^^^^^^^^^^^
+
+    The load-typesystem node specifies which type systems to load when mapping
+    multiple libraries to another language or basing one library on another, and
+    it is a child of the typesystem node.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <load-typesystem name="..." generate="yes | no" />
+        </typesystem>
+
+    The **name** attribute is the filename of the typesystem to load, the
+    **generate** attribute specifies whether code should be generated or not. The
+    later must be specified when basing one library on another, making the generator
+    able to understand inheritance hierarchies, primitive mapping, parameter types
+    in functions, etc.
+
+    Most libraries will be based on both the QtCore and QtGui modules, in which
+    case code generation for these libraries will be disabled.
+
+
+rejection
+^^^^^^^^^
+
+    The rejection node rejects the given class, or the specified function or
+    field, and it is a child of the typesystem node.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <rejection class="..."
+                function-name="..."
+                field-name="..." />
+        </typesystem>
+
+    The **class** attribute is the C++ class name of the class to reject. Use the
+    *optional* **function-name** or **field-name** attributes to reject a particular
+    function or field. Note that the **field-name** and **function-name** cannot
+    be specified at the same time. To remove all occurrences of a given field or
+    function, set the class attribute to \*.
+
+.. _primitive-type:
+
+primitive-type
+^^^^^^^^^^^^^^
+
+    The primitive-type node describes how a primitive type is mapped from C++ to
+    the target language, and is a child of the typesystem node. Note that most
+    primitives are already specified in the QtCore typesystem.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <primitive-type name="..."
+                since="..."
+                target-name="..."
+                default-constructor="..."
+                preferred-conversion="yes | no" />
+        </typesystem>
+
+    The **name** attribute is the name of the primitive in C++, the optional,
+    **target-name** attribute is the name of the primitive type in the target
+    language. If the later two attributes are not specified their default value
+    will be the same as the **name** attribute.
+
+    The *optional*  **since** value is used to specify the API version of this type.
+
+    If the *optional* **preferred-conversion** attribute is set to *no*, it
+    indicates that this version of the primitive type is not the preferred C++
+    equivalent of the target language type. For example, in Python both "qint64"
+    and "long long" become "long" but we should prefer the "qint64" version. For
+    this reason we mark "long long" with preferred-conversion="no".
+
+    The *optional* **default-constructor** specifies the minimal constructor
+    call to build one value of the primitive-type. This is not needed when the
+    primitive-type may be built with a default constructor (the one without
+    arguments).
+
+    The *optional* **preferred-conversion** attribute tells how to build a default
+    instance of the primitive type. It should be a constructor call capable of
+    creating a instance of the primitive type. Example: a class "Foo" could have
+    a **preferred-conversion** value set to "Foo()". Usually this attribute is
+    used only for classes declared as primitive types and not for primitive C++
+    types, but that depends on the application using *ApiExtractor*.
+
+
+.. _namespace:
+
+namespace-type
+^^^^^^^^^^^^^^
+
+    The namespace-type node maps the given C++ namespace to the target language,
+    and it is a child of the typesystem node. Note that within namespaces, the
+    generator only supports enums (i.e., no functions or classes).
+
+    .. code-block:: xml
+
+        <typesystem>
+            <namespace-type name="..."
+                generate="yes | no"
+                package="..."
+                since="..."
+                revision="..." />
+        </typesystem>
+
+    The **name** attribute is the name of the namespace, e.g., "Qt".
+
+    The *optional* **generate** attribute is used to inform if you need to prepend
+    the given namespace into each generated class. Its default value is **yes**.
+
+    The **package** attribute can be used to override the package of the type system.
+
+    The *optional*  **since** value is used to specify the API version of this type.
+
+    The **revision** attribute can be used to specify a revision for each type, easing the
+    production of ABI compatible bindings.
+
+enum-type
+^^^^^^^^^
+
+    The enum-type node maps the given enum from C++ to the target language,
+    and it is a child of the typesystem node. Use the reject-enum-value to
+    reject values.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <enum-type name="..."
+                identified-by-value="..."
+                class="yes | no"
+                since="..."
+                flags="yes | no"
+                flags-revision="..."
+                lower-bound="..."
+                upper-bound="..."
+                force-integer="yes | no"
+                extensible="yes | no"
+                revision="..." />
+        </typesystem>
+
+    The **name** attribute is the fully qualified C++ name of the enum
+    (e.g.,"Qt::FillRule"). If the *optional* **flags** attribute is set to *yes*
+    (the default is *no*), the generator will expect an existing QFlags<T> for the
+    given enum type. The **lower-bound** and **upper-bound** attributes are used
+    to specify runtime bounds checking for the enum value. The value must be a
+    compilable target language statement, such as "QGradient.Spread.PadSpread"
+    (taking again Python as an example). If the **force-integer** attribute is
+    set to *yes* (the default is *no*), the generated target language code will
+    use the target language integers instead of enums. And finally, the
+    **extensible** attribute specifies whether the given enum can be extended
+    with user values (the default is *no*).
+
+    The *optional*  **since** value is used to specify the API version of this type.
+
+    The attribute **identified-by-value** helps to specify anonymous enums using the
+    name of one of their values, which is unique for the anonymous enum scope.
+    Notice that the **enum-type** tag can either have **name** or **identified-by-value**
+    but not both.
+
+    The **revision** attribute can be used to specify a revision for each type, easing the
+    production of ABI compatible bindings.
+
+    The **flags-revision** attribute has the same purposes of **revision** attribute but
+    is used for the QFlag related to this enum.
+
+
+reject-enum-value
+^^^^^^^^^^^^^^^^^
+
+    The reject-enum-value node rejects the enum value specified by the **name**
+    attribute, and it is a child of the enum-type node.
+
+    .. code-block:: xml
+
+         <enum-type>
+             <reject-enum-value name="..."/>
+         </enum-type>
+
+    This node is used when a C++ enum implementation has several identical numeric
+    values, some of which are typically obsolete.
+
+.. _value-type:
+
+value-type
+^^^^^^^^^^
+
+    The value-type node indicates that the given C++ type is mapped onto the target
+    language as a value type. This means that it is an object passed by value on C++,
+    i.e. it is stored in the function call stack. It is a child of the :ref:`typesystem` node.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <value-type  name="..." since="..."
+             copyable="yes | no"
+             allow-thread="..."
+             exception-handling="..."
+             hash-function="..."
+             stream="yes | no"
+             default-constructor="..."
+             revision="..." />
+        </typesystem>
+
+    The **name** attribute is the fully qualified C++ class name, such as
+    "QMatrix" or "QPainterPath::Element". The **copyable** attribute is used to
+    force or not specify if this type is copyable. The *optional* **hash-function**
+    attribute informs the function name of a hash function for the type.
+
+    The *optional* attribute **stream** specifies whether this type will be able to
+    use externally defined operators, like QDataStream << and >>. If equals to **yes**,
+    these operators will be called as normal methods within the current class.
+
+    The *optional*  **since** value is used to specify the API version of this type.
+
+    The *optional* **default-constructor** specifies the minimal constructor
+    call to build one instance of the value-type. This is not needed when the
+    value-type may be built with a default constructor (the one without arguments).
+    Usually a code generator may guess a minimal constructor for a value-type based
+    on its constructor signatures, thus **default-constructor** is used only in
+    very odd cases.
+
+    The **revision** attribute can be used to specify a revision for each type, easing the
+    production of ABI compatible bindings.
+
+    The *optional* attributes **allow-thread** and **exception-handling**
+    specify the default handling for the corresponding function modification
+    (see :ref:`modify-function`).
+
+.. _object-type:
+
+object-type
+^^^^^^^^^^^
+
+    The object-type node indicates that the given C++ type is mapped onto the target
+    language as an object type. This means that it is an object passed by pointer on
+    C++ and it is stored on the heap. It is a child of the :ref:`typesystem` node.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <object-type name="..."
+             since="..."
+             copyable="yes | no"
+             allow-thread="..."
+             exception-handling="..."
+             hash-function="..."
+             stream="yes | no"
+             revision="..." />
+        </typesystem>
+
+    The **name** attribute is the fully qualified C++ class name. If there is no
+    C++ base class, the default-superclass attribute can be used to specify a
+    superclass for the given type, in the generated target language API. The
+    **copyable** and **hash-function** attributes are the same as described for
+    :ref:`value-type`.
+
+    The *optional* attribute **stream** specifies whether this type will be able to
+    use externally defined operators, like QDataStream << and >>. If equals to **yes**,
+    these operators will be called as normal methods within the current class.
+
+    The *optional*  **since** value is used to specify the API version of this type.
+
+    The **revision** attribute can be used to specify a revision for each type, easing the
+    production of ABI compatible bindings.
+
+    The *optional* attributes **allow-thread** and **exception-handling**
+    specify the default handling for the corresponding function modification
+    (see :ref:`modify-function`).
+
+interface-type
+^^^^^^^^^^^^^^
+
+    The interface-type node indicates that the given class is replaced by an
+    interface pattern when mapping from C++ to the target language. Using the
+    interface-type node implicitly makes the given type an :ref:`object-type`.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <interface-type name="..."
+                since="..."
+                package ="..."
+                default-superclass ="..."
+                revision="..." />
+        </typesystem>
+
+    The **name** attribute is the fully qualified C++ class name. The *optional*
+    **package** attribute can be used to override the package of the type system.
+    If there is no C++ base class, the *optional* **default-superclass** attribute
+    can be used to specify a superclass in the generated target language API, for
+    the given class.
+
+    The *optional*  **since** value is used to specify the API version of this interface.
+
+    The **revision** attribute can be used to specify a revision for each type, easing the
+    production of ABI compatible bindings.
+
+.. _container-type:
+
+container-type
+^^^^^^^^^^^^^^
+
+    The container-type node indicates that the given class is a container and
+    must be handled using one of the conversion helpers provided by attribute **type**.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <container-type name="..."
+                since="..."
+                type ="..." />
+        </typesystem>
+
+    The **name** attribute is the fully qualified C++ class name. The **type**
+    attribute is used to indicate what conversion rule will be applied to the
+    container. It can be: *list*, *string-list*, *linked-list*, *vector*, *stack*,
+    *queue*, *set*, *map*, *multi-map*, *hash*, *multi-hash* or *pair*.
+
+    The *optional*  **since** value is used to specify the API version of this container.
+
+typedef-type
+^^^^^^^^^^^^
+
+    The typedef-type allows for specifying typedefs in the typesystem. They
+    are mostly equivalent to spelling out the typedef in the included header, which
+    is often complicated when trying to wrap libraries whose source code cannot be
+    easily extended.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <typedef-type name="..."
+                source="..."
+                since="..." />
+        </typesystem>
+
+    The **source** attribute is the source. Example:
+
+    .. code-block:: xml
+
+        <namespace-type name='std'>
+            <value-type name='optional' generate='no'/>\n"
+        </namespace-type>
+        <typedef-type name="IntOptional" source="std::optional&lt;int&gt;"/>
+
+    is equivalent to
+
+    .. code-block:: c++
+
+        typedef std::optional<int> IntOptional;
+
+    The *optional*  **since** value is used to specify the API version of this type.
+
+.. _custom-type:
+
+custom-type
+^^^^^^^^^^^
+
+    The custom-type node simply makes the parser aware of the existence of a target
+    language type, thus avoiding errors when trying to find a type used in function
+    signatures and other places. The proper handling of the custom type is meant to
+    be done by a generator using the APIExractor.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <custom-type name="..." />
+        </typesystem>
+
+    The **name** attribute is the name of the custom type, e.g., "PyObject".
+
+.. _smart-pointer-type:
+
+smart-pointer-type
+^^^^^^^^^^^^^^^^^^
+
+    The smart pointer type node indicates that the given class is a smart pointer
+    and requires inserting calls to **getter** to access the pointeee.
+    Currently, only the **type** *shared* is supported and the usage is limited
+    to function return values.
+    **ref-count-method** specifies the name of the method used to do reference counting.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <smart-pointer-type name="..."
+                since="..."
+                type="..."
+                getter="..."
+                ref-count-method="..."/>
+            </typesystem>
+
+.. _function:
+
+function
+^^^^^^^^
+
+    The function node indicates that the given C++ global function is mapped onto
+    the target language.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <function signature="..." rename="..." since="..."/>
+        </typesystem>
+
+    This tag has some limitations, it doesn't support function modifications, besides you
+    can't add a function overload using :ref:`add-function` tag to an existent function.
+    These limitation will be addressed in future versions of ApiExtractor.
+
+    The function tag has two *optional* attributes: **since**, whose value is used to specify
+    the API version of this function, and **rename**, to modify the function name.
+
diff --git a/sources/shiboken2/doc/typesystem_templates.rst b/sources/shiboken2/doc/typesystem_templates.rst
new file mode 100644
index 000000000..31b155c5a
--- /dev/null
+++ b/sources/shiboken2/doc/typesystem_templates.rst
@@ -0,0 +1,55 @@
+.. _using-code-templates:
+
+Using Code Templates
+--------------------
+
+template
+^^^^^^^^
+
+    The template node registers a template that can be used to avoid duplicate
+    code when extending the generated code, and it is a child of the typesystem
+    node.
+
+    .. code-block:: xml
+
+        <typesystem>
+            <template name="my_template">
+                // the code
+            </template>
+        </typesystem>
+
+    Use the insert-template node to insert the template code (identified by the
+    template's ``name`` attribute) into the generated code base.
+
+
+insert-template
+^^^^^^^^^^^^^^^
+
+    The insert-template node includes the code template identified by the name
+    attribute, and it can be a child of the inject-code, conversion-rule, template,
+    custom-constructor and custom-destructor nodes.
+
+    .. code-block:: xml
+
+         <inject-code class="target" position="beginning">
+             <insert-template name="my_template" />
+         </inject-code>
+
+    Use the replace node to modify the template code.
+
+
+replace
+^^^^^^^
+
+    The replace node allows you to modify template code before inserting it into
+    the generated code, and it can be a child of the insert-template node.
+
+    .. code-block:: xml
+
+        <insert-template name="my_template">
+           <replace from="..." to="..." />
+        </insert-template>
+
+    This node will replace the attribute ``from`` with the value pointed by
+    ``to``.
+
diff --git a/sources/shiboken2/doc/typesystemvariables.rst b/sources/shiboken2/doc/typesystemvariables.rst
index e595f7ddc..a07ba0d8c 100644
--- a/sources/shiboken2/doc/typesystemvariables.rst
+++ b/sources/shiboken2/doc/typesystemvariables.rst
@@ -3,7 +3,7 @@ Type System Variables
 *********************
 
 User written code can be placed in arbitrary places using the
-:ref:`inject-code <apiextractor:inject-code>` tag. To ease the binding developer
+:ref:`inject-code <inject-code>` tag. To ease the binding developer
 work, the injected code can make use of special variables that will be replaced
 by the correct values. This also shields the developer from some |project|
 implementation specifics.
@@ -59,7 +59,7 @@ Variables
   system), this value will be inserted in the argument list. If you want to remove
   the argument so completely that it doesn't appear in any form on the
   ``%ARGUMENT_NAMES`` replacement, don't forget to remove also its default value
-  with the :ref:`remove-default-expression <apiextractor:remove-default-expression>`  type system tag.
+  with the :ref:`remove-default-expression <remove-default-expression>`  type system tag.
 
 
   Take the following method and related type system description as an example: