shiboken6: Fix up the documentation

- Link elements to their parent elements and to each other
- Link attribute "invalidate-after-use" of modify-argument
- Mention 3 ways of injecting code
- Fix and add more external URLs
- Remove  unsupported "since" attribute of inject-code
- Remove unsupported "target-declaration" modification

Change-Id: I3132b345468935f7b022153e3cbea0d519cd559f
Reviewed-by: Christian Tismer <tismer@stackless.com>
(cherry picked from commit bfa101c6f67bde1ee65cc6d272f3dbe597d1b744)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

8 files changed, 117 insertions, 60 deletions

diff --git a/sources/shiboken6/doc/typesystem_arguments.rst b/sources/shiboken6/doc/typesystem_arguments.rst
index 658da4295..9c64a0be8 100644
--- a/sources/shiboken6/doc/typesystem_arguments.rst
+++ b/sources/shiboken6/doc/typesystem_arguments.rst
@@ -196,7 +196,7 @@ 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.
+    parent is destroyed (see :ref:`ownership-parent`).
 
     .. code-block:: xml
 
diff --git a/sources/shiboken6/doc/typesystem_converters.rst b/sources/shiboken6/doc/typesystem_converters.rst
index 872daa187..1119f0f27 100644
--- a/sources/shiboken6/doc/typesystem_converters.rst
+++ b/sources/shiboken6/doc/typesystem_converters.rst
@@ -29,7 +29,7 @@ C++ and vice-versa.
 
 
 For the user defined conversion code to be inserted in the proper places,
-the "<conversion-rule>" tag must be used.
+the :ref:`conversion-rule` tag must be used.
 
       .. code-block:: xml
 
diff --git a/sources/shiboken6/doc/typesystem_documentation.rst b/sources/shiboken6/doc/typesystem_documentation.rst
index d73e43cb1..f03d8b70a 100644
--- a/sources/shiboken6/doc/typesystem_documentation.rst
+++ b/sources/shiboken6/doc/typesystem_documentation.rst
@@ -5,8 +5,8 @@ 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.
+    documentation. This node is a child of the :ref:`object-type`,
+    :ref:`value-type` and :ref:`modify-function` nodes.
 
     .. code-block:: xml
 
@@ -30,14 +30,22 @@ 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
+    documentation. . This node is a child of the :ref:`object-type`,
+    :ref:`value-type` and :ref:`modify-function` nodes.
+    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.
 
+.. _`qdoc`: https://doc.qt.io/qt-6/qdoc-index.html
+
+.. _`Sphinx`: https://www.sphinx-doc.org/en/master
+
     .. code-block:: xml
 
         <modify-documentation xpath="...">
             <!-- new documentation -->
         </modify-documentation>
 
-    The **xpath** attribute is the XPath to the node that you want to modify.
+    The **xpath** attribute is the `XPath`_ to the node that you want to modify.
+
+.. _`XPath`: https://www.w3.org/TR/1999/REC-xpath-19991116/
diff --git a/sources/shiboken6/doc/typesystem_manipulating_objects.rst b/sources/shiboken6/doc/typesystem_manipulating_objects.rst
index 7d2cc5198..f68d5a2b1 100644
--- a/sources/shiboken6/doc/typesystem_manipulating_objects.rst
+++ b/sources/shiboken6/doc/typesystem_manipulating_objects.rst
@@ -7,53 +7,94 @@ Manipulating Object and Value Types
 
 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.
 
+    .. code-block:: xml
+
+        <inject-code class="native | target"
+                     position="beginning | end" since="..."
+                     file="[file]"
+                     snippet="[label]"/>
+
+
+    The ``class`` attribute specifies which module of the generated code that
+    will be affected by the code injection
+    (see :ref:`codegenerationterminology`). The ``class`` attribute accepts the
+    following values:
+
+        * ``native``: The c++ code
+        * ``target``: The binding code
+
+    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.
+
+    For a detailed description of how to above attributes interact,
+    see :ref:`codeinjectionsemantics`.
+
+    The optional ``file`` attribute specifies the file name
+    (see :ref:`external-snippets`).
+
+    The optional ``snippet`` attribute specifies the snippet label
+    (see :ref:`external-snippets`).
+
+    There are severals ways to specify the code:
+
+Embedding Code into XML
+=======================
+
     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"
+             <inject-code class="native | target"
                  position="beginning | end" since="...">
                  // the code
              </inject-code>
          </value-type>
 
-    or obtained from an external file:
+
+Using a Template Specified in XML
+=================================
+
+    It is possible to create code templates for reuse in XML
+    (see :ref:`using-code-templates`). This allows for replacing of custom
+    placeholders.
 
     .. code-block:: xml
 
          <value-type>
-             <inject-code class="native | target | target-declaration"
-                 position="beginning | end" since="..."
-                 file="external_source.cpp"
-                 snippet="label"/>
+             <inject-code class="native | target" class="native | target">
+                 <insert-template name="template_name"/>
+             </inject-code>
          </value-type>
 
 
-    The ``class`` attribute specifies which module of the generated code that
-    will be affected by the code injection
-    (see :ref:`codegenerationterminology`). The ``class`` attribute accepts the
-    following values:
+.. _external-snippets:
 
-        * 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)
+Using Snippets From External Files
+==================================
 
-    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.
+    Code snippets can also be retrieved from external files found in the
+    typesystem search path (see :ref:`typesystem-paths`).
+
+    .. code-block:: xml
+
+         <value-type>
+             <inject-code class="native | target"
+                 position="beginning | end" since="..."
+                 file="external_source.cpp"
+                 snippet="label"/>
+         </value-type>
 
-    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
+    In the external file ``external_source.cpp``, the code between annotations
+    of the form:
 
     .. code-block:: c++
 
@@ -61,9 +102,8 @@ inject-code
         ...
         // @snippet label
 
-    will be extracted.
 
-    For a detailed description, see :ref:`codeinjectionsemantics`.
+    will be extracted.
 
 modify-field
 ^^^^^^^^^^^^
@@ -100,10 +140,10 @@ modify-field
 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.
+    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
 
diff --git a/sources/shiboken6/doc/typesystem_modify_function.rst b/sources/shiboken6/doc/typesystem_modify_function.rst
index d7ed13b07..121a22088 100644
--- a/sources/shiboken6/doc/typesystem_modify_function.rst
+++ b/sources/shiboken6/doc/typesystem_modify_function.rst
@@ -8,16 +8,17 @@ Modifying Functions
 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.
+    Function modifications consist of a list of ``modify-argument`` nodes
+    contained in a :ref:`modify-function` node.  Use the :ref:`remove-argument`,
+    :ref:`replace-default-expression`, :ref:`remove-default-expression`,
+    :ref:`replace-type`, :ref:`reference-count` and :ref:`define-ownership`
+    nodes to specify the details of the modification.
 
     .. code-block:: xml
 
          <modify-function>
-             <modify-argument index="return | this | 1 ..." rename="...">
+             <modify-argument index="return | this | 1 ..." rename="..."
+              invalidate-after-use = "true | false">
                  // modifications
              </modify-argument>
          </modify-function>
@@ -29,3 +30,6 @@ modify-argument
 
     The optional ``rename`` attribute is used to rename a argument and use this
     new name in the generated code.
+
+    For the optional ``invalidate-after-use`` attribute,
+    see :ref:`invalidationafteruse` .
diff --git a/sources/shiboken6/doc/typesystem_ownership.rst b/sources/shiboken6/doc/typesystem_ownership.rst
index a2ee8e1fa..71ddc8c71 100644
--- a/sources/shiboken6/doc/typesystem_ownership.rst
+++ b/sources/shiboken6/doc/typesystem_ownership.rst
@@ -58,14 +58,14 @@ Invalidate after use
 
     Objects marked with *invalidate-after-use* in the type system description always are
     virtual method arguments provided by a C++ originated call. They should be
-    invalidated right after the Python function returns.
+    invalidated right after the Python function returns (see :ref:`invalidationafteruse`).
 
 .. _ownership-virt-method:
 
 Objects with virtual methods
 ----------------------------
 
-    A little bit of implementation details:
+    A little bit of implementation details (see also :ref:`codegenerationterminology`):
     virtual methods are supported by creating a C++ class, the **shell**, that inherits
     from the class with virtual methods, the native one, and override those methods to check if
     any derived class in Python also override it.
@@ -73,9 +73,11 @@ Objects with virtual methods
     If the class has a virtual destructor (and C++ classes with virtual methods should have), this
     C++ instance invalidates the wrapper only when the overridden destructor is called.
 
-    One exception to this rule is when the object is created in C++, like in a
-    factory method. This way the wrapped object is a C++ instance of the native
-    class, not the shell one, and we cannot know when it is destroyed.
+    An instance of the **shell** is created when created in Python. However,
+    when  the object is created in C++, like in a factory method or a parameter
+    to a virtual function like ``QObject::event(QEvent *)``, the wrapped object
+    is a C++ instance of the native class, not the **shell** one, and we cannot
+    know when it is destroyed.
 
 .. _ownership-parent:
 
@@ -216,6 +218,12 @@ 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.**
 
+See `Object Trees and Object Ownership in Qt`_.
+
+.. _`Object Trees and Object Ownership in Qt`: http://doc.qt.io/qt-6/objecttrees.html
+
+.. _invalidationafteruse:
+
 Invalidation after use
 ----------------------
 
@@ -228,7 +236,3 @@ call returned. In this case, you should use the ``invalidate-after-use`` attribu
         <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`_.
-
-.. _`Object Trees and Object Ownership`: http://doc.qt.io/qt-5/objecttrees.html
diff --git a/sources/shiboken6/doc/typesystem_specifying_types.rst b/sources/shiboken6/doc/typesystem_specifying_types.rst
index b299c94ee..346d0c6e6 100644
--- a/sources/shiboken6/doc/typesystem_specifying_types.rst
+++ b/sources/shiboken6/doc/typesystem_specifying_types.rst
@@ -1,8 +1,6 @@
 Specifying Types
 ----------------
 
-.. _typesystem:
-
 Including Snippets
 ^^^^^^^^^^^^^^^^^^
 
@@ -27,6 +25,8 @@ in the type system paths passed as command line argument.
 Note that this is not a standard externally parsed entity due to the limitations
 of the underlying parser.
 
+.. _typesystem:
+
 typesystem
 ^^^^^^^^^^
 
diff --git a/sources/shiboken6/doc/typesystem_templates.rst b/sources/shiboken6/doc/typesystem_templates.rst
index 31b155c5a..b529776dc 100644
--- a/sources/shiboken6/doc/typesystem_templates.rst
+++ b/sources/shiboken6/doc/typesystem_templates.rst
@@ -6,9 +6,9 @@ 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.
+    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
+    :ref:`typesystem` node.
 
     .. code-block:: xml
 
@@ -18,16 +18,17 @@ template
             </template>
         </typesystem>
 
-    Use the insert-template node to insert the template code (identified by the
-    template's ``name`` attribute) into the generated code base.
+    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.
+    attribute, and it can be a child of the
+    :ref:`inject-code`, :ref:`conversion-rule`, ``template``,
+    ``custom-constructor`` and ``custom-destructor`` nodes.
 
     .. code-block:: xml
 
@@ -41,8 +42,8 @@ insert-template
 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.
+    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