doc: Add page for pyside6-genpyi

Add a documentation page for the pyside6-genpyi tool. This also removes
an unused argument and clarifies that the --feature argument is
currently not available for PyPy.

Change-Id: Ic2fa7e92ae0ccbc30e997db8d7dfad02e5b26732
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>

2 files changed, 62 insertions, 9 deletions

diff --git a/sources/pyside6/PySide6/support/generate_pyi.py b/sources/pyside6/PySide6/support/generate_pyi.py
index 5a2cf05ee..92808e2a5 100644
--- a/sources/pyside6/PySide6/support/generate_pyi.py
+++ b/sources/pyside6/PySide6/support/generate_pyi.py
@@ -8,14 +8,14 @@ This script generates the .pyi files for all PySide modules.
 """
 
 import argparse
-import inspect
+import inspect  # noqa: F401
 import logging
 import os
 import sys
-import typing
+import typing  # noqa: F401
 
 from pathlib import Path
-from types import SimpleNamespace
+from types import SimpleNamespace  # noqa: F401
 
 # Can we use forward references?
 USE_PEP563 = sys.version_info[:2] >= (3, 7)
@@ -25,7 +25,7 @@ def generate_all_pyi(outpath, options):
     ps = os.pathsep
     if options.sys_path:
         # make sure to propagate the paths from sys_path to subprocesses
-        normpath = lambda x: os.fspath(Path(x).resolve())
+        normpath = lambda x: os.fspath(Path(x).resolve())  # noqa: E731
         sys_path = [normpath(_) for _ in options.sys_path]
         sys.path[0:0] = sys_path
         pypath = ps.join(sys_path)
@@ -63,15 +63,16 @@ if __name__ == "__main__":
     parser = argparse.ArgumentParser(
         description="This script generates the .pyi file for all PySide modules.")
     parser.add_argument("modules", nargs="+",
-        help="'all' or the names of modules to build (QtCore QtGui etc.)")
+                        help="'all' or the names of modules to build (QtCore QtGui etc.)")
     parser.add_argument("--quiet", action="store_true", help="Run quietly")
-    parser.add_argument("--check", action="store_true", help="Test the output if on Python 3")
     parser.add_argument("--outpath",
-        help="the output directory (default = binary location)")
+                        help="the output directory (default = binary location)")
     parser.add_argument("--sys-path", nargs="+",
-        help="a list of strings prepended to sys.path")
+                        help="a list of strings prepended to sys.path")
     parser.add_argument("--feature", nargs="+", choices=["snake_case", "true_property"], default=[],
-        help="""a list of feature names. Example: `--feature snake_case true_property`""")
+                        help="""a list of feature names. """
+                        """Example: `--feature snake_case true_property`. """
+                        """Currently not available for PyPy.""")
     options = parser.parse_args()
 
     qtest_env = os.environ.get("QTEST_ENVIRONMENT", "")
diff --git a/sources/pyside6/doc/tools/pyside-genpyi.rst b/sources/pyside6/doc/tools/pyside-genpyi.rst
new file mode 100644
index 000000000..0240c5005
--- /dev/null
+++ b/sources/pyside6/doc/tools/pyside-genpyi.rst
@@ -0,0 +1,52 @@
+.. _pyside6-genpyi:
+
+pyside6-genpyi
+==============
+
+`pyside6-genpyi` is a command line tool to generate Python stub files
+(.pyi) for PySide modules. Stub files define signatures of all classes,
+methods (including overloads), constants and enums of the PySide
+modules. Signatures also contain type hints. This helps PySide integrate
+with Python type checkers and IDEs. For example, if you use any function
+from the Qt API with PySide, your IDE's function lookup feature will
+show you the function signature and its parameters and return value
+including types.
+
+PySide6 already ships with stub files that were generated with
+`pyside6-genpyi`. However, if you want to generate new stub files for
+several (or all) modules, for example to toggle a few features, you can
+run `pyside6-genpyi` manually. If you want to generate stub files for
+your own custom module, refer to :ref:`shiboken6-genpyi`.
+
+
+Usage
+-----
+
+To generate stub files for a PySide module, run the following command:
+
+.. code-block:: bash
+
+    pyside6-genpyi <module_names> [OPTIONS]
+
+where `<module_names>` is a space-separated list of module names (the
+modules must be importable from the working directory) and where
+`[OPTIONS]` can be one of the following:
+
+* **--quiet**: Run the tool quietly without output to stdout.
+* **--outpath <output_dir>**: Specify the output directory for the
+  generated stub files. If not specified, the stub files are generated
+  in the location of the module binary.
+* **--sys-path <paths>**: Prepend the system path (`sys.path`) with a
+  space-separated list of strings `<paths>`. This is useful if the
+  module is not installed in a default lookup location.
+* **--feature <features>**: A space-separate list of optional PySide
+  features to enable (see :ref:`pysideapi2`). This option has no effect
+  when using PyPy. Currently, the following features are available:
+
+  * **snake_case**: All methods in the module are switched from
+    ``camelCase`` to ``snake_case``. A single upper case letter is
+    replaced by an underscore and the lower case letter.
+  * **true_property**: All getter and setter functions in the module
+    which are marked as a property in the Qt6 docs are replaced by Python
+    property objects. Properties are also listed as such in the according
+    QMetaObject of a class.