Re-structure shiboken documentation

Task-number: PYSIDE-1112
Change-Id: Ice3e8efb7b75bd14ee73c20310f722c4e0b07b3b
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

17 files changed, 361 insertions, 304 deletions

diff --git a/sources/shiboken2/doc/_templates/layout.html b/sources/shiboken2/doc/_templates/layout.html
index 94ff3534e..2e2e9e892 100644
--- a/sources/shiboken2/doc/_templates/layout.html
+++ b/sources/shiboken2/doc/_templates/layout.html
@@ -8,7 +8,7 @@
 <div id="container">
 <div class="header">
     <div class="header_container">
-        <div class="logo"><a href="http://www.pyside.org"><img alt="PySide" src="{{ pathto('_static/pysidelogo.png', 1) }}" width="199" height="102" /></a></div>
+        <div class="logo"><a href="http://www.pyside.org"><img alt="PySide" src="{{ pathto('_static/pysidelogo.png', 1) }}"/></a></div>
   {{ relbar() }}
     </div>
 </div>
diff --git a/sources/shiboken2/doc/wordsofadvice.rst b/sources/shiboken2/doc/considerations.rst
index 9aebf1f03..3488c3407 100644
--- a/sources/shiboken2/doc/wordsofadvice.rst
+++ b/sources/shiboken2/doc/considerations.rst
@@ -110,3 +110,74 @@ this you will need use the new style class:
 
 All classes used for multiple inheritance with other PySide types need to have
 'object' as base class.
+**************************
+Frequently Asked Questions
+**************************
+
+This is a list of Frequently Asked Questions about |project|.
+Feel free to suggest new entries using our `Mailing list`_ or our IRC channel!
+
+General
+=======
+
+What is Shiboken?
+-----------------
+
+Shiboken is a Generator Runner plugin that outputs C++ code for CPython
+extensions.
+The first version of PySide had source code based on Boost templates.
+It was easier to produce code but a paradigm change was needed, as the next
+question explains.
+
+
+Why did you switch from Boost.Python to Shiboken?
+-------------------------------------------------
+
+The main reason was the size reduction. Boost.Python makes excessive use of
+templates resulting in a significant increase of the binaries size.
+On the other hand, as Shiboken generates CPython code, the resulting binaries
+are smaller.
+
+Creating bindings
+=================
+
+Can I wrap non-Qt libraries?
+----------------------------
+
+Yes. Check Shiboken source code for an example (libsample).
+
+
+Is there any runtime dependency on the generated binding?
+---------------------------------------------------------
+
+Yes. Only libshiboken, and the obvious Python interpreter
+and the C++ library that is being wrapped.
+
+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 <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
+will wrap the target library for python.
+
+
+Is there any recommended build system?
+--------------------------------------
+
+Both API Extractor and generator uses and recommends the CMake build system.
+
+Can I write closed-source bindings with the generator?
+------------------------------------------------------
+
+Yes, as long as you use a LGPL version of Qt, due to runtime requirements.
+
+What is 'inject code'?
+----------------------
+
+That's how we call customized code that will be *injected* into the
+generated at specific locations. They are specified inside the typesystem.
+
+.. _`Mailing list`:  http://lists.qt-project.org/mailman/listinfo/pyside
diff --git a/sources/shiboken2/doc/examples/index.rst b/sources/shiboken2/doc/examples/index.rst
new file mode 100644
index 000000000..92a64195e
--- /dev/null
+++ b/sources/shiboken2/doc/examples/index.rst
@@ -0,0 +1,9 @@
+Examples
+========
+
+C++ examples
+------------
+
+.. toctree::
+
+    samplebinding.rst
diff --git a/sources/shiboken2/doc/samplebinding.rst b/sources/shiboken2/doc/examples/samplebinding.rst
index 9043ed84c..a53b32bac 100644
--- a/sources/shiboken2/doc/samplebinding.rst
+++ b/sources/shiboken2/doc/examples/samplebinding.rst
@@ -240,8 +240,7 @@ Try running it to see if the ice creams are delivered.
     :file:`<PYTHON_ENV_ROOT>/site-packages/lib/PySide2/examples/samplebinding`.
 
 Refer to the following topics for detailed information about using Shiboken:
- * :doc:`Shiboken module <shibokenmodule>`
- * :doc:`Type System Variables <typesystemvariables>`
- * :doc:`User Defined Type Conversion <typeconverters>`
- * :doc:`Object ownership <ownership>`
- * :doc:`Frequently Asked Questions <faq>`
+ * :doc:`Type System Variables <../typesystem_variables>`
+ * :doc:`User Defined Type Conversion <../typesystem_converters>`
+ * :doc:`Object ownership <../typesystem_ownership>`
+ * :doc:`Considerations and Frequently Asked Questions <../considerations>`
diff --git a/sources/shiboken2/doc/faq.rst b/sources/shiboken2/doc/faq.rst
deleted file mode 100644
index eb77e5822..000000000
--- a/sources/shiboken2/doc/faq.rst
+++ /dev/null
@@ -1,71 +0,0 @@
-**************************
-Frequently Asked Questions
-**************************
-
-This is a list of Frequently Asked Questions about |project|.
-Feel free to suggest new entries using our `Mailing list`_ or our IRC channel!
-
-General
-=======
-
-What is Shiboken?
------------------
-
-Shiboken is a Generator Runner plugin that outputs C++ code for CPython
-extensions.
-The first version of PySide had source code based on Boost templates.
-It was easier to produce code but a paradigm change was needed, as the next
-question explains.
-
-
-Why did you switch from Boost.Python to Shiboken?
--------------------------------------------------
-
-The main reason was the size reduction. Boost.Python makes excessive use of
-templates resulting in a significant increase of the binaries size.
-On the other hand, as Shiboken generates CPython code, the resulting binaries
-are smaller.
-
-Creating bindings
-=================
-
-Can I wrap non-Qt libraries?
-----------------------------
-
-Yes. Check Shiboken source code for an example (libsample).
-
-
-Is there any runtime dependency on the generated binding?
----------------------------------------------------------
-
-Yes. Only libshiboken, and the obvious Python interpreter
-and the C++ library that is being wrapped.
-
-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 <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
-will wrap the target library for python.
-
-
-Is there any recommended build system?
---------------------------------------
-
-Both API Extractor and generator uses and recommends the CMake build system.
-
-Can I write closed-source bindings with the generator?
-------------------------------------------------------
-
-Yes, as long as you use a LGPL version of Qt, due to runtime requirements.
-
-What is 'inject code'?
-----------------------
-
-That's how we call customized code that will be *injected* into the
-generated at specific locations. They are specified inside the typesystem.
-
-.. _`Mailing list`:  http://lists.qt-project.org/mailman/listinfo/pyside
diff --git a/sources/shiboken2/doc/gettingstarted.rst b/sources/shiboken2/doc/gettingstarted.rst
new file mode 100644
index 000000000..e064cec5d
--- /dev/null
+++ b/sources/shiboken2/doc/gettingstarted.rst
@@ -0,0 +1,61 @@
+Getting started
+===============
+
+Building from source
+--------------------
+
+This step is focused on building Shiboken from source, both the Generator and Python module.
+Please notice that these are built when you are building PySide from source too, so there is no
+need to continue if you already have a built PySide.
+
+General Requirements
+^^^^^^^^^^^^^^^^^^^^
+
+ * **Python**: 3.5+ and 2.7
+ * **Qt:** 5.12+ is recommended
+ * **libclang:** The libclang library, recommended: version 6 for Shiboken2 5.12.
+   Prebuilt versions of it can be `downloaded here`_.
+ * **CMake:** 3.1+ is needed.
+
+.. _downloaded here: http://download.qt.io/development_releases/prebuilt/libclang/
+
+Simple build
+^^^^^^^^^^^^
+
+If you need only Shiboken Generator, a simple build run would look like this::
+
+    python setup.py install --qmake=/path/to/qmake \
+                            --build-tests \
+                            --parallel=8 \
+                            --verbose-build \
+                            --internal-build=shiboken2-generator
+
+The same can be used for the module, changing the value of ``internal-build`` to
+``shiboken2-module``.
+
+Using the wheels
+----------------
+
+Installing ``pyside2`` or ``shiboken2`` from pip **does not** install ``shiboken2_generator``,
+because the wheels are not on PyPi.
+
+You can get the ``shiboken2_generator`` wheels from Qt servers, and you can still install it
+via ``pip``::
+
+    pip install \
+        --index-url=http://download.qt.io/official_releases/QtForPython/ \
+        --trusted-host download.qt.io \
+        shiboken2 pyside2 shiboken2_generator
+
+
+The ``whl`` package cannot automatically discover in your system the location for:
+
+* Clang installation,
+* ``qmake`` location with the same version as the one described in the wheel,
+* Qt libraries with the same package version.
+
+So using this process requires you to manually modify the variables:
+
+* ``CLANG_INSTALL_DIR`` must be set to where the libraries are,
+* ``PATH`` must include the location for a ``qmake`` with the same Qt version as the package,
+* ``LD_LIBRARY_PATH`` including the Qt libraries and Clang libraries paths.
diff --git a/sources/shiboken2/doc/index.rst b/sources/shiboken2/doc/index.rst
index 0e08bacf9..ca452b9ca 100644
--- a/sources/shiboken2/doc/index.rst
+++ b/sources/shiboken2/doc/index.rst
@@ -1,39 +1,52 @@
-Shiboken the Binding Generator
-*******************************
+Shiboken
+********
 
-Shiboken is the CPython-based binding code generator for C or C++ libraries.
-It uses an ApiExtractor library to parse the C or C++ headers and get the
-type information, using Clang. You can also use this library to parse non-Qt
-projects. The following diagram summarizes Shiboken's role in the Qt for Python
-project.
+Shiboken is a fundamental piece on the `Qt for Python`_ project that serves two purposes:
 
-.. image:: images/qtforpython-underthehood.png
+* Generator_: Extract information from C or C++ headers and generate CPython_ code that allow
+  to bring C or C++ projects to Python. This process uses a library called ApiExtractor_ which
+  internally uses Clang_.
+* Module_: An utility Python module that exposed new Python types, functions to handle pointers,
+  among other things, that is written in CPython_ and can use independently of the generator.
 
-An XML typesystem file is used to specify the types to be exposed to Python
-and to apply modifications to properly represent and manipulate the types in
-the Python World. For example, you can remove and add methods to certain types,
-and also modify the arguments of each method. These actions are inevitable to
-properly handle the data structures or types.
+.. _`Qt for Python`: ../index.html
+.. _Generator: shibokengenerator.html
+.. _Module: shibokenmodule.html
+.. _CPython: https://github.com/python/cpython
+.. _Clang: https://clang.llvm.org/
+.. _ApiExtractor: typesystem.html
 
-The final outcome of this process is a set of wrappers written in CPython,
-which can be used as a module in your Python code.
+Documentation
+=============
 
-Table of Contents
-*****************
+.. raw:: html
+
+    <table class="special">
+        <colgroup>
+            <col style="width: 33%" />
+            <col style="width: 33%" />
+            <col style="width: 33%" />
+        </colgroup>
+        <tr>
+          <td><a href="gettingstarted.html"><p><strong>Getting Started</strong><br/>Install and build from source.</p></a></td>
+          <td><a href="shibokengenerator.html"><p><strong>Shiboken Generator</strong><br/>Binding generator executable.</p></a></td>
+          <td><a href="shibokenmodule.html"><p><strong>Shiboken Module</strong><br/>Python utility module.</p></a></td>
+        </tr>
+        <tr>
+          <td><a href="typesystem.html"><p><strong>Type System</strong><br/>Reference and functionallities.</p></a></td>
+          <td><a href="examples/index.html"><p><strong>Examples</strong><br/>Using Shiboken.</p></a></td>
+          <td><a href="considerations.html"><p><strong>Considerations</strong><br/>Known issues and FAQ.</p></a></td>
+        </tr>
+
+    </table>
 
 .. toctree::
-   :maxdepth: 1
-
-   overview.rst
-   samplebinding.rst
-   commandlineoptions.rst
-   projectfile.rst
-   typesystemvariables.rst
-   typeconverters.rst
-   codeinjectionsemantics.rst
-   sequenceprotocol.rst
-   ownership.rst
-   wordsofadvice.rst
+   :hidden:
+   :glob:
+
+   gettingstarted.rst
+   shibokengenerator.rst
    shibokenmodule.rst
-   faq.rst
    typesystem.rst
+   examples/index.rst
+   considerations.rst
diff --git a/sources/shiboken2/doc/overview.rst b/sources/shiboken2/doc/overview.rst
deleted file mode 100644
index 97ef2c13c..000000000
--- a/sources/shiboken2/doc/overview.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-.. _gen-overview:
-
-******************
-Generator Overview
-******************
-
-In a few words, the Generator is a utility that parses a collection of header and
-typesystem files, generating other files (code, documentation, etc.) as result.
-
-Creating new bindings
-=====================
-
-.. figure:: images/bindinggen-development.png
-   :scale: 80
-   :align: center
-
-   Creating new bindings
-
-Each module of the generator system has an specific role.
-
-1. Provide enough data about the classes and functions.
-2. Generate valid code, with modifications from typesystems and injected codes.
-3. Modify the API to expose the objects in a way that fits you target language best.
-4. Insert customizations where handwritten code is needed.
-
-.. figure:: images/shibokenqtarch.png
-   :scale: 80
-   :align: center
-
-   Runtime architecture
-
-The newly created binding will run on top of Shiboken which takes
-care of interfacing Python and the underlying C++ library.
-
-Handwritten inputs
-==================
-
-Creating new bindings involves creating two pieces of "code": the typesystem and
-the inject code.
-
-:typesystem: XML files that provides the developer with a tool to customize the
-             way that the generators will see the classes and functions. For
-             example, functions can be renamed, have its signature changed and
-             many other actions.
-:inject code: allows the developer to insert handwritten code where the generated
-              code is not suitable or needs some customization.
diff --git a/sources/shiboken2/doc/projectfile.rst b/sources/shiboken2/doc/projectfile.rst
deleted file mode 100644
index aa703d941..000000000
--- a/sources/shiboken2/doc/projectfile.rst
+++ /dev/null
@@ -1,67 +0,0 @@
-.. _project-file:
-
-********************
-Binding Project File
-********************
-
-Instead of directing the Generator behavior via command line, the binding
-developer can write a text project file describing the same information, and
-avoid the hassle of a long stream of command line arguments.
-
-.. _project-file-structure:
-
-The project file structure
-==========================
-
-Here follows a comprehensive example of a generator project file.
-
-    .. code-block:: ini
-
-         [generator-project]
-         generator-set = path/to/generator/CHOICE_GENERATOR
-         header-file = DIR/global.h" />
-         typesystem-file = DIR/typesystem_for_your_binding.xml
-         output-directory location="OUTPUTDIR" />
-         include-path = path/to/library/being/wrapped/headers/1
-         include-path = path/to/library/being/wrapped/headers/2
-         typesystem-path = path/to/directory/containing/type/system/files/1
-         typesystem-path = path/to/directory/containing/type/system/files/2
-         enable-parent-ctor-heuristic
-
-
-Project file tags
-=================
-
-The generator project file tags are in direct relation to the
-:ref:`command line arguments <command-line>`. All of the current command line
-options provided by |project| were already seen on the
-:ref:`project-file-structure`, for new command line options provided by
-additional generator modules (e.g.: qtdoc, Shiboken) could also be used in the
-generator project file following simple conversion rules.
-
-For tags without options, just write as an empty tag without any attributes.
-Example:
-
-    .. code-block:: bash
-
-         --BOOLEAN-ARGUMENT
-
-becomes
-
-    .. code-block:: ini
-
-         BOOLEAN-ARGUMENT
-
-and
-
-    .. code-block:: bash
-
-         --VALUE-ARGUMENT=VALUE
-
-becomes
-
-    .. code-block:: ini
-
-         VALUE-ARGUMENT = VALUE
-
-
diff --git a/sources/shiboken2/doc/shiboken2.1 b/sources/shiboken2/doc/shiboken2.1
deleted file mode 100644
index e017bd9a9..000000000
--- a/sources/shiboken2/doc/shiboken2.1
+++ /dev/null
@@ -1,73 +0,0 @@
-.TH SHIBOKEN "1" "March 2010" "shiboken v0.2.0" "User Commands"
-.SH NAME
-shiboken \- CPython bindings generator for C++ libraries
-.SH DESCRIPTION
-.SS "Usage:"
-.IP
-shiboken [options] header\-file typesystem\-file
-.SS "General options:"
-.TP
-\fB\-\-debug\-level\fR=\fI[sparse\fR|medium|full]
-Set the debug level
-.TP
-\fB\-\-documentation\-only\fR
-Do not generates any code, just the documentation
-.TP
-\fB\-\-generatorSet\fR
-generatorSet to be used. e.g. qtdoc
-.TP
-\fB\-\-help\fR
-Display this help and exit
-.TP
-\fB\-\-include\-paths=\fR<path>[:<path>:...]
-Include paths used by the C++ parser
-.TP
-\fB\-\-license\-file\fR=\fI[licensefile]\fR
-File used for copyright headers of generated files
-.TP
-\fB\-\-no\-suppress\-warnings\fR
-Show all warnings
-.TP
-\fB\-\-output\-directory\fR=\fI[dir]\fR
-The directory where the generated files will be written
-.TP
-\fB\-\-silent\fR
-Avoid printing any message
-.TP
-\fB\-\-typesystem\-paths=\fR<path>[:<path>:...]
-Paths used when searching for typesystems
-.TP
-\fB\-\-version\fR
-Output version information and exit
-.SS "Shiboken options:"
-.TP
-\fB\-\-disable\-verbose\-error\-messages\fR
-Disable verbose error messages. Turn the python code hard to debug but safe few kB on the generated bindings.
-.TP
-\fB\-\-enable\-parent\-ctor\-heuristic\fR
-Enable heuristics to detect parent relationship on constructors.
-.TP
-\fB\-\-enable\-pyside\-extensions\fR
-Enable PySide extensions, such as support for signal/slots, use this if you are creating a binding for a Qt\-based library.
-.TP
-\fB\-\-enable\-return\-value\-heuristic\fR
-Enable heuristics to detect parent relationship on return values (USE WITH CAUTION!)
-.SS "Shiboken options:"
-.TP
-\fB\-\-disable\-verbose\-error\-messages\fR
-Disable verbose error messages. Turn the python code hard to debug but safe few kB on the generated bindings.
-.TP
-\fB\-\-enable\-parent\-ctor\-heuristic\fR
-Enable heuristics to detect parent relationship on constructors.
-.TP
-\fB\-\-enable\-pyside\-extensions\fR
-Enable PySide extensions, such as support for signal/slots, use this if you are creating a binding for a Qt\-based library.
-.TP
-\fB\-\-enable\-return\-value\-heuristic\fR
-Enable heuristics to detect parent relationship on return values (USE WITH CAUTION!)
-.SH COPYRIGHT
-Copyright \(co 2016 The Qt Company Ltd.
-.SH AUTHOR
-.PP
-This manpage was written for Debian, starting with a help2man output, by
-Didier Raboud <didier@raboud.com>, on the 26. March 2010.
diff --git a/sources/shiboken2/doc/commandlineoptions.rst b/sources/shiboken2/doc/shibokengenerator.rst
index 19f614653..1a7152fbb 100644
--- a/sources/shiboken2/doc/commandlineoptions.rst
+++ b/sources/shiboken2/doc/shibokengenerator.rst
@@ -1,3 +1,64 @@
+.. _gen-overview:
+
+******************
+Generator Overview
+******************
+
+The following diagram summarizes Shiboken's role in the Qt for Python
+project.
+
+.. image:: images/qtforpython-underthehood.png
+
+An XML typesystem file is used to specify the types to be exposed to Python
+and to apply modifications to properly represent and manipulate the types in
+the Python World. For example, you can remove and add methods to certain types,
+and also modify the arguments of each method. These actions are inevitable to
+properly handle the data structures or types.
+
+The final outcome of this process is a set of wrappers written in CPython,
+which can be used as a module in your Python code.
+
+In a few words, the Generator is a utility that parses a collection of header and
+typesystem files, generating other files (code, documentation, etc.) as result.
+
+Creating new bindings
+=====================
+
+.. figure:: images/bindinggen-development.png
+   :scale: 80
+   :align: center
+
+   Creating new bindings
+
+Each module of the generator system has an specific role.
+
+1. Provide enough data about the classes and functions.
+2. Generate valid code, with modifications from typesystems and injected codes.
+3. Modify the API to expose the objects in a way that fits you target language best.
+4. Insert customizations where handwritten code is needed.
+
+.. figure:: images/shibokenqtarch.png
+   :scale: 80
+   :align: center
+
+   Runtime architecture
+
+The newly created binding will run on top of Shiboken which takes
+care of interfacing Python and the underlying C++ library.
+
+Handwritten inputs
+==================
+
+Creating new bindings involves creating two pieces of "code": the typesystem and
+the inject code.
+
+:typesystem: XML files that provides the developer with a tool to customize the
+             way that the generators will see the classes and functions. For
+             example, functions can be renamed, have its signature changed and
+             many other actions.
+:inject code: allows the developer to insert handwritten code where the generated
+              code is not suitable or needs some customization.
+
 .. _command-line:
 
 Command line options
@@ -184,3 +245,71 @@ QtDocGenerator Options
 ``--additional-documentation=<file>``
    List of additional XML files to be converted to .rst files
    (for example, tutorials).
+
+.. _project-file:
+
+********************
+Binding Project File
+********************
+
+Instead of directing the Generator behavior via command line, the binding
+developer can write a text project file describing the same information, and
+avoid the hassle of a long stream of command line arguments.
+
+.. _project-file-structure:
+
+The project file structure
+==========================
+
+Here follows a comprehensive example of a generator project file.
+
+    .. code-block:: ini
+
+         [generator-project]
+         generator-set = path/to/generator/CHOICE_GENERATOR
+         header-file = DIR/global.h" />
+         typesystem-file = DIR/typesystem_for_your_binding.xml
+         output-directory location="OUTPUTDIR" />
+         include-path = path/to/library/being/wrapped/headers/1
+         include-path = path/to/library/being/wrapped/headers/2
+         typesystem-path = path/to/directory/containing/type/system/files/1
+         typesystem-path = path/to/directory/containing/type/system/files/2
+         enable-parent-ctor-heuristic
+
+
+Project file tags
+=================
+
+The generator project file tags are in direct relation to the
+:ref:`command line arguments <command-line>`. All of the current command line
+options provided by |project| were already seen on the
+:ref:`project-file-structure`, for new command line options provided by
+additional generator modules (e.g.: qtdoc, Shiboken) could also be used in the
+generator project file following simple conversion rules.
+
+For tags without options, just write as an empty tag without any attributes.
+Example:
+
+    .. code-block:: bash
+
+         --BOOLEAN-ARGUMENT
+
+becomes
+
+    .. code-block:: ini
+
+         BOOLEAN-ARGUMENT
+
+and
+
+    .. code-block:: bash
+
+         --VALUE-ARGUMENT=VALUE
+
+becomes
+
+    .. code-block:: ini
+
+         VALUE-ARGUMENT = VALUE
+
+
diff --git a/sources/shiboken2/doc/typesystem.rst b/sources/shiboken2/doc/typesystem.rst
index 7674129cd..01c19ac7d 100644
--- a/sources/shiboken2/doc/typesystem.rst
+++ b/sources/shiboken2/doc/typesystem.rst
@@ -1,5 +1,5 @@
 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.
@@ -15,15 +15,43 @@ Below there is a complete reference guide to the various nodes (XML tags) of the
 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.
 
+Define types
+------------
+
+.. toctree::
+   :maxdepth: 1
+
+   typesystem_specifying_types.rst
+
+Modifying types
+---------------
+
 .. toctree::
+   :maxdepth: 1
+
+   typesystem_arguments.rst
+   typesystem_codeinjection.rst
+   typesystem_converters.rst
+   typesystem_templates.rst
+   typesystem_modify_function.rst
+   typesystem_manipulating_objects.rst
+   typesystem_conversionrule.rst
+   typesystem_documentation.rst
+   typesystem_variables.rst
 
-    typesystem_specifying_types
-    typesystem_manipulating_objects
-    typesystem_modify_function
-    typesystem_arguments
-    typesystem_solving_compilation
-    typesystem_templates
-    typesystem_conversionrule
-    typesystem_documentation
+Object ownership
+----------------
 
+.. toctree::
+   :maxdepth: 1
+
+   typesystem_ownership.rst
+
+Extra options and Python caveats
+--------------------------------
+
+.. toctree::
+   :maxdepth: 1
 
+   typesystem_solving_compilation.rst
+   typesystem_sequenceprotocol.rst
diff --git a/sources/shiboken2/doc/codeinjectionsemantics.rst b/sources/shiboken2/doc/typesystem_codeinjection.rst
index beb2997a3..c891fd2cd 100644
--- a/sources/shiboken2/doc/codeinjectionsemantics.rst
+++ b/sources/shiboken2/doc/typesystem_codeinjection.rst
@@ -1,8 +1,10 @@
+.. _codeinjectionsemantics:
+
 ************************
 Code Injection Semantics
 ************************
 
-:std:doc:`API Extractor <overview>` provides the
+:std:doc:`API Extractor <shibokengenerator>` 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
diff --git a/sources/shiboken2/doc/typeconverters.rst b/sources/shiboken2/doc/typesystem_converters.rst
index 872daa187..872daa187 100644
--- a/sources/shiboken2/doc/typeconverters.rst
+++ b/sources/shiboken2/doc/typesystem_converters.rst
diff --git a/sources/shiboken2/doc/ownership.rst b/sources/shiboken2/doc/typesystem_ownership.rst
index 59fdb9d66..69b61ff00 100644
--- a/sources/shiboken2/doc/ownership.rst
+++ b/sources/shiboken2/doc/typesystem_ownership.rst
@@ -224,4 +224,6 @@ call returned. In this case, you should use the ``invalidate-after-use`` attribu
 
 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
+See `Object Trees and Object Ownership`_.
+
+.. _`Object Trees and Object Ownership`: http://doc.qt.io/qt-5/objecttrees.html
diff --git a/sources/shiboken2/doc/sequenceprotocol.rst b/sources/shiboken2/doc/typesystem_sequenceprotocol.rst
index 26ae3b220..26ae3b220 100644
--- a/sources/shiboken2/doc/sequenceprotocol.rst
+++ b/sources/shiboken2/doc/typesystem_sequenceprotocol.rst
diff --git a/sources/shiboken2/doc/typesystemvariables.rst b/sources/shiboken2/doc/typesystem_variables.rst
index 73d4dd12c..73d4dd12c 100644
--- a/sources/shiboken2/doc/typesystemvariables.rst
+++ b/sources/shiboken2/doc/typesystem_variables.rst