doc: fix issues with pyside rst files

Fixing extra indentation, syntax issues, and formatting.
Adapting too some snippet line highlights, and many other
details.

Pick-to: 6.5
Change-Id: Ife4eb5cec03577b2902d409b4007ae6d12141747
Reviewed-by: Friedemann Kleint <[email protected]>

4 files changed, 48 insertions, 70 deletions

diff --git a/sources/pyside6/doc/developer/add_port_example.rst b/sources/pyside6/doc/developer/add_port_example.rst
index 1188b8c4c..6ddd1f0f2 100644
--- a/sources/pyside6/doc/developer/add_port_example.rst
+++ b/sources/pyside6/doc/developer/add_port_example.rst
@@ -33,7 +33,7 @@ Port a Qt example
 - Add a ``.pyproject`` file (verify later on that docs build).
 - Add a ``doc`` directory and descriptive ``.rst`` file,
   and a screenshot if suitable (use ``optipng`` to reduce file size).
-- Add the """Port of the ... example from Qt 6""" doc string.
+- Add the ``"""Port of the ... example from Qt 6"""`` doc string.
 - Try to port variable and function names to snake case convention.
 - Verify that a flake check is mostly silent.
 - Remove C++ documentation from ``sources/pyside6/doc/additionaldocs.lst``.
diff --git a/sources/pyside6/doc/developer/add_tool.rst b/sources/pyside6/doc/developer/add_tool.rst
index 31a6e773f..bceccbdce 100644
--- a/sources/pyside6/doc/developer/add_tool.rst
+++ b/sources/pyside6/doc/developer/add_tool.rst
@@ -26,16 +26,16 @@ Add a Qt tool wrapper
 - Install the files (``sources/pyside-tools/CMakeLists.txt``).
 - Include the tool in the deprecated 'setup.py bdist_wheel' process:
 
-   - Add the tool in ``build_scripts/__init__.py``.
+  - Add the tool in ``build_scripts/__init__.py``.
 
-   - Copy the files to the wheels in ``build_scripts/platforms/*.py``.
+  - Copy the files to the wheels in ``build_scripts/platforms/*.py``.
 
-   - Add an entry to ``sources/pyside6/doc/gettingstarted/package_details.rst``.
+  - Add an entry to ``sources/pyside6/doc/gettingstarted/package_details.rst``.
 
 - Include the tool in the new wheel creation process:
 
-   - Add an entry to ``create_wheels.py``.
+  - Add an entry to ``create_wheels.py``.
 
-   - Include the Qt binaries explicitly on ``build_scripts/wheel_files.py``
+  - Include the Qt binaries explicitly on ``build_scripts/wheel_files.py``
 
 - Build with ``--standalone``, verify it is working.
diff --git a/sources/pyside6/doc/developer/feature-motivation.rst b/sources/pyside6/doc/developer/feature-motivation.rst
index 9249e034e..43bbb86b6 100644
--- a/sources/pyside6/doc/developer/feature-motivation.rst
+++ b/sources/pyside6/doc/developer/feature-motivation.rst
@@ -84,12 +84,11 @@ all methods of all classes used in this module are changing their name.
 
 The algorithm to change names is this:
 
- * if the name has less than 3 chars, or
- * if two upper chars are adjacent, or
- * if the name starts with ``gl`` (which marks OpenGL),
- * the name is returned unchanged. Otherwise
-
- * a single upper char ``C`` is replaced by ``_c``
+* if the name has less than 3 chars, or
+* if two upper chars are adjacent, or
+* if the name starts with ``gl`` (which marks OpenGL),
+* the name is returned unchanged. Otherwise
+* a single upper char ``C`` is replaced by ``_c``
 
 
 The true_property feature
diff --git a/sources/pyside6/doc/developer/signature_doc.rst b/sources/pyside6/doc/developer/signature_doc.rst
index 3bd28ad68..c81e9a559 100644
--- a/sources/pyside6/doc/developer/signature_doc.rst
+++ b/sources/pyside6/doc/developer/signature_doc.rst
@@ -136,71 +136,52 @@ Really important are the **parser**, **mapping**, **errorhandler**, **enum_sig**
 or be compatible with embedding and installers.
 
 
-loader.py
-+++++++++
+**loader.py**
+    This module assembles and imports the ``inspect`` module, and then exports the
+    ``create_signature`` function. This function takes a fake function and some
+    attributes and builds a ``__signature__`` object with the inspect module.
 
-This module assembles and imports the ``inspect`` module, and then exports the
-``create_signature`` function. This function takes a fake function and some
-attributes and builds a ``__signature__`` object with the inspect module.
 
+**parser.py**
+    This module takes a class signatures string from C++ and parses it into the
+    needed properties for the ``create_signature`` function. Its entry point is the
+    ``pyside_type_init`` function, which is called from the C module via ``loader.py``.
 
-parser.py
-+++++++++
 
-This module takes a class signatures string from C++ and parses it into the
-needed properties for the ``create_signature`` function. Its entry point is the
-``pyside_type_init`` function, which is called from the C module via ``loader.py``.
+**mapping.py**
+    The purpose of the mapping module is maintaining a list of replacement strings
+    that map from the *signature text* in C to the property strings that Python
+    needs. A lot of mappings are resolved by rather complex expressions in ``parser.py``,
+    but a few hundred cases are better to spell explicitly, here.
 
+**errorhandler.py**
+    Since ``Qt For Python 5.12``, we no longer use the builtin type error messages from C++.
+    Instead, we get much better results with the signature module. At the same time,
+    this enforced supporting shiboken as well, and the signature module was no longer
+    optional.
 
-mapping.py
-++++++++++
+**enum_sig.py**
+    The diverse applications of the signature module all needed to iterate over modules,
+    classes and functions. In order to centralize this enumeration, the process has
+    been factored out as a context manager. The user has only to supply functions
+    that do the actual formatting.
 
-The purpose of the mapping module is maintaining a list of replacement strings
-that map from the *signature text* in C to the property strings that Python
-needs. A lot of mappings are resolved by rather complex expressions in ``parser.py``,
-but a few hundred cases are better to spell explicitly, here.
+    See for example the .pyi generator ``pyside6/PySide6/support/generate_pyi.py``.
 
+**layout.py**
+    As more applications used the signature module, different formatting of signatures
+    was needed. To support that, we created the function ``create_signature``, which
+    has a parameter to choose from some predefined layouts.
 
-errorhandler.py
-+++++++++++++++
 
-Since ``Qt For Python 5.12``, we no longer use the builtin type error messages from C++.
-Instead, we get much better results with the signature module. At the same time,
-this enforced supporting shiboken as well, and the signature module was no longer
-optional.
+**typing27.py**
+    Python 2 has no typing module at all. This is a backport of the minimum that is needed.
 
 
-enum_sig.py
-+++++++++++
-
-The diverse applications of the signature module all needed to iterate over modules,
-classes and functions. In order to centralize this enumeration, the process has
-been factored out as a context manager. The user has only to supply functions
-that do the actual formatting.
-
-See for example the .pyi generator ``pyside6/PySide6/support/generate_pyi.py``.
-
-
-layout.py
-+++++++++
-
-As more applications used the signature module, different formatting of signatures
-was needed. To support that, we created the function ``create_signature``, which
-has a parameter to choose from some predefined layouts.
-
-
-*typing27.py*
-+++++++++++++
-
-Python 2 has no typing module at all. This is a backport of the minimum that is needed.
-
-
-*backport_inspect.py*
-+++++++++++++++++++++
-
-Python 2 has an inspect module, but lacks the signature functions, completely.
-This module adds the missing functionality, which is merged at runtime into
-the inspect module.
+**backport_inspect.py**
+    Python 2 has an inspect module, but lacks the signature functions, completely.
+    This module adds the missing functionality, which is merged at runtime into
+    the inspect module.
 
 
 Multiple Arities
@@ -372,11 +353,9 @@ This was implemented in ``Qt For Python 5.12.1``.
 Literature
 ----------
 
-    `PEP 362 – Function Signature Object <https://www.python.org/dev/peps/pep-0362/>`__
-
-    `PEP 484 – Type Hints <https://www.python.org/dev/peps/pep-0484/>`__
-
-    `PEP 3107 – Function Annotations <https://www.python.org/dev/peps/pep-3107/>`__
+* `PEP 362 – Function Signature Object <https://www.python.org/dev/peps/pep-0362/>`__
+* `PEP 484 – Type Hints <https://www.python.org/dev/peps/pep-0484/>`__
+* `PEP 3107 – Function Annotations <https://www.python.org/dev/peps/pep-3107/>`__
 
 
 *Personal Remark: This module is dedicated to our lovebird "Püppi", who died on 2017-09-15.*