doc: add package detail page

To clarify the content of the packages, dependencies,
and tools that we include in the wheels.

Other files were modified to link the new page.

Task-number: PYSIDE-1112
Change-Id: I358c47601e2b930b12807dda41382474186baf01
Reviewed-by: Christian Tismer <tismer@stackless.com>
(cherry picked from commit 52d38437445f6aa979875a93702496f800b98d63)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 151 insertions, 4 deletions

diff --git a/sources/pyside6/doc/index.rst b/sources/pyside6/doc/index.rst
index 10b878d9b..c866e5f1d 100644
--- a/sources/pyside6/doc/index.rst
+++ b/sources/pyside6/doc/index.rst
@@ -3,8 +3,9 @@
 
 .. ifconfig:: output_format == 'html'
 
-    **Qt for Python** offers the official Python bindings for `Qt`_, and
-    has two main components:
+    **Qt for Python** offers the official Python bindings for `Qt`_,
+    which enables you to use Python to write your Qt applications.
+    The project has two main components:
 
     * `PySide6`_, so that you can use Qt6 APIs in your Python applications, and
     * `Shiboken6 <shiboken6/index.html>`__, a binding generator tool, which can
@@ -13,8 +14,9 @@
 
 .. ifconfig:: output_format == 'qthelp'
 
-    **Qt for Python** offers the official Python bindings for `Qt`_, and
-    has two main components:
+    **Qt for Python** offers the official Python bindings for `Qt`_,
+    which enables you to use Python to write your Qt applications.
+    The project has two main components:
 
     * `PySide6`_, so that you can use Qt6 APIs in your Python applications, and
     * `Shiboken6 <../shiboken6/index.html>`__, a binding generator tool, which can
@@ -31,7 +33,20 @@ This project is available under the LGPLv3/GPLv3 and the `Qt commercial license`
 .. _`Qt commercial license`: https://www.qt.io/licensing/
 .. _`Porting from PySide2 to PySide6`: porting_from2.html
 
+Quick Start
+===========
 
+You can obtain the latest stable version by running ``pip install pyside6``.
+If you want to build it yourself, check the `getting started guide`_.
+
+To learn how to use it, check out `write your first application`_,
+and to learn what is installed with the ``pyside6``, check the
+`package content, structure, and tools`_ page.
+
+
+.. _`getting started guide`: gettingstarted.html
+.. _`write your first application`: quickstart.html
+.. _`package content, structure, and tools`: package_details.html
 
 Documentation
 =============
diff --git a/sources/pyside6/doc/package_details.rst b/sources/pyside6/doc/package_details.rst
new file mode 100644
index 000000000..3fd3d86f7
--- /dev/null
+++ b/sources/pyside6/doc/package_details.rst
@@ -0,0 +1,129 @@
+.. _package_details:
+
+Package Details
+===============
+
+Having a large project as the Qt Framework available from one simple
+installation line::
+  pip install pyside6
+is really beneficial,
+but it might be confusing to newcomers.
+
+Besides your IDE, you don't need to install anything else to develop your
+Qt application, because the same command installs many tools
+that will help you design UIs, use QML types, generate
+files automatically, translate applications, etc.
+
+Package Dependencies
+--------------------
+
+.. image:: packages.png
+   :width: 400
+   :alt: Packages structure and dependency
+
+Starting from 6.3.0, the ``pyside6`` package (wheel) is almost empty,
+and only includes references to other packages that are required
+to properly use all the modules.
+This packages are:
+
+* ``pyside6-essentials``, `essential Qt modules <https://pypi.org/project/PySide6-Essentials/>`_,
+* ``pyside6-addons``, `additional Qt modules <https://pypi.org/project/PySide6-Addons/>`_,
+* ``shiboken6``, a utility Python module.
+
+You can verify this by running ``pip list`` to check the installed
+packages in your Python (virtual) environment::
+
+  (env) % pip list
+  Package            Version
+  ------------------ -------
+  pip                22.0.4
+  PySide6            6.3.0
+  PySide6-Addons     6.3.0
+  PySide6-Essentials 6.3.0
+  setuptools         58.1.0
+  shiboken6          6.3.0
+
+Both ``pyside6-essentials`` and ``pyside6-addons`` contain Qt binaries
+(``.so``, ``.dll``, or ``.dylib``) that are used by the Python wrappers
+that enable you to use the Qt modules from Python.
+For example, in the ``QtCore`` module, you will find
+on Linux:
+
+* ``PySide6/QtCore.abi3.so``, and
+* ``PySide6/Qt/lib/libQt6Core.so.6``
+
+inside the ``site-packages`` directory of your (virtual) environment.
+The first is the *importable* module which depends on the second file
+which is the original QtCore library.
+
+.. note:: The package ``shiboken6-generator`` is not a dependency,
+   and it's not available on PyPi. The reason, is that it depends on
+   ``libclang``, which is a large library that we don't package, and
+   requires a special configuration for you to use. Check the `Shiboken
+   Documentation`_ for more details.
+
+..
+  Adding the full URL because it's a different sphinx project.
+.. _`Shiboken Documentation`: https://doc.qt.io/qtforpython/shiboken6/gettingstarted.html
+
+Tools Included
+--------------
+
+Following the same idea from the modules, we also include in the packages
+(wheels) Qt tools that are important for any Qt application development
+workflow, like ``uic``, ``rcc``, etc.
+
+All the tools **must** be used from the PySide wrappers, and not directly.
+For example, if exploring the ``site-packages/`` directory on your installation
+you find ``uic.exe`` (on Windows), you should not click on that, and use
+``pyside6-uic.exe`` instead.
+The reason for this is the proper setup of PATHs, plugins, and more,
+to properly work with the installed Python package.
+
+Here you can find all the tools we include in |project| starting
+from 6.3.0, grouped by different topics:
+
+Project development
+~~~~~~~~~~~~~~~~~~~
+
+* ``pyside6-project``, to build Qt Designer forms (``.ui`` files),
+  resource files (``.qrc``) and QML type files (``.qmltype``) from
+  a ``.pyproject`` file.
+
+Widget Development
+~~~~~~~~~~~~~~~~~~
+
+* ``pyside6-designer``, drag-and-drop tool for designing Widget UIs (generates ``.ui`` files).
+* ``pyside6-uic``, to generate Python code from ``.ui`` form files.
+* ``pyside6-rcc``, to generate serialized data from ``.qrc`` resources files.
+  Keep in mind these files can be used in other non-widget projects.
+
+QML Development
+~~~~~~~~~~~~~~~
+
+* ``pyside6-qmllint``, that verifies the syntactic validity of QML files.
+* ``pyside6-qmltyperegistrar``, to read metatypes files and generate
+  files that contain the necessary code to register all the types marked with
+  relevant macros.
+
+Translations
+~~~~~~~~~~~~
+
+* ``pyside6-linguist``, for translating text in applications.
+* ``pyside6-lrelease``, to create run-time translation files for the application.
+* ``pyside6-lupdate``, to synchronize source code and translations.
+
+Qt Help
+~~~~~~~
+
+* ``pyside6-assistant``, for viewing online documentation in Qt Help file format.
+  Read more about the formats on the `QtHelp Framework`_ page.
+
+.. _`QtHelp Framework`: https://doc.qt.io/qt-6/qthelp-framework.html
+
+PySide Utilities
+~~~~~~~~~~~~~~~~
+
+* ``pyside6-genpyi``, to generate Python stubs (``.pyi`` files) for Qt modules.
+* ``pyside6-metaobjectdump``, a tool to print out the metatype information in
+  JSON to be used as input for ``qmltyperegistrar``.
diff --git a/sources/pyside6/doc/packages.png b/sources/pyside6/doc/packages.png
new file mode 100644
index 000000000..57e7ca47d
--- /dev/null
+++ b/sources/pyside6/doc/packages.png
diff --git a/sources/pyside6/doc/quickstart.rst b/sources/pyside6/doc/quickstart.rst
index babbab82e..5d1053455 100644
--- a/sources/pyside6/doc/quickstart.rst
+++ b/sources/pyside6/doc/quickstart.rst
@@ -53,6 +53,9 @@ Installation
     # Prints the Qt version used to compile PySide6
     print(PySide6.QtCore.__version__)
 
+.. note:: For more information about what's included in the ``pyside6``
+   package, check :ref:`package_details`.
+
 Create a Simple Application
 ---------------------------