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 <[email protected]>

2 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..1ebfc18c5
--- /dev/null
+++ b/sources/pyside6/doc/developer/documentation.rst
@@ -0,0 +1,72 @@
+.. _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)
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