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.

Change-Id: If80eaa34cce1c98f46dcd3102670ec61dd0ffbb0
Reviewed-by: Shyamnath Premnadh <Shyamnath.Premnadh@qt.io>
(cherry picked from commit c4a9c70cab27f2d5a054e6f1fd0769b4211eb2b7)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 33 insertions, 7 deletions

diff --git a/sources/pyside6/doc/README.md b/sources/pyside6/doc/developer/documentation.rst
index 746e44989..1ebfc18c5 100644
--- a/sources/pyside6/doc/README.md
+++ b/sources/pyside6/doc/developer/documentation.rst
@@ -1,3 +1,24 @@
+.. _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
@@ -11,7 +32,8 @@ 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
+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
@@ -22,6 +44,8 @@ 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
@@ -34,14 +58,15 @@ Pages of examples that exist in Python should be removed.
         fi
     done
 
-# Inheritance graphs
+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.
+``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
+* ``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)
+* ``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