diff options
Diffstat (limited to 'sources/shiboken6/doc/typesystem_documentation.rst')
| -rw-r--r-- | sources/shiboken6/doc/typesystem_documentation.rst | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/sources/shiboken6/doc/typesystem_documentation.rst b/sources/shiboken6/doc/typesystem_documentation.rst new file mode 100644 index 000000000..4e7d18b99 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_documentation.rst @@ -0,0 +1,62 @@ +Manipulating Documentation +-------------------------- + +inject-documentation +^^^^^^^^^^^^^^^^^^^^ + +The inject-documentation node inserts the documentation into the generated +documentation. This node is a child of the :ref:`object-type`, +:ref:`value-type` and :ref:`modify-function` nodes. + +.. code-block:: xml + + <value-type> + <inject-documentation mode="append | prepend | replace" format="native | target" + file="[file]" snippet="[label]"> + // 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. + +The optional ``file`` attribute specifies the file name +(see :ref:`external-snippets`). + +The optional ``snippet`` attribute specifies the snippet label +(see :ref:`external-snippets`). + +At the moment the only supported backend is Sphinx. + +If the injected documentation contains a Sphinx function directive, no +directive will be auto-generated. This can be used to add parameter +documentation to added functions. + +modify-documentation +^^^^^^^^^^^^^^^^^^^^ + +The modify-documentation node allows you to change the auto-generated +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. + +.. _`XPath`: https://www.w3.org/TR/1999/REC-xpath-19991116/ |