From c4a9c70cab27f2d5a054e6f1fd0769b4211eb2b7 Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Fri, 4 Aug 2023 14:22:26 +0200 Subject: Developer Documentation: Add documentation hints Move the sources/pyside6/doc/README.md to a new page of the Developer Documentation and prepend some information about fixing snippets/texts. Pick-to: 6.5 Change-Id: If80eaa34cce1c98f46dcd3102670ec61dd0ffbb0 Reviewed-by: Shyamnath Premnadh --- sources/pyside6/doc/developer/documentation.rst | 72 +++++++++++++++++++++++++ sources/pyside6/doc/developer/index.rst | 1 + 2 files changed, 73 insertions(+) create mode 100644 sources/pyside6/doc/developer/documentation.rst (limited to 'sources/pyside6/doc/developer') diff --git a/sources/pyside6/doc/developer/documentation.rst b/sources/pyside6/doc/developer/documentation.rst new file mode 100644 index 000000000..1ebfc18c5 --- /dev/null +++ b/sources/pyside6/doc/developer/documentation.rst @@ -0,0 +1,72 @@ +.. _developer-documentation: + +Fixing Documentation issues +=========================== + +Fixing texts +------------ + +Shiboken's ```` 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 '' "$F" > /dev/null # Exclude reference only + then + egrep "( /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) diff --git a/sources/pyside6/doc/developer/index.rst b/sources/pyside6/doc/developer/index.rst index 23bd21681..d15b36bc3 100644 --- a/sources/pyside6/doc/developer/index.rst +++ b/sources/pyside6/doc/developer/index.rst @@ -16,6 +16,7 @@ Development Topics add_module.rst add_port_example.rst add_tool.rst + documentation.rst extras.rst Implementation details -- cgit v1.2.3