diff options
Diffstat (limited to 'sources/pyside6/doc/developer/documentation.rst')
| -rw-r--r-- | sources/pyside6/doc/developer/documentation.rst | 73 |
1 files changed, 73 insertions, 0 deletions
diff --git a/sources/pyside6/doc/developer/documentation.rst b/sources/pyside6/doc/developer/documentation.rst new file mode 100644 index 000000000..517bd46f1 --- /dev/null +++ b/sources/pyside6/doc/developer/documentation.rst @@ -0,0 +1,73 @@ +.. _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/<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. + +.. 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) |