Merge pull request #1527 from ixjlyons/improve-parameter-docs

Improve parametertree documentation coverage

doc/source/apireference.rst

@@ -12,7 +12,7 @@ Contents:
     widgets/index
     3dgraphics/index
     colormap
-    parametertree/index
+    parametertree/apiref
     dockarea
     graphicsscene/index
     flowchart/index

doc/source/parametertree/index.rst

@@ -3,17 +3,22 @@
 Parameter Trees
 ===============
 
+.. currentmodule:: pyqtgraph.parametertree
+
 Parameter trees are a system for handling hierarchies of parameters while automatically generating one or more GUIs to display and interact with the parameters.
 This feature is commonly seen, for example, in user interface design applications which display a list of editable properties for each widget.
-Parameters generally have a name, a data type (int, float, string, color, etc), and a value matching the data type. Parameters may be grouped and nested
+Parameters generally have a name, a data type (int, float, string, color, etc), and a value matching the data type. Parameters may be grouped and nested to form hierarchies and may be subclassed to provide custom behavior and display widgets.
-to form hierarchies and may be subclassed to provide custom behavior and display widgets.
 
-PyQtGraph's parameter tree system works similarly to the model-view architecture used by some components of Qt: Parameters are purely data-handling classes
+PyQtGraph's parameter tree system works similarly to the model-view architecture used by some components of Qt:
-that exist independent of any graphical interface. A ParameterTree is a widget that automatically generates a graphical interface which represents
-the state of a haierarchy of Parameter objects and allows the user to edit the values within that hierarchy. This separation of data (model) and graphical
-interface (view) allows the same data to be represented multiple times and in a variety of different ways. 
 
-For more information, see the 'parametertree' example included with pyqtgraph and the API reference
+- A :class:`Parameter` is a purely data-handling class that exists independent of any graphical interface.
+- A :class:`ParameterItem` is an interactive graphical representation of a :class:`Parameter`.
+- A :class:`ParameterTree` is a widget that automatically generates a graphical interface which represents the state of a hierarchy of Parameter objects and allows the user to edit the values within that hierarchy.
+
+This separation of data (model) and graphical interface (view) allows the same data to be represented multiple times and in a variety of different ways.
+For example, a floating point number parameter could be represented by a slider or a spinbox, or both.
+
+For more information, see the 'parametertree' example included with pyqtgraph and the API reference:
 
 .. toctree::
     :maxdepth: 2

doc/source/parametertree/parameter.rst

@@ -1,8 +1,9 @@
 Parameter
 =========
 
+.. autofunction:: pyqtgraph.parametertree.registerParameterType
+
 .. autoclass:: pyqtgraph.parametertree.Parameter
     :members:
 
     .. automethod:: pyqtgraph.parametertree.Parameter.__init__
-

doc/source/parametertree/parametertypes.rst

@@ -1,6 +1,40 @@
 Built-in Parameter Types
 ========================
 
-.. automodule:: pyqtgraph.parametertree.parameterTypes
+.. currentmodule:: pyqtgraph.parametertree.parameterTypes
+
+Parameters
+----------
+
+.. autoclass:: SimpleParameter
    :members:
 
+.. autoclass:: GroupParameter
+   :members:
+
+.. autoclass:: ListParameter
+   :members:
+
+.. autoclass:: TextParameter
+   :members:
+
+.. autoclass:: ActionParameter
+   :members:
+
+ParameterItems
+--------------
+
+.. autoclass:: WidgetParameterItem
+   :members:
+
+.. autoclass:: GroupParameterItem
+   :members:
+
+.. autoclass:: ListParameterItem
+   :members:
+
+.. autoclass:: TextParameterItem
+   :members:
+
+.. autoclass:: ActionParameterItem
+   :members:

pyqtgraph/parametertree/Parameter.py

@@ -9,6 +9,11 @@ PARAM_TYPES = {}
 PARAM_NAMES = {}
 
 def registerParameterType(name, cls, override=False):
+    """Register a parameter type in the parametertree system.
+
+    This enables construction of custom Parameter classes by name in
+    :meth:`~pyqtgraph.parametertree.Parameter.create`.
+    """
     global PARAM_TYPES
     if name in PARAM_TYPES and not override:
         raise Exception("Parameter type '%s' already exists (use override=True to replace)" % name)

pyqtgraph/parametertree/parameterTypes.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 from ..Qt import QtCore, QtGui
 from ..python2_3 import asUnicode
 from .Parameter import Parameter, registerParameterType
@@ -303,9 +304,27 @@ class EventProxy(QtCore.QObject):
 
 
 class SimpleParameter(Parameter):
+    """Parameter representing a single value.
+
+    This parameter is backed by :class:`WidgetParameterItem` to represent the
+    following parameter names:
+
+    - 'int'
+    - 'float'
+    - 'bool'
+    - 'str'
+    - 'color'
+    - 'colormap'
+    """
     itemClass = WidgetParameterItem
 
     def __init__(self, *args, **kargs):
+        """Initialize the parameter.
+
+        This is normally called implicitly through :meth:`Parameter.create`.
+        The keyword arguments avaialble to :meth:`Parameter.__init__` are
+        applicable.
+        """
         Parameter.__init__(self, *args, **kargs)
         
         ## override a few methods for color parameters
@@ -547,6 +566,21 @@ class ListParameterItem(WidgetParameterItem):
 
 
 class ListParameter(Parameter):
+    """Parameter with a list of acceptable values.
+
+    By default, this parameter is represtented by a :class:`ListParameterItem`,
+    displaying a combo box to select a value from the list.
+
+    In addition to the generic :class:`~pyqtgraph.parametertree.Parameter`
+    options, this parameter type accepts a ``limits`` argument specifying the
+    list of allowed values.  ``values`` is an alias and may be used instead.
+
+    The values may generally be of any data type, as long as they can be
+    represented as a string. If the string representation provided is
+    undesirable, the values may be given as a dictionary mapping the desired
+    string representation to the value.
+    """
+
     itemClass = ListParameterItem
 
     def __init__(self, **opts):
@@ -562,6 +596,7 @@ class ListParameter(Parameter):
         self.setLimits(opts['limits'])
         
     def setLimits(self, limits):
+        """Change the list of allowed values."""
         self.forward, self.reverse = self.mapping(limits)
         
         Parameter.setLimits(self, limits)
@@ -591,6 +626,7 @@ registerParameterType('list', ListParameter, override=True)
 
 
 class ActionParameterItem(ParameterItem):
+    """ParameterItem displaying a clickable button."""
     def __init__(self, param, depth):
         ParameterItem.__init__(self, param, depth)
         self.layoutWidget = QtGui.QWidget()
@@ -620,7 +656,10 @@ class ActionParameterItem(ParameterItem):
         self.param.activate()
         
 class ActionParameter(Parameter):
-    """Used for displaying a button within the tree."""
+    """Used for displaying a button within the tree.
+
+    ``sigActivated(self)`` is emitted when the button is clicked.
+    """
     itemClass = ActionParameterItem
     sigActivated = QtCore.Signal(object)
     
@@ -632,6 +671,7 @@ registerParameterType('action', ActionParameter, override=True)
 
 
 class TextParameterItem(WidgetParameterItem):
+    """ParameterItem displaying a QTextEdit widget."""
     def __init__(self, param, depth):
         WidgetParameterItem.__init__(self, param, depth)
         self.hideWidget = False
@@ -663,7 +703,7 @@ class TextParameterItem(WidgetParameterItem):
         return self.textBox
         
 class TextParameter(Parameter):
-    """Editable string; displayed as large text box in the tree."""
+    """Editable string, displayed as large text box in the tree."""
     itemClass = TextParameterItem