shiboken6: Add more links to the documentation

- Link the child nodes of the typesystem elements.
- Remove the section describing the deprecated conversion-rule
  syntax.
- Add more links and formatting throughout the documentation.
- Fix syntax error in considerations.

Change-Id: I602caa2e0728a94803ede0e8e77123e52b107fdd
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
(cherry picked from commit d27400ea27a2883f141f8fd4a41ec8e70ae23b83)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

11 files changed, 163 insertions, 109 deletions

diff --git a/sources/shiboken6/doc/considerations.rst b/sources/shiboken6/doc/considerations.rst
index 6539f06d3..abab2c28d 100644
--- a/sources/shiboken6/doc/considerations.rst
+++ b/sources/shiboken6/doc/considerations.rst
@@ -110,6 +110,7 @@ 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
 **************************
diff --git a/sources/shiboken6/doc/shibokengenerator.rst b/sources/shiboken6/doc/shibokengenerator.rst
index a5092bfd6..d811ee25f 100644
--- a/sources/shiboken6/doc/shibokengenerator.rst
+++ b/sources/shiboken6/doc/shibokengenerator.rst
@@ -60,12 +60,13 @@ the typesystem and, in most cases, the injected code.
          well to prevent the headers from being suppressed in the generated
          code.
 
-:typesystem: XML files that provides the developer with a tool to customize the
+::ref:`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.
+::ref:`inject code <codeinjectionsemantics>`: allows the developer to insert
+              handwritten code where the generated code is not suitable or
+              needs some customization.
 
 .. _command-line:
 
diff --git a/sources/shiboken6/doc/typesystem_arguments.rst b/sources/shiboken6/doc/typesystem_arguments.rst
index 9c64a0be8..ac5e1c826 100644
--- a/sources/shiboken6/doc/typesystem_arguments.rst
+++ b/sources/shiboken6/doc/typesystem_arguments.rst
@@ -3,13 +3,14 @@
 Modifying Arguments
 -------------------
 
-.. _conversionrule:
+.. _conversionrule-on-arguments:
 
 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:
+    The ``conversion-rule`` node allows you to write customized code to convert
+    the given argument between the target language and C++.
+    It is then a child of the :ref:`modify-argument` node:
 
     .. code-block:: xml
 
@@ -20,8 +21,8 @@ conversion-rule
         </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
+    This node is typically used in combination with the :ref:`replace-type` and
+    :ref:`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
@@ -35,15 +36,18 @@ conversion-rule
         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>`.
+    .. 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-tag>`.
 
 .. _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.
+    The ``remove-argument`` node removes the given argument from the function's
+    signature, and it is a child of the :ref:`modify-argument` node.
 
     .. code-block:: xml
 
@@ -56,7 +60,8 @@ remove-argument
 rename to
 ^^^^^^^^^
 
-    The 'rename to' node is used to rename a argument and use this new name in the generated code.
+    The ``rename to`` node is used to rename a argument and use this new name in
+    the generated code, and it is a child of the :ref:`modify-argument` node.
 
     .. code-block:: xml
 
@@ -71,8 +76,8 @@ rename to
 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.
+    The ``remove-default-expression`` node disables the use of the default expression
+    for the given argument, and it is a child of the :ref:`modify-argument` node.
 
     .. code-block:: xml
 
@@ -85,9 +90,9 @@ remove-default-expression
 replace-default-expression
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    The replace-default-expression node replaces the specified argument with the
+    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.
+    :ref:`modify-argument` node.
 
     .. code-block:: xml
 
@@ -100,9 +105,9 @@ replace-default-expression
 replace-type
 ^^^^^^^^^^^^
 
-    The replace-type node replaces the type of the given argument to the one
+    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.
+    :ref:`modify-argument` node.
 
     .. code-block:: xml
 
@@ -119,8 +124,10 @@ replace-type
 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
+    The ``define-ownership`` tag indicates that the function changes the ownership
+    rules of the argument object, and it is a child of the
+    :ref:`modify-argument` node.
+    The ``class`` attribute specifies the class of
     function where to inject the ownership altering code
     (see :ref:`codegenerationterminology`). The ``owner`` attribute
     specifies the new ownership of the object. It accepts the following values:
@@ -145,10 +152,11 @@ define-ownership
 reference-count
 ^^^^^^^^^^^^^^^
 
-    The reference-count tag dictates how an argument should be handled by the
+    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
+    the argument. It is a child of the :ref:`modify-argument` node.
+    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,
@@ -194,9 +202,10 @@ replace-value
 parent
 ^^^^^^
 
-    The parent node lets you define the argument parent which will
+    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 (see :ref:`ownership-parent`).
+    It is a child of the :ref:`modify-argument` node.
 
     .. code-block:: xml
 
diff --git a/sources/shiboken6/doc/typesystem_codeinjection.rst b/sources/shiboken6/doc/typesystem_codeinjection.rst
index 836609508..055e876a8 100644
--- a/sources/shiboken6/doc/typesystem_codeinjection.rst
+++ b/sources/shiboken6/doc/typesystem_codeinjection.rst
@@ -22,7 +22,7 @@ This is the ``inject-code`` tag options that matters to |project|.
 inject-code tag
 ===============
 
-The following table describes the semantics of ``inject-code`` tag as used on
+The following table describes the semantics of :ref:`inject-code` tag as used on
 |project|. The ``class`` attribute specifies whether to code is injected
 into the **C++ Wrapper** or the **Python Wrapper** (see
 :ref:`codegenerationterminology`).
diff --git a/sources/shiboken6/doc/typesystem_conversionrule.rst b/sources/shiboken6/doc/typesystem_conversionrule.rst
index fc87a85c9..4ac2bd365 100644
--- a/sources/shiboken6/doc/typesystem_conversionrule.rst
+++ b/sources/shiboken6/doc/typesystem_conversionrule.rst
@@ -10,7 +10,11 @@ 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.
+    target language types (see also :ref:`user-defined-type-conversion`).
+
+    It is a child of the :ref:`container-type`, :ref:`primitive-type` or
+    :ref:`value-type` and may contain :ref:`native-to-target` or
+    :ref:`native-to-target` child nodes.
 
     .. code-block:: xml
 
@@ -32,14 +36,19 @@ conversion-rule
             </conversion-rule>
         </value-type>
 
-    The code can be inserted directly, via ``add-conversion`` (providing snippet
-    functionality) or via ``insert-template`` (XML template,
+    The code can be inserted directly, via :ref:`add-conversion` (providing snippet
+    functionality) or via :ref:`insert-template` (XML template,
     see :ref:`using-code-templates`).
 
     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.
 
+    .. note::
+
+        You can also use the ``conversion-rule`` node to specify customized code
+        to convert a function argument between the target language and C++
+        (see :ref:`conversionrule-on-arguments`).
 
 .. _native-to-target:
 
@@ -47,9 +56,10 @@ 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
+    target language equivalent. It is a child of the :ref:`conversion-rule` node.
+    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.
+    :ref:`insert-template` tags may be used to insert commonly repeating code.
 
     .. code-block:: xml
 
@@ -75,9 +85,11 @@ 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
+    from target language values to C++ native values. It is a child of the
+    :ref:`conversion-rule` node and may have one or several :ref:`add-conversion`
+    child nodes. 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*.
 
 
@@ -100,6 +112,7 @@ add-conversion
     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.
+    It is a child of the :ref:`target-to-native` node.
 
     .. code-block:: xml
 
diff --git a/sources/shiboken6/doc/typesystem_converters.rst b/sources/shiboken6/doc/typesystem_converters.rst
index 1119f0f27..7858eb6a9 100644
--- a/sources/shiboken6/doc/typesystem_converters.rst
+++ b/sources/shiboken6/doc/typesystem_converters.rst
@@ -1,3 +1,5 @@
+.. _user-defined-type-conversion:
+
 ****************************
 User Defined Type Conversion
 ****************************
diff --git a/sources/shiboken6/doc/typesystem_manipulating_objects.rst b/sources/shiboken6/doc/typesystem_manipulating_objects.rst
index f68d5a2b1..d26ba332a 100644
--- a/sources/shiboken6/doc/typesystem_manipulating_objects.rst
+++ b/sources/shiboken6/doc/typesystem_manipulating_objects.rst
@@ -8,9 +8,10 @@ Manipulating Object and Value Types
 inject-code
 ^^^^^^^^^^^
 
-    The inject-code node inserts the given code into the generated code for the
+    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.
+    It may contain :ref:`insert-template` child nodes.
 
     .. code-block:: xml
 
@@ -108,7 +109,7 @@ Using Snippets From External Files
 modify-field
 ^^^^^^^^^^^^
 
-    The modify-field node allows you to alter the access privileges for a given
+    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.
 
@@ -141,9 +142,10 @@ 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.
+    mapping it onto the target language, and it is a child of a
+    :ref:`namespace`, :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
 
@@ -243,8 +245,8 @@ modify-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
+    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.
 
@@ -268,13 +270,19 @@ add-function
 
         void foo(int @parameter1@,float)
 
+
+    See :ref:`sequence-protocol` for adding the respective functions.
+
 .. _declare-function:
 
 declare-function
 ^^^^^^^^^^^^^^^^
 
-    The declare-function node allows you to declare a function present in the
-    type.
+    The ``declare-function`` node allows you to declare a function present in
+    the type 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.
 
     .. code-block:: xml
 
@@ -303,30 +311,6 @@ declare-function
     This tells shiboken a public function of that signature exists and
     bindings will be created in specializations of ``QList``.
 
-.. _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).
-
 .. _property-declare:
 
 property
@@ -335,8 +319,8 @@ property
     The ``property`` element allows you to specify properties consisting of
     a type and getter and setter functions.
 
-    It may appear as a child of a complex type such as ``object-type`` or
-    ``value-type``.
+    It may appear as a child of a complex type such as :ref:`object-type` or
+    :ref:`value-type`.
 
     If the PySide6 extension is not present, code will be generated using the
     ``PyGetSetDef`` struct, similar to what is generated for fields.
diff --git a/sources/shiboken6/doc/typesystem_sequenceprotocol.rst b/sources/shiboken6/doc/typesystem_sequenceprotocol.rst
index 742be3d70..63cc2c619 100644
--- a/sources/shiboken6/doc/typesystem_sequenceprotocol.rst
+++ b/sources/shiboken6/doc/typesystem_sequenceprotocol.rst
@@ -1,8 +1,10 @@
+.. _sequence-protocol:
+
 Sequence Protocol
 -----------------
 
 Support for the sequence protocol is achieved adding functions with special
-names, this is done using the add-function tag.
+names, this is done using the :ref:`add-function` tag.
 
 The special function names are:
 
@@ -16,7 +18,7 @@ The special function names are:
     __concat__    PyObject* self, PyObject* _other                PyObject*            PySequence_Concat
     ============= =============================================== ==================== ===================
 
-You just need to inform the function name to the add-function tag, without any
+You just need to inform the function name to the :ref:`add-function` tag, without any
 parameter or return type information, when you do it, |project| will create a C
 function with parameters and return type defined by the table above.
 
diff --git a/sources/shiboken6/doc/typesystem_solving_compilation.rst b/sources/shiboken6/doc/typesystem_solving_compilation.rst
index 23ab9012d..cca511d5b 100644
--- a/sources/shiboken6/doc/typesystem_solving_compilation.rst
+++ b/sources/shiboken6/doc/typesystem_solving_compilation.rst
@@ -1,12 +1,14 @@
 Solving compilation problems
 ----------------------------
 
+.. _suppress-warning:
+
 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.
+    user. The ``suppress-warning`` node suppresses the specified warning, and it is
+    a child of the :ref:`typesystem` node.
 
     .. code-block:: xml
 
@@ -18,12 +20,14 @@ suppress-warning
     wildcard (use "" to escape regular expression matching if the warning contain
     a regular "*").
 
+.. _extra-includes:
+
 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 ``extra-includes`` node contains declarations of additional include files,
+    and it can be a child of the :ref:`namespace`, :ref:`value-type` and
+    :ref:`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
@@ -48,9 +52,9 @@ extra-includes
 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 ``include`` node specifies the name and location of a file that must be
+    included, and it is a child of the :ref:`namespace`, :ref:`value-type`,
+    :ref:`object-type` or :ref:`extra-includes` node.
 
     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
diff --git a/sources/shiboken6/doc/typesystem_specifying_types.rst b/sources/shiboken6/doc/typesystem_specifying_types.rst
index 346d0c6e6..3cc1a334f 100644
--- a/sources/shiboken6/doc/typesystem_specifying_types.rst
+++ b/sources/shiboken6/doc/typesystem_specifying_types.rst
@@ -30,8 +30,15 @@ of the underlying parser.
 typesystem
 ^^^^^^^^^^
 
-    This is the root node containing all the type system information. It can
-    have a number of attributes, described below.
+    This is the root node containing all the type system information.
+    It may contain :ref:`add-function`, :ref:`container-type`,
+    :ref:`custom-type`, :ref:`enum-type`, :ref:`function`,
+    :ref:`load-typesystem`, :ref:`namespace`, :ref:`object-type`,
+    :ref:`primitive-type`, :ref:`rejection`, :ref:`smart-pointer-type`,
+    :ref:`suppress-warning`, :ref:`template`, :ref:`system_include`,
+    :ref:`typedef-type` or :ref:`value-type` child nodes.
+
+    It can have a number of attributes, described below.
 
     .. code-block:: xml
 
@@ -64,12 +71,14 @@ typesystem
       exist (as is the case for example for ``QFileInfo::exists()``),
       the snake case name must be used.
 
+.. _load-typesystem:
+
 load-typesystem
 ^^^^^^^^^^^^^^^
 
-    The load-typesystem node specifies which type systems to load when mapping
+    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.
+    it is a child of the :ref:`typesystem` node.
 
     .. code-block:: xml
 
@@ -86,12 +95,13 @@ load-typesystem
     Most libraries will be based on both the QtCore and QtGui modules, in which
     case code generation for these libraries will be disabled.
 
+.. _rejection:
 
 rejection
 ^^^^^^^^^
 
-    The rejection node rejects the given class, or the specified function or
-    field, and it is a child of the typesystem node.
+    The ``rejection`` node rejects the given class, or the specified function
+    or field, and it is a child of the :ref:`typesystem` node.
 
     .. code-block:: xml
 
@@ -112,9 +122,10 @@ rejection
 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.
+    The ``primitive-type`` node describes how a primitive type is mapped from C++ to
+    the target language, and is a child of the :ref:`typesystem` node. It may
+    contain :ref:`conversion-rule` child nodes. Note that most primitives are
+    already specified in the QtCore typesystem.
 
     .. code-block:: xml
 
@@ -170,9 +181,13 @@ primitive-type
 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).
+    The ``namespace-type`` node maps the given C++ namespace to the target
+    language, and it is a child of the :ref:`typesystem` node or other
+    ``namespace-type`` nodes. It may contain :ref:`add-function`,
+    :ref:`declare-function`,  :ref:`enum-type`, :ref:`extra-includes`,
+    :ref:`modify-function`, ``namespace-type``, :ref:`object-type`,
+    :ref:`smart-pointer-type`, :ref:`typedef-type` or :ref:`value-type`
+    child nodes.
 
     .. code-block:: xml
 
@@ -213,12 +228,14 @@ namespace-type
     The **revision** attribute can be used to specify a revision for each type, easing the
     production of ABI compatible bindings.
 
+.. _enum-type:
+
 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.
+    The ``enum-type`` node maps the given enum from C++ to the target language,
+    and it is a child of the :ref:`typesystem node`. Use
+    :ref:`reject-enum-value` child nodes to reject values.
 
     .. code-block:: xml
 
@@ -261,12 +278,13 @@ enum-type
     The **flags-revision** attribute has the same purposes of **revision** attribute but
     is used for the QFlag related to this enum.
 
+.. _reject-enum-value:
 
 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.
+    The ``reject-enum-value`` node rejects the enum value specified by the
+    **name** attribute, and it is a child of the :ref:`enum-type` node.
 
     .. code-block:: xml
 
@@ -282,9 +300,14 @@ reject-enum-value
 value-type
 ^^^^^^^^^^
 
-    The value-type node indicates that the given C++ type is mapped onto the target
+    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.
+    i.e. it is stored in the function call stack. It is a child of the :ref:`typesystem`
+    node or other type nodes and may contain :ref:`add-function`,
+    :ref:`declare-function`, :ref:`conversion-rule`, :ref:`enum-type`,
+    :ref:`extra-includes`, :ref:`modify-function`, :ref:`object-type`,
+    :ref:`smart-pointer-type`, :ref:`typedef-type` or further ``value-type``
+    child nodes.
 
     .. code-block:: xml
 
@@ -338,7 +361,11 @@ 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.
+    C++ and it is stored on the heap. It is a child of the :ref:`typesystem` node
+    or other type nodes and may contain :ref:`add-function`,
+    :ref:`declare-function`, :ref:`enum-type`, :ref:`extra-includes`,
+    :ref:`modify-function`, ``object-type``, :ref:`smart-pointer-type`,
+    :ref:`typedef-type` or :ref:`value-type` child nodes.
 
     .. code-block:: xml
 
@@ -401,8 +428,10 @@ interface-type
 container-type
 ^^^^^^^^^^^^^^
 
-    The container-type node indicates that the given class is a container and
+    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**.
+    It is a child of the :ref:`typesystem` node and may contain
+    :ref:`conversion-rule` child nodes.
 
     .. code-block:: xml
 
@@ -419,13 +448,16 @@ container-type
 
     The *optional*  **since** value is used to specify the API version of this container.
 
+.. _typedef-type:
+
 typedef-type
 ^^^^^^^^^^^^
 
-    The typedef-type allows for specifying typedefs in the typesystem. They
+    The ``typedef-type`` node 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.
+    It is a child of the :ref:`typesystem` node or other type nodes.
 
     .. code-block:: xml
 
@@ -457,10 +489,11 @@ typedef-type
 custom-type
 ^^^^^^^^^^^
 
-    The custom-type node simply makes the parser aware of the existence of a target
+    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.
+    It is a child of the :ref:`typesystem` node.
 
     .. code-block:: xml
 
@@ -475,11 +508,12 @@ custom-type
 smart-pointer-type
 ^^^^^^^^^^^^^^^^^^
 
-    The smart pointer type node indicates that the given class is a smart pointer
+    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.
+    It is a child of the :ref:`typesystem` node or other type nodes.
 
     The *optional* attribute **instantiations** specifies for which instantiations
     of the smart pointer wrappers will be generated (comma-separated list).
@@ -505,8 +539,9 @@ smart-pointer-type
 function
 ^^^^^^^^
 
-    The function node indicates that the given C++ global function is mapped onto
+    The ``function`` node indicates that the given C++ global function is mapped onto
     the target language.
+    It is a child of the :ref:`typesystem` node.
 
     .. code-block:: xml
 
@@ -534,6 +569,7 @@ system-include
     parsed. Normally, include files considered to be system include
     files are skipped by the C++ code parser. Its primary use case
     is exposing classes from the STL library.
+    It is a child of the :ref:`typesystem` node.
 
     .. code-block:: xml
 
diff --git a/sources/shiboken6/doc/typesystem_templates.rst b/sources/shiboken6/doc/typesystem_templates.rst
index b529776dc..7026f1502 100644
--- a/sources/shiboken6/doc/typesystem_templates.rst
+++ b/sources/shiboken6/doc/typesystem_templates.rst
@@ -3,6 +3,8 @@
 Using Code Templates
 --------------------
 
+.. _template:
+
 template
 ^^^^^^^^
 
@@ -21,14 +23,15 @@ template
     Use the ``insert-template`` node to insert the template code (identified
     by the template's ``name`` attribute) into the generated code base.
 
+.. _insert-template:
 
 insert-template
 ^^^^^^^^^^^^^^^
 
-    The insert-template node includes the code template identified by the name
-    attribute, and it can be a child of the
-    :ref:`inject-code`, :ref:`conversion-rule`, ``template``,
-    ``custom-constructor`` and ``custom-destructor`` nodes.
+    The ``insert-template`` node includes the code template identified by the
+    name attribute, and it can be a child of the :ref:`inject-code`,
+    :ref:`conversion-rule`, :ref:`template`, ``custom-constructor``
+    or ``custom-destructor`` nodes.
 
     .. code-block:: xml
 
@@ -36,14 +39,13 @@ insert-template
              <insert-template name="my_template" />
          </inject-code>
 
-    Use the replace node to modify the template 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``.
+    the generated code, and it can be a child of the :ref:`insert-template node`.
 
     .. code-block:: xml