docs: Propose new structure for API index

Change-Id: If2d96afbf93f153fb1b8e79f150a934620899d18
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

2 files changed, 59 insertions, 37 deletions

diff --git a/sources/pyside2/doc/api.rst b/sources/pyside2/doc/api.rst
index 2cc258c75..337d383b4 100644
--- a/sources/pyside2/doc/api.rst
+++ b/sources/pyside2/doc/api.rst
@@ -5,64 +5,86 @@
 
 Basic modules
 -------------
-  These are the main modules that will help you build a Widget based UI.
 
-  :mod:`Qt Core <PySide2.QtCore>`
-    Provides core non-GUI functionality, like signal and slots, properties, base classes of item models, serialization, etc.
-  :mod:`Qt GUI <PySide2.QtGui>`
-    Extends QtCore with GUI functionality: Events, windows and screens, OpenGL and raster-based 2D painting, images.
-  :mod:`Qt Widgets <PySide2.QtWidgets>`
-    Ready to use Widgets for your application, including also graphical elements for your UI.
+These are the main modules that help you build a Widget-based UI.
+
++---------------------------------------+--------------------------------------------------------+
+| :mod:`Qt Core <PySide2.QtCore>`       | Provides core non-GUI functionality, like signal and   |
+|                                       | slots, properties, base classes of item models,        |
+|                                       | serialization, and more.                               |
++---------------------------------------+--------------------------------------------------------+
+| :mod:`Qt GUI <PySide2.QtGui>`         | Extends QtCore with GUI functionality: Events, windows |
+|                                       | and screens, OpenGL and raster-based 2D painting, as   |
+|                                       | well as images.                                        |
++---------------------------------------+--------------------------------------------------------+
+| :mod:`Qt Widgets <PySide2.QtWidgets>` | Provides ready to use Widgets for your application,    |
+|                                       | including graphical elements for your UI.              |
++---------------------------------------+--------------------------------------------------------+
 
 QML and Qt Quick
 ----------------
-  If you want to use the `QML Language <https://doc.qt.io/qt-5.qmlapplications>`, these
-  modules will help you interact with it from Python.
 
-  :mod:`Qt QML <PySide2.QtQml>`
-    Base Python API to interact with the QML module.
-  :mod:`Qt Quick <PySide2.QtQuick>`
-    Provides classes for embedding Qt Quick in Qt applications.
-  :mod:`Qt QuickWidgets <PySide2.QtQuickWidgets>`
-    Provides the QQuickWidget class for embedding Qt Quick in widget-based applications.
+Use these modules to interact with the `QML Language <https://doc.qt.io/qt-5.qmlapplications>`,
+from Python.
+
++-------------------------------------------------+----------------------------------------------+
+| :mod:`Qt QML <PySide2.QtQml>`                   | The base Python API to interact with the     |
+|                                                 | module.                                      |
++-------------------------------------------------+----------------------------------------------+
+| :mod:`Qt Quick <PySide2.QtQuick>`               | Provides classes to embed Qt Quick in Qt     |
+|                                                 | applications.                                |
++-------------------------------------------------+----------------------------------------------+
+| :mod:`Qt QuickWidgets <PySide2.QtQuickWidgets>` | Provides the QQuickWidget class to embed Qt  |
+|                                                 | Quick in widget-based applications.          |
++-------------------------------------------------+----------------------------------------------+
 
 Data visualization
 ------------------
 
-  Charts and diagrams: these modules provide a large amount
-  of classes that can help you include these elements in your UI.
+Charts, diagrams, animations: these modules provide classes to help you include these elements in
+your UI.
 
-  :mod:`Qt Charts <PySide2.QtCharts>`
-    Provides a set of easy to use chart components.
-  :mod:`Qt DataVisualization <PySide2.QtDataVisualization>`
-    Provides a way to visualize data in 3D as bar, scatter, and surface graphs.
++------------------------------------------------------------+-----------------------------------+
+| :mod:`Qt Charts <PySide2.QtCharts>`                        | Provides a set of easy to use     |
+|                                                            | chart components.                 |
++------------------------------------------------------------+-----------------------------------+
+| :mod:`Qt DataVisualization <PySide2.QtDataVisualization>`  | Provides a way to visualize data  |
+|                                                            | in 3D as bar, scatter, or surface |
+|                                                            | graphs.                           |
++------------------------------------------------------------+-----------------------------------+
 
 Multimedia
 -----------
 
-  Audio, video, and hardware interaction: check these modules if you are
-  looking for multimedia solutions.
+Audio, video, and hardware interaction: use these modules for multimedia solutions.
 
-  :mod:`Qt Multimedia <PySide2.QtMultimedia>`
-    Provides low-level multimedia functionality.
-  :mod:`Qt MultimediaWidgets <PySide2.QtMultimediaWidgets>`
-    Provides the widget-based multimedia API.
++------------------------------------------------------------+-----------------------------------+
+| :mod:`Qt Multimedia <PySide2.QtMultimedia>`                | Provides low-level multimedia     |
+|                                                            | functionality.                    |
++------------------------------------------------------------+-----------------------------------+
+| :mod:`Qt MultimediaWidgets <PySide2.QtMultimediaWidgets>`  | Provides the widget-based         |
+|                                                            | multimedia API.                   |
++------------------------------------------------------------+-----------------------------------+
 
 WebEngine
 ---------
 
-  If your project is based on a browser or the features around web
-  based applications, these modules will help you to interact with them.
+If your project is based on a browser or the features around Web-based applications, use these
+modules to interact with them.
 
-  :mod:`Qt WebEngineWidgets <PySide2.QtWebEngineWidgets>`
-    Provides widgets that can handle web content.
-  :mod:`Qt WebChannel <PySide2.QtWebChannel>`
-    Enables peer-to-peer communication between a server and a client
-    (HTML/JavaScript or QML application).
++---------------------------------------------------------+--------------------------------------+
+| :mod:`Qt WebEngineWidgets <PySide2.QtWebEngineWidgets>` | Provides widgets to handle Web       |
+|                                                         | content.                             |
++---------------------------------------------------------+--------------------------------------+
+| :mod:`Qt WebChannel <PySide2.QtWebChannel>`             | Enables peer-to-peer communication   |
+|                                                         | between a server and a client        |
+|                                                         | (HTML/JavaScript or QML application).|
++---------------------------------------------------------+--------------------------------------+
 
 All the modules
 ---------------
 
-  Here is a complete list of modules supported by |pymodname|.
+There are many other modules currently supported by |pymodname|, here you can find a complete list
+of them.
 
-  :doc:`Modules <modules>`
+  :doc:`Check all the modules <modules>`
diff --git a/sources/pyside2/doc/index.rst b/sources/pyside2/doc/index.rst
index 93e3451c5..96cbf2ab2 100644
--- a/sources/pyside2/doc/index.rst
+++ b/sources/pyside2/doc/index.rst
@@ -2,7 +2,7 @@
 *********
 
 **Qt for Python** offers the official Python bindings for `Qt`_ (`PySide2`_),
-enabling the use of its APIs in Python applications, and a binding generator tool (`Shiboken2`_)
+so that you can use Qt5 APIs in your Python applications, and a binding generator tool (`Shiboken2`_)
 which can be used to expose C++ projects into Python.
 
 |project| is available under the LGPLv3/GPLv3 and the Qt commercial license.