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/<module>/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.

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)