Improve Porting documentation

Task-number: PYSIDE-1112
Task-number: PYSIDE-1482
Pick-to: 6.0
Change-Id: Ic65d86e2567849f26cb28c480937e7fb41ad5856
Reviewed-by: Cristian Maureira-Fredes <[email protected]>

1 files changed, 68 insertions, 6 deletions

diff --git a/sources/pyside6/doc/porting_from2.rst b/sources/pyside6/doc/porting_from2.rst
index 7b678f5cb..b94cada92 100644
--- a/sources/pyside6/doc/porting_from2.rst
+++ b/sources/pyside6/doc/porting_from2.rst
@@ -1,24 +1,53 @@
-Porting applications from PySide2 to PySide6
-********************************************
+Porting Applications from PySide2 to PySide6
+============================================
+
+Module Availability
+-------------------
 
 Qt for Python 6.0.0 initially ships with the essential
 `Modules <https://doc.qt.io/qt-6/qtmodules.html>`_ and some
-add-ons (Qt Concurrent, Qt Help, Qt OpenGL, Qt Print Support
+add-ons (Qt 3D, Qt Concurrent, Qt Help, Qt OpenGL, Qt Print Support
 Qt Quick Widgets, Qt SQL, Qt SVG, Qt UI Tools and Qt XML).
+
 More modules will follow in subsequent releases as they
 are added to Qt.
 
+For Qt for Python 6.1, Active Qt, Qt Charts, Qt Data Visualization,
+Qt StateMachine and Qt SCXML are planned.
+
+Module-Level Changes
+--------------------
+
+* *Qt Quick Controls 1* have been removed.
+* ``QStateMachine`` and related classes have been extracted to a new
+  *QtStateMachine* module.
+* ``QXmlReader`` and related classes (*SAX API*) have been removed.
+* The content of the *QtOpenGL* module has been replaced. The class
+  ``QGLWidget`` and related classes (``QGLContext``, ``QGLFunctions``,
+  ``QGLShaderProgram``) have been removed. Parts of the *Open GL*
+  functionality from *QtGui* have been extracted into this module, for example
+  ``QOpenGLBuffer`` and ``QOpenGLShaderProgram``.
+  There is a new module *QtOpenGLWidgets* which contains the class
+  ``QOpenGLWidget``, a replacement for ``QGLWidget``.
+
+As *Open GL*  is phasing out,
+`QRhi <https://doc.qt.io/qt-6/topics-graphics.html>`_ should be considered
+for graphics applications.
+
+Imports
+-------
+
 The first thing to do when porting applications is to replace the
 import statements:
 
-::
+.. code-block:: python
 
     from PySide2.QtWidgets import QApplication...
     from PySide2 import QtCore
 
 needs to be changed to:
 
-::
+.. code-block:: python
 
     from PySide6.QtWidgets import QApplication...
     from PySide6 import QtCore
@@ -27,7 +56,40 @@ needs to be changed to:
 Some classes are in a different module now, for example
 ``QAction`` and ``QShortcut`` have been moved from ``QtWidgets`` to ``QtGui``.
 
+For *Qt Charts* and *Qt Data Visualization*, the additional namespaces have been
+removed. It is now possible to use:
+
+.. code-block:: python
+
+    from PySide6.QtCharts import QChartView
+
+directly.
+
+
+Class/Function Deprecations
+---------------------------
+
 Then, the code base needs to be checked for usage of deprecated API and adapted
-accordingly. More information can be found in the
+accordingly. For example:
+
+ * The High DPI scaling attributes ``Qt.AA_EnableHighDpiScaling``,
+   ``Qt.AA_DisableHighDpiScaling`` and ``Qt.AA_UseHighDpiPixmaps`` are
+   deprecated. High DPI is by default enabled in Qt 6 and cannot be turned off.
+ * ``QDesktopWidget`` has been removed. ``QScreen`` should be used instead,
+   which can be retrieved using ``QWidget.screen()``,
+   ``QGuiApplication.primaryScreen()`` or ``QGuiApplication.screens()``.
+ * ``QFontMetrics.width()`` has been renamed to ``horizontalAdvance()``.
+ * ``QMouseEvent.pos()`` and ``QMouseEvent.globalPos()`` returning a ``QPoint``
+   are now deprecated. ``QMouseEvent.position()`` and
+   ``QMouseEvent.globalPosition()`` returning a ``QPointF`` should be used
+   instead.
+ * ``QOpenGLVersionFunctionsFactory.get()`` instead of
+   ``QOpenGLContext.versionFunctions()`` should be used to obtain
+   *Open GL* functions.
+ * ``QRegExp`` has been replaced by ``QRegularExpression``.
+ * ``QWidget.mapToGlobal()`` and ``QWidget.mapFromGlobal()`` now also accept
+   and return ``QPointF``.
+
+More information can be found in the
 `Porting to Qt 6 <https://doc.qt.io/qt-6/portingguide.html>`_ Guide
 and the `Qt 6.0 Documentation <https://doc.qt.io/qt-6/index.html>`_ .