.. _developer-documentation:

Fixing Documentation issues
===========================

Fixing texts
------------

Shiboken's ``<inject-documentation>`` element can be used to add texts.
It's ``"replace"`` mode is currently not implemented, though.

Fixing snippets
---------------

Snippets can replaced by placing a Python equivalent under ``sources/pyside6/doc/snippets``.
The directory structure matches that of Qt. To replace a snippet with the id `0` in
``qtbase/examples/foo/snippet.cpp``, place a file ``qtbase/examples/foo/snippet_0.cpp.py``
under that directory (one snippet per file with the snippet id appended to the base name).

More complicated mappings can be added to ``tools/snippets_translate/override.py``.

# Recreating the module descriptions after a Qt major version change

The source tree contains .rst files containing the module description in
doc/extras (named for example "QtCore.rst"). They are extracted/adapted from
the C++ module descriptions. If there is no module description file, shiboken
will extract the module description from the webxml files generated by qdoc.
This ends up in the build directory under doc/rst/PySide6/&lt;module&gt;/index.rst.
It can be used as a starting point for a module description file. C++
specific information like build instructions should be removed.

The descriptions may link to tutorials which can be added to additionaldocs.lst
for webxml extraction.

Maintaining additionaldocs.lst
------------------------------

The file is a list of additional documentation files. These are basically Qt
tutorials referenced by the documentation. They will receive some Python
adaption by shiboken/sphinx.

The list can be created by the below script and some hand-editing. It will find
almost all documents. Quite a number of them might be unreferenced, but there
is no good way of filtering for this.
Pages of examples that exist in Python should be removed.

.. code-block:: bash

    for F in *.webxml
    do
        echo "$F" | egrep '(-index)|(-module)|(-qmlmodule)\.webxml$' > /dev/null
        if [ $? -ne 0 ]
        then
            if fgrep '<para>' "$F" > /dev/null # Exclude reference only
            then
                egrep "(<class )|(<namespace )" $F > /dev/null || echo $F
            fi
        fi
    done

Inheritance graphs
------------------

``inheritance_diagram.pyproject`` lists the script involved in inheritance
graph generation, ``inheritance_diagram.py`` being the main one used by sphinx.
The others have main-test drivers for checking.

There are 2 scripts used for determining the inheritance:
* ``json_inheritance.py`` (env var ``INHERITANCE_FILE``) reads a
  inheritance.json file containing the class hierarchy generated by
  shiboken's doc generator.

* ``import_inheritance.py`` actually tries to import the class (legacy)