Add references from ApiExtractor to shiboken doc

Including intersphinx extension allow us to link
the documentation from ApiExtractor to shiboken's.

ApiExtractor doc need to be build first, so we can
use the inventory that sphinx create, to link it
to shiboken's configuration.

All the harcoded references were replaced by dynamic
references. Also new labels were included to properly
cross reference topics.

Checked the spell on many rst files too.

Task-number: PYSIDE-363
Change-Id: I11a50b1f9eee48a00a3de6f957942eb0823eba47
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

6 files changed, 21 insertions, 33 deletions

diff --git a/sources/shiboken2/doc/CMakeLists.txt b/sources/shiboken2/doc/CMakeLists.txt
index 7bd0161ad..bb5ad8607 100644
--- a/sources/shiboken2/doc/CMakeLists.txt
+++ b/sources/shiboken2/doc/CMakeLists.txt
@@ -1,10 +1,10 @@
-
 find_program(SPHINX sphinx-build DOC "Path to sphinx-build binary.")
 
 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 bf3ddbe5e..0051c63df 100644
--- a/sources/shiboken2/doc/codeinjectionsemantics.rst
+++ b/sources/shiboken2/doc/codeinjectionsemantics.rst
@@ -2,12 +2,11 @@
 Code Injection Semantics
 ************************
 
-API Extractor provides the `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.
-
+:std:doc:`API Extractor <apiextractor:overview>` provides the
+:ref:`inject-code <apiextractor: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.
 
 This is the ``inject-code`` tag options that matters to |project|.
 
@@ -396,6 +395,3 @@ to prevent bad custom code to pass unnoticed.
         (...)
 
         // Start of ``MODULENAME_module_wrapper.cpp``
-
-
-.. _`inject-code`: http://www.pyside.org/docs/apiextractor/typesystem_manipulating_objects.html#inject-code
diff --git a/sources/shiboken2/doc/conf.py.in b/sources/shiboken2/doc/conf.py.in
index 5dc7b868d..57c2f94b9 100644
--- a/sources/shiboken2/doc/conf.py.in
+++ b/sources/shiboken2/doc/conf.py.in
@@ -22,7 +22,8 @@ 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']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.ifconfig',
+'sphinx.ext.coverage', 'sphinx.ext.intersphinx']
 
 rst_epilog = """
 .. |project| replace:: Shiboken
@@ -158,3 +159,4 @@ html_show_sourcelink = False
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
 
+intersphinx_mapping = {'apiextractor': ('@CMAKE_BINARY_DIR@/ApiExtractor/doc/html','@CMAKE_BINARY_DIR@/ApiExtractor/doc/html/objects.inv')}
diff --git a/sources/shiboken2/doc/faq.rst b/sources/shiboken2/doc/faq.rst
index 4b2bf9eea..3653b8654 100644
--- a/sources/shiboken2/doc/faq.rst
+++ b/sources/shiboken2/doc/faq.rst
@@ -11,7 +11,7 @@ General
 What is Shiboken?
 -----------------
 
-Shiboken is a `GeneratorRunner`_ that outputs C++ code for CPython
+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
@@ -45,7 +45,8 @@ 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 `typesystem`_ file with any customization wanted in
+The developer creates a :std:doc:`typesystem <apiextractor: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.
@@ -68,5 +69,3 @@ 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
-.. _`GeneratorRunner`:  http://www.pyside.org/home-binding/binding-generator
-.. _`typesystem`:  http://www.pyside.org/docs/apiextractor/typesystem.html
diff --git a/sources/shiboken2/doc/typeconverters.rst b/sources/shiboken2/doc/typeconverters.rst
index ea32c7f0c..6b29bdb4f 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
-`<native-to-target>`_, which has only one conversion from C++ to Python, and
-`<target-to-native>`_, that may define the conversion of multiple Python types
+: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
 to C++'s "Complex" type.
 
 .. image:: images/converter.png
     :height: 240px
     :align: center
 
-|project| expects the code for `<native-to-target>`_, to directly return the
+|project| expects the code for :ref:`native-to-target <apiextractor:native-to-target>`, to directly return the
 Python result of the conversion, and the added conversions inside the
-`<target-to-native>`_ must attribute the Python to C++ conversion result to
+:ref:`target-to-native <apiextractor: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 `<add-conversion>`_ tag and a custom check must be added.
+an :ref:`add-conversion <apiextractor:add-conversion>` tag and a custom check must be added.
 Here's how to do it:
 
       .. code-block:: xml
@@ -130,14 +130,12 @@ Here's how to do it:
 Container Conversions
 =====================
 
-Converters for `<container-type>`_ are pretty much the same as for other type,
+Converters for :ref:`container-type <apiextractor: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
 defined (or automatically generated) for the containers.
 
-.. _`container-type`: http://www.pyside.org/docs/apiextractor/typesystem_specifying_types.html#container-type
-
       .. code-block:: xml
 
             <container-type name="std::map" type="map">
@@ -288,10 +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 `<add-conversion>`_
+is gone, and the ``checkType`` is now an attribute of the :ref:`add-conversion <apiextractor: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.
-
-.. _`<native-to-target>`: http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#native-to-target
-.. _`<target-to-native>`: http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#target-to-native
-.. _`<add-conversion>`: http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#add-conversion
diff --git a/sources/shiboken2/doc/typesystemvariables.rst b/sources/shiboken2/doc/typesystemvariables.rst
index 9de2b02f5..e595f7ddc 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
-:doc:`inject-code <codeinjectionsemantics>` tag. To ease the binding developer
+:ref:`inject-code <apiextractor: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 `<remove-default-expression/>`_  type system tag.
+  with the :ref:`remove-default-expression <apiextractor:remove-default-expression>`  type system tag.
 
 
   Take the following method and related type system description as an example:
@@ -332,6 +332,3 @@ that expects a Python sequence instead.
                 delete[] argv;
             </inject-code>
         </modify-function>
-
-
-.. _`<remove-default-expression/>`: http://www.pyside.org/docs/apiextractor/typesystem_arguments.html#remove-default-expression