Add documentation to the plot example

Amends bce1bfb3af99aeb24259df34d662e8fcf072d3fd.

Task-number: PYSIDE-1605
Task-number: PYSIDE-1776
Change-Id: I28d081d718995e42c1b8fd5341d0ba59c5ed7ca0
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>

2 files changed, 36 insertions, 0 deletions

diff --git a/examples/widgets/painting/plot/doc/plot.png b/examples/widgets/painting/plot/doc/plot.png
new file mode 100644
index 000000000..e5031e351
--- /dev/null
+++ b/examples/widgets/painting/plot/doc/plot.png
diff --git a/examples/widgets/painting/plot/doc/plot.rst b/examples/widgets/painting/plot/doc/plot.rst
new file mode 100644
index 000000000..a63eaed87
--- /dev/null
+++ b/examples/widgets/painting/plot/doc/plot.rst
@@ -0,0 +1,36 @@
+Plot Example
+============
+
+The Plot example shows how to display a graph from data using an
+`opaque container <https://doc.qt.io/qtforpython-6/shiboken6/typesystem_containers.html>`_.
+
+It draws an sine graph using ``QPainter.drawPolyline()`` from a list of points.
+The list of points is continuously updated, as is the case for a example for a
+graph of an oscilloscope or medical patient monitor.
+In this case, it makes sense from a performance point of view to avoid the
+conversion of a Python list of data to a C++ list (``QList<QPoint>``)
+for each call to the plot function ``QPainter.drawPolyline()``.
+This is where opaque containers come into play.
+
+Instead of Python list of points, a ``QPointList`` is instantiated to store
+the data. ``QPointList`` is an opaque container wrapping a ``QList<QPoint>``.
+It can be passed to ``QPainter.drawPolyline()`` instead of a Python list of
+points.
+
+The type is declared in the entry for the ``QList`` container type in the
+type system file of the ``QtCore`` library:
+
+.. code-block:: xml
+
+    <container-type name="QList" type="list"
+                    opaque-containers="int:QIntList;QPoint:QPointList;QPointF:QPointFList">
+        ...
+    </container-type>
+
+In the ``shift()`` member function, new data are appended to the list while
+old data moving out of the visible window are removed from the front of the
+list.
+
+.. image:: plot.png
+   :width: 400
+   :alt: Plot Screenshot