.. _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:

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

The file is a list of additional documentation files. These are basically Qt
tutorials referenced by the documentation, for example "Additional Frameworks"
sections of module files. They will receive some Python adaption by
shiboken/sphinx.

A line in brackets denotes the output directory.

The list can be created by running the below script in the PySide6 build
directory 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

    find_docs()
    {
        for F in $(find . -name "*.webxml")
        do
            echo "$F" | egrep '(-index|example|cmake|private-module|-changes-qt6|-module.web|-qmlmodule.web)' > /dev/null
            if [ $? -ne 0 ]
            then
                if fgrep '<para>' "$F" > /dev/null # Exclude reference only
                then
                    egrep "(<namespace|<class|<struct|<group|<union)" $F > /dev/null || echo $F
                fi
            fi
        done
    }

    cd doc/qdoc-output
    find_docs | cut -c3- | sort

The overviews go into a directory named ``overviews``. There are also special
pages containing lists of classes with brief, grouped by function. They mostly
have a ``<group name="...">`` WebXML element, but may also be hand-written.
They should be referenced from the module page in a section named `List of
Classes by Function`. For clarity, the files with a ``<group>`` element are
placed into a separate directory ``groups``.

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)
