From 900c050c66119454585ec83cf31149f6d64dd3ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristi=C3=A1n=20Maureira-Fredes?= Date: Tue, 4 Apr 2023 17:19:23 +0200 Subject: 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 --- sources/pyside6/doc/developer/add_port_example.rst | 2 +- sources/pyside6/doc/developer/add_tool.rst | 10 +-- .../pyside6/doc/developer/feature-motivation.rst | 11 ++- sources/pyside6/doc/developer/signature_doc.rst | 95 +++++++++------------- 4 files changed, 48 insertions(+), 70 deletions(-) (limited to 'sources/pyside6/doc/developer') 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 `__ - - `PEP 484 – Type Hints `__ - - `PEP 3107 – Function Annotations `__ +* `PEP 362 – Function Signature Object `__ +* `PEP 484 – Type Hints `__ +* `PEP 3107 – Function Annotations `__ *Personal Remark: This module is dedicated to our lovebird "Püppi", who died on 2017-09-15.* -- cgit v1.2.3