Added docstrings to plot_grid, plot_histogram and plot_layout modules

Author: PierreRaybaut

doc/reference/index.rst

@@ -15,3 +15,7 @@ Main `python-qwt` classes:
     plot
     plot_canvas
     plot_curve
+    plot_directpainter
+    plot_grid
+    plot_histogram
+    plot_layout

doc/reference/plot_directpainter.rst

@@ -0,0 +1,2 @@
+.. automodule:: qwt.plot_directpainter
+   :members:

doc/reference/plot_grid.rst

@@ -0,0 +1,2 @@
+.. automodule:: qwt.plot_grid
+   :members:

doc/reference/plot_histogram.rst

@@ -0,0 +1,2 @@
+.. automodule:: qwt.plot_histogram
+   :members:

doc/reference/plot_layout.rst

@@ -0,0 +1,2 @@
+.. automodule:: qwt.plot_layout
+   :members:

qwt/plot_curve.py

@@ -195,7 +195,7 @@ class QwtPlotCurve(QwtPlotSeriesItem, QwtSeriesStore):
     
         Constructor
         
-        :param title: Parent plot widget
+        :param title: Curve title
         :type title: qwt.text.QwtText or str or None
     """
 

qwt/plot_directpainter.py

@@ -5,6 +5,14 @@
 # Copyright (c) 2015 Pierre Raybaut, for the Python translation/optimization
 # (see LICENSE file for more details)
 
+"""
+QwtPlotDirectPainter
+--------------------
+
+.. autoclass:: QwtPlotDirectPainter
+   :members:
+"""
+
 from qwt.qt.QtGui import QPainter, QRegion
 from qwt.qt.QtCore import QObject, QT_VERSION, Qt, QEvent
 
@@ -39,6 +47,51 @@ def __init__(self):
 
 
 class QwtPlotDirectPainter(QObject):
+    """
+    Painter object trying to paint incrementally
+
+    Often applications want to display samples while they are
+    collected. When there are too many samples complete replots
+    will be expensive to be processed in a collection cycle.
+
+    `QwtPlotDirectPainter` offers an API to paint
+    subsets (f.e all additions points) without erasing/repainting
+    the plot canvas.
+
+    On certain environments it might be important to calculate a proper
+    clip region before painting. F.e. for Qt Embedded only the clipped part
+    of the backing store will be copied to a (maybe unaccelerated) 
+    frame buffer.
+
+    .. warning::
+    
+        Incremental painting will only help when no replot is triggered
+        by another operation (like changing scales) and nothing needs
+        to be erased.
+        
+    Paint attributes:
+    
+      * `QwtPlotDirectPainter.AtomicPainter`:
+      
+        Initializing a `QPainter` is an expensive operation.
+        When `AtomicPainter` is set each call of `drawSeries()` opens/closes
+        a temporary `QPainter`. Otherwise `QwtPlotDirectPainter` tries to
+        use the same `QPainter` as long as possible.
+
+      * `QwtPlotDirectPainter.FullRepaint`:
+      
+        When `FullRepaint` is set the plot canvas is explicitly repainted
+        after the samples have been rendered.
+
+      * `QwtPlotDirectPainter.CopyBackingStore`:
+      
+        When `QwtPlotCanvas.BackingStore` is enabled the painter
+        has to paint to the backing store and the widget. In certain 
+        situations/environments it might be faster to paint to 
+        the backing store only and then copy the backing store to the canvas.
+        This flag can also be useful for settings, where Qt fills the
+        the clip region with the widget background.
+    """
 
     # enum Attribute
     AtomicPainter = 0x01
@@ -50,6 +103,16 @@ def __init__(self, parent=None):
         self.__data = QwtPlotDirectPainter_PrivateData()
 
     def setAttribute(self, attribute, on=True):
+        """
+        Change an attribute
+        
+        :param int attribute: Attribute to change
+        :param bool on: On/Off
+
+        .. seealso::
+
+            :py:meth:`testAttribute()`
+        """
         if self.testAttribute(attribute) != on:
             self.__data.attributes |= attribute
         else:
@@ -58,29 +121,86 @@ def setAttribute(self, attribute, on=True):
             self.reset()
 
     def testAttribute(self, attribute):
+        """
+        :param int attribute: Attribute to be tested
+        :return: True, when attribute is enabled
+
+        .. seealso::
+
+            :py:meth:`setAttribute()`
+        """
         return self.__data.attributes & attribute
 
     def setClipping(self, enable):
+        """
+        En/Disables clipping
+            
+        :param bool enable: Enables clipping is true, disable it otherwise
+        
+        .. seealso::
+        
+            :py:meth:`hasClipping()`, :py:meth:`clipRegion()`, 
+            :py:meth:`setClipRegion()`
+        """
         self.__data.hasClipping = enable
 
     def hasClipping(self):
+        """
+        :return: Return true, when clipping is enabled
+        
+        .. seealso::
+        
+            :py:meth:`setClipping()`, :py:meth:`clipRegion()`, 
+            :py:meth:`setClipRegion()`
+        """
         return self.__data.hasClipping
 
     def setClipRegion(self, region):
+        """
+        Assign a clip region and enable clipping
+
+        Depending on the environment setting a proper clip region might 
+        improve the performance heavily. F.e. on Qt embedded only the clipped 
+        part of the backing store will be copied to a (maybe unaccelerated) 
+        frame buffer device.
+        
+        :param QRegion region: Clip region
+        
+        .. seealso::
+        
+            :py:meth:`hasClipping()`, :py:meth:`setClipping()`, 
+            :py:meth:`clipRegion()`
+        """
         self.__data.clipRegion = region
         self.__data.hasClipping = True
 
     def clipRegion(self):
+        """
+        :return: Return Currently set clip region.
+        
+        .. seealso::
+        
+            :py:meth:`hasClipping()`, :py:meth:`setClipping()`, 
+            :py:meth:`setClipRegion()`
+        """
         return self.__data.clipRegion
 
     def drawSeries(self, seriesItem, from_, to):
-        """When observing an measurement while it is running, new points have 
+        """
+        Draw a set of points of a seriesItem.
+        
+        When observing a measurement while it is running, new points have 
         to be added to an existing seriesItem. drawSeries() can be used to 
         display them avoiding a complete redraw of the canvas.
 
-        Setting plot().canvas().setAttribute(Qt.WA_PaintOutsidePaintEvent, True)
+        Setting `plot().canvas().setAttribute(Qt.WA_PaintOutsidePaintEvent, True)`
         will result in faster painting, if the paint engine of the canvas widget
-        supports this feature."""
+        supports this feature.
+        
+        :param qwt.plot_seriesitem.QwtPlotSeriesItem seriesItem: Item to be painted
+        :param int from_: Index of the first point to be painted
+        :param int to: Index of the last point to be painted. If to < 0 the series will be painted to its last point.
+        """
         if seriesItem is None or seriesItem.plot() is None:
             return
         canvas = seriesItem.plot().canvas()
@@ -129,6 +249,7 @@ def drawSeries(self, seriesItem, from_, to):
             self.__data.seriesItem = None
 
     def reset(self):
+        """Close the internal QPainter"""
         if self.__data.painter.isActive():
             w = self.__data.painter.device()  #XXX: cast to QWidget
             if w: