From db67a256a925c5a2811b74d537d39bce201b4251 Mon Sep 17 00:00:00 2001 From: Kenneth Lyons Date: Fri, 3 Apr 2020 10:06:25 -0700 Subject: [PATCH] Miscellaneous doc fixups (#1142) * Miscellaneous doc cleanup * Moved dockarea up a level (like flowchart, parametertree). Removed extraneous parametertree doc --- doc/source/apireference.rst | 2 + doc/source/conf.py | 3 +- doc/source/dockarea.rst | 11 ++ doc/source/graphicsItems/index.rst | 2 +- doc/source/graphicswindow.rst | 20 ++-- doc/source/installation.rst | 107 +++++++++++--------- doc/source/plotting.rst | 4 +- doc/source/widgets/dockarea.rst | 5 - doc/source/widgets/index.rst | 2 - doc/source/widgets/parametertree.rst | 5 - pyqtgraph/flowchart/Flowchart.py | 3 +- pyqtgraph/functions.py | 11 +- pyqtgraph/graphicsItems/AxisItem.py | 4 +- pyqtgraph/graphicsItems/HistogramLUTItem.py | 31 +++--- pyqtgraph/graphicsItems/InfiniteLine.py | 4 +- pyqtgraph/graphicsItems/LinearRegionItem.py | 21 ++-- pyqtgraph/graphicsItems/PlotDataItem.py | 37 ++++--- pyqtgraph/graphicsWindows.py | 11 +- pyqtgraph/widgets/GraphicsLayoutWidget.py | 30 +++--- 19 files changed, 169 insertions(+), 144 deletions(-) create mode 100644 doc/source/dockarea.rst delete mode 100644 doc/source/widgets/dockarea.rst delete mode 100644 doc/source/widgets/parametertree.rst diff --git a/doc/source/apireference.rst b/doc/source/apireference.rst index c4dc64aa..c52c8df1 100644 --- a/doc/source/apireference.rst +++ b/doc/source/apireference.rst @@ -13,5 +13,7 @@ Contents: 3dgraphics/index colormap parametertree/index + dockarea graphicsscene/index flowchart/index + graphicswindow diff --git a/doc/source/conf.py b/doc/source/conf.py index 3ec48f75..dd5e0718 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -93,7 +93,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -216,4 +216,3 @@ man_pages = [ ('index', 'pyqtgraph', 'pyqtgraph Documentation', ['Luke Campagnola'], 1) ] - diff --git a/doc/source/dockarea.rst b/doc/source/dockarea.rst new file mode 100644 index 00000000..384581d3 --- /dev/null +++ b/doc/source/dockarea.rst @@ -0,0 +1,11 @@ +Dock Area Module +================ + +.. automodule:: pyqtgraph.dockarea + :members: + +.. autoclass:: pyqtgraph.dockarea.DockArea + :members: + +.. autoclass:: pyqtgraph.dockarea.Dock + :members: diff --git a/doc/source/graphicsItems/index.rst b/doc/source/graphicsItems/index.rst index 7042d27e..eec86610 100644 --- a/doc/source/graphicsItems/index.rst +++ b/doc/source/graphicsItems/index.rst @@ -24,6 +24,7 @@ Contents: axisitem textitem errorbaritem + bargraphitem arrowitem fillbetweenitem curvepoint @@ -42,4 +43,3 @@ Contents: graphicsitem uigraphicsitem graphicswidgetanchor - diff --git a/doc/source/graphicswindow.rst b/doc/source/graphicswindow.rst index 3d5641c3..0602ae7e 100644 --- a/doc/source/graphicswindow.rst +++ b/doc/source/graphicswindow.rst @@ -1,8 +1,16 @@ -Basic display widgets -===================== +Deprecated Window Classes +========================= - - GraphicsWindow - - GraphicsView - - GraphicsLayoutItem - - ViewBox +.. automodule:: pyqtgraph.graphicsWindows +.. autoclass:: pyqtgraph.GraphicsWindow + :members: + +.. autoclass:: pyqtgraph.TabWindow + :members: + +.. autoclass:: pyqtgraph.PlotWindow + :members: + +.. autoclass:: pyqtgraph.ImageWindow + :members: diff --git a/doc/source/installation.rst b/doc/source/installation.rst index e3e1f1fc..fd9f5288 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,55 +1,70 @@ Installation ============ -There are many different ways to install pyqtgraph, depending on your needs: - -* The most common way to install pyqtgraph is with pip:: - - $ pip install pyqtgraph - - Some users may need to call ``pip3`` instead. This method should work on - all platforms. -* To get access to the very latest features and bugfixes you have three choice:: - - 1. Clone pyqtgraph from github:: - - $ git clone https://github.com/pyqtgraph/pyqtgraph - - Now you can install pyqtgraph from the source:: - - $ python setup.py install - - 2. Directly install from GitHub repo:: - - $ pip install git+git://github.com/pyqtgraph/pyqtgraph.git@develop - - You can change to ``develop`` of the above command to the branch - name or the commit you prefer. - - 3. - You can simply place the pyqtgraph folder someplace importable, such as - inside the root of another project. PyQtGraph does not need to be "built" or - compiled in any way. - -* Packages for pyqtgraph are also available in a few other forms: - - * **Anaconda**: ``conda install pyqtgraph`` - * **Debian, Ubuntu, and similar Linux:** Use ``apt install python-pyqtgraph`` or - download the .deb file linked at the top of the pyqtgraph web page. - * **Arch Linux:** has packages (thanks windel). (https://aur.archlinux.org/packages.php?ID=62577) - * **Windows:** Download and run the .exe installer file linked at the top of the pyqtgraph web page. - - -Requirements -============ - PyQtGraph depends on: - + * Python 2.7 or Python 3.x * A Qt library such as PyQt4, PyQt5, PySide, or PySide2 * numpy -The easiest way to meet these dependencies is with ``pip`` or with a scientific python -distribution like Anaconda. +The easiest way to meet these dependencies is with ``pip`` or with a scientific +python distribution like Anaconda. -.. _pyqtgraph: http://www.pyqtgraph.org/ +There are many different ways to install pyqtgraph, depending on your needs: + +pip +--- + +The most common way to install pyqtgraph is with pip:: + + $ pip install pyqtgraph + +Some users may need to call ``pip3`` instead. This method should work on all +platforms. + +conda +----- + +pyqtgraph is on the default Anaconda channel:: + + $ conda install pyqtgraph + +It is also available in the conda-forge channel:: + + $ conda install -c conda-forge pyqtgraph + +From Source +----------- + +To get access to the very latest features and bugfixes you have three choices: + +1. Clone pyqtgraph from github:: + + $ git clone https://github.com/pyqtgraph/pyqtgraph + $ cd pyqtgraph + + Now you can install pyqtgraph from the source:: + + $ pip install . + +2. Directly install from GitHub repo:: + + $ pip install git+git://github.com/pyqtgraph/pyqtgraph.git@develop + + You can change ``develop`` of the above command to the branch name or the + commit you prefer. + +3. You can simply place the pyqtgraph folder someplace importable, such as + inside the root of another project. PyQtGraph does not need to be "built" or + compiled in any way. + +Other Packages +-------------- + +Packages for pyqtgraph are also available in a few other forms: + +* **Debian, Ubuntu, and similar Linux:** Use ``apt install python-pyqtgraph`` or + download the .deb file linked at the top of the pyqtgraph web page. +* **Arch Linux:** https://www.archlinux.org/packages/community/any/python-pyqtgraph/ +* **Windows:** Download and run the .exe installer file linked at the top of the + pyqtgraph web page: http://pyqtgraph.org diff --git a/doc/source/plotting.rst b/doc/source/plotting.rst index 8a99663a..956f5b97 100644 --- a/doc/source/plotting.rst +++ b/doc/source/plotting.rst @@ -41,7 +41,7 @@ There are several classes invloved in displaying plot data. Most of these classe * :class:`AxisItem ` - Displays axis values, ticks, and labels. Most commonly used with PlotItem. * Container Classes (subclasses of QWidget; may be embedded in PyQt GUIs) * :class:`PlotWidget ` - A subclass of GraphicsView with a single PlotItem displayed. Most of the methods provided by PlotItem are also available through PlotWidget. - * :class:`GraphicsLayoutWidget ` - QWidget subclass displaying a single GraphicsLayoutItem. Most of the methods provided by GraphicsLayoutItem are also available through GraphicsLayoutWidget. + * :class:`GraphicsLayoutWidget ` - QWidget subclass displaying a single :class:`~pyqtgraph.GraphicsLayout`. Most of the methods provided by :class:`~pyqtgraph.GraphicsLayout` are also available through GraphicsLayoutWidget. .. image:: images/plottingClasses.png @@ -69,5 +69,3 @@ Create/show a plot widget, display three data curves:: for i in range(3): plotWidget.plot(x, y[i], pen=(i,3)) ## setting pen=(i,3) automaticaly creates three different-colored pens - - diff --git a/doc/source/widgets/dockarea.rst b/doc/source/widgets/dockarea.rst deleted file mode 100644 index 09a6acca..00000000 --- a/doc/source/widgets/dockarea.rst +++ /dev/null @@ -1,5 +0,0 @@ -dockarea module -=============== - -.. automodule:: pyqtgraph.dockarea - :members: diff --git a/doc/source/widgets/index.rst b/doc/source/widgets/index.rst index 9cfbc0c4..e5acb7f0 100644 --- a/doc/source/widgets/index.rst +++ b/doc/source/widgets/index.rst @@ -12,11 +12,9 @@ Contents: plotwidget imageview - dockarea spinbox gradientwidget histogramlutwidget - parametertree consolewidget colormapwidget scatterplotwidget diff --git a/doc/source/widgets/parametertree.rst b/doc/source/widgets/parametertree.rst deleted file mode 100644 index 565b930b..00000000 --- a/doc/source/widgets/parametertree.rst +++ /dev/null @@ -1,5 +0,0 @@ -parametertree module -==================== - -.. automodule:: pyqtgraph.parametertree - :members: diff --git a/pyqtgraph/flowchart/Flowchart.py b/pyqtgraph/flowchart/Flowchart.py index 2e7ed0eb..e269c62f 100644 --- a/pyqtgraph/flowchart/Flowchart.py +++ b/pyqtgraph/flowchart/Flowchart.py @@ -508,7 +508,7 @@ class Flowchart(Node): self.sigStateChanged.emit() def loadFile(self, fileName=None, startDir=None): - """Load a flowchart (*.fc) file. + """Load a flowchart (``*.fc``) file. """ if fileName is None: if startDir is None: @@ -938,4 +938,3 @@ class FlowchartWidget(dockarea.DockArea): class FlowchartNode(Node): pass - diff --git a/pyqtgraph/functions.py b/pyqtgraph/functions.py index 45e9aad6..8e1de665 100644 --- a/pyqtgraph/functions.py +++ b/pyqtgraph/functions.py @@ -934,10 +934,12 @@ def solveBilinearTransform(points1, points2): return matrix def rescaleData(data, scale, offset, dtype=None, clip=None): - """Return data rescaled and optionally cast to a new dtype:: - + """Return data rescaled and optionally cast to a new dtype. + + The scaling operation is:: + data => (data-offset) * scale - + """ if dtype is None: dtype = data.dtype @@ -2503,6 +2505,3 @@ class SignalBlock(object): def __exit__(self, *args): if self.reconnect: self.signal.connect(self.slot) - - - diff --git a/pyqtgraph/graphicsItems/AxisItem.py b/pyqtgraph/graphicsItems/AxisItem.py index 2601ecae..6b2c63df 100644 --- a/pyqtgraph/graphicsItems/AxisItem.py +++ b/pyqtgraph/graphicsItems/AxisItem.py @@ -36,7 +36,7 @@ class AxisItem(GraphicsWidget): without any scaling prefix (eg, 'V' instead of 'mV'). The scaling prefix will be automatically prepended based on the range of data displayed. - **args All extra keyword arguments become CSS style options for + args All extra keyword arguments become CSS style options for the tag which will surround the axis label and units. ============== =============================================================== """ @@ -256,7 +256,7 @@ class AxisItem(GraphicsWidget): without any scaling prefix (eg, 'V' instead of 'mV'). The scaling prefix will be automatically prepended based on the range of data displayed. - **args All extra keyword arguments become CSS style options for + args All extra keyword arguments become CSS style options for the tag which will surround the axis label and units. ============== ============================================================= diff --git a/pyqtgraph/graphicsItems/HistogramLUTItem.py b/pyqtgraph/graphicsItems/HistogramLUTItem.py index 687c2e3f..ad39b60e 100644 --- a/pyqtgraph/graphicsItems/HistogramLUTItem.py +++ b/pyqtgraph/graphicsItems/HistogramLUTItem.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- """ GraphicsWidget displaying an image histogram along with gradient editor. Can be used to adjust the appearance of images. """ @@ -32,22 +33,20 @@ class HistogramLUTItem(GraphicsWidget): - Movable region over histogram to select black/white levels - Gradient editor to define color lookup table for single-channel images - Parameters - ---------- - image : ImageItem or None - If *image* is provided, then the control will be automatically linked to - the image and changes to the control will be immediately reflected in - the image's appearance. - fillHistogram : bool - By default, the histogram is rendered with a fill. - For performance, set *fillHistogram* = False. - rgbHistogram : bool - Sets whether the histogram is computed once over all channels of the - image, or once per channel. - levelMode : 'mono' or 'rgba' - If 'mono', then only a single set of black/whilte level lines is drawn, - and the levels apply to all channels in the image. If 'rgba', then one - set of levels is drawn for each channel. + ================ =========================================================== + image (:class:`~pyqtgraph.ImageItem` or ``None``) If *image* is + provided, then the control will be automatically linked to + the image and changes to the control will be immediately + reflected in the image's appearance. + fillHistogram (bool) By default, the histogram is rendered with a fill. + For performance, set ``fillHistogram=False`` + rgbHistogram (bool) Sets whether the histogram is computed once over all + channels of the image, or once per channel. + levelMode 'mono' or 'rgba'. If 'mono', then only a single set of + black/white level lines is drawn, and the levels apply to + all channels in the image. If 'rgba', then one set of + levels is drawn for each channel. + ================ =========================================================== """ sigLookupTableChanged = QtCore.Signal(object) diff --git a/pyqtgraph/graphicsItems/InfiniteLine.py b/pyqtgraph/graphicsItems/InfiniteLine.py index 36505026..37d84c7e 100644 --- a/pyqtgraph/graphicsItems/InfiniteLine.py +++ b/pyqtgraph/graphicsItems/InfiniteLine.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- from ..Qt import QtGui, QtCore from ..Point import Point from .GraphicsObject import GraphicsObject @@ -160,7 +161,8 @@ class InfiniteLine(GraphicsObject): ============= ========================================================= **Arguments** marker String indicating the style of marker to add: - '<|', '|>', '>|', '|<', '<|>', '>|<', '^', 'v', 'o' + ``'<|'``, ``'|>'``, ``'>|'``, ``'|<'``, ``'<|>'``, + ``'>|<'``, ``'^'``, ``'v'``, ``'o'`` position Position (0.0-1.0) along the visible extent of the line to place the marker. Default is 0.5. size Size of the marker in pixels. Default is 10.0. diff --git a/pyqtgraph/graphicsItems/LinearRegionItem.py b/pyqtgraph/graphicsItems/LinearRegionItem.py index 9903dac5..56ff5748 100644 --- a/pyqtgraph/graphicsItems/LinearRegionItem.py +++ b/pyqtgraph/graphicsItems/LinearRegionItem.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- from ..Qt import QtGui, QtCore from .GraphicsObject import GraphicsObject from .InfiniteLine import InfiniteLine @@ -54,17 +55,17 @@ class LinearRegionItem(GraphicsObject): False, they are static. bounds Optional [min, max] bounding values for the region span Optional [min, max] giving the range over the view to draw - the region. For example, with a vertical line, use span=(0.5, 1) - to draw only on the top half of the view. + the region. For example, with a vertical line, use + ``span=(0.5, 1)`` to draw only on the top half of the + view. swapMode Sets the behavior of the region when the lines are moved such that - their order reverses: - * "block" means the user cannot drag one line past the other - * "push" causes both lines to be moved if one would cross the other - * "sort" means that lines may trade places, but the output of - getRegion always gives the line positions in ascending order. - * None means that no attempt is made to handle swapped line - positions. - The default is "sort". + their order reverses. "block" means the user cannot drag + one line past the other. "push" causes both lines to be + moved if one would cross the other. "sort" means that + lines may trade places, but the output of getRegion + always gives the line positions in ascending order. None + means that no attempt is made to handle swapped line + positions. The default is "sort". ============== ===================================================================== """ diff --git a/pyqtgraph/graphicsItems/PlotDataItem.py b/pyqtgraph/graphicsItems/PlotDataItem.py index 172e3beb..58a218c7 100644 --- a/pyqtgraph/graphicsItems/PlotDataItem.py +++ b/pyqtgraph/graphicsItems/PlotDataItem.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- import numpy as np from .. import metaarray as metaarray from ..Qt import QtCore @@ -40,25 +41,30 @@ class PlotDataItem(GraphicsObject): **Data initialization arguments:** (x,y data only) =================================== ====================================== - PlotDataItem(xValues, yValues) x and y values may be any sequence (including ndarray) of real numbers - PlotDataItem(yValues) y values only -- x will be automatically set to range(len(y)) + PlotDataItem(xValues, yValues) x and y values may be any sequence + (including ndarray) of real numbers + PlotDataItem(yValues) y values only -- x will be + automatically set to range(len(y)) PlotDataItem(x=xValues, y=yValues) x and y given by keyword arguments - PlotDataItem(ndarray(Nx2)) numpy array with shape (N, 2) where x=data[:,0] and y=data[:,1] + PlotDataItem(ndarray(Nx2)) numpy array with shape (N, 2) where + ``x=data[:,0]`` and ``y=data[:,1]`` =================================== ====================================== **Data initialization arguments:** (x,y data AND may include spot style) - =========================== ========================================= - PlotDataItem(recarray) numpy array with dtype=[('x', float), ('y', float), ...] - PlotDataItem(list-of-dicts) [{'x': x, 'y': y, ...}, ...] - PlotDataItem(dict-of-lists) {'x': [...], 'y': [...], ...} - PlotDataItem(MetaArray) 1D array of Y values with X sepecified as axis values - OR 2D array with a column 'y' and extra columns as needed. - =========================== ========================================= + ============================ ========================================= + PlotDataItem(recarray) numpy array with ``dtype=[('x', float), + ('y', float), ...]`` + PlotDataItem(list-of-dicts) ``[{'x': x, 'y': y, ...}, ...]`` + PlotDataItem(dict-of-lists) ``{'x': [...], 'y': [...], ...}`` + PlotDataItem(MetaArray) 1D array of Y values with X sepecified as + axis values OR 2D array with a column 'y' + and extra columns as needed. + ============================ ========================================= **Line style keyword arguments:** - ========== ============================================================================== + ============ ============================================================================== connect Specifies how / whether vertexes should be connected. See :func:`arrayToQPath() ` pen Pen to use for drawing line between points. @@ -67,15 +73,14 @@ class PlotDataItem(GraphicsObject): shadowPen Pen for secondary line to draw behind the primary line. disabled by default. May be any single argument accepted by :func:`mkPen() ` fillLevel Fill the area between the curve and fillLevel - fillOutline (bool) If True, an outline surrounding the *fillLevel* - area is drawn. - fillBrush Fill to use when fillLevel is specified. + fillOutline (bool) If True, an outline surrounding the *fillLevel* area is drawn. + fillBrush Fill to use when fillLevel is specified. May be any single argument accepted by :func:`mkBrush() ` stepMode If True, two orthogonal lines are drawn for each sample as steps. This is commonly used when drawing histograms. - Note that in this case, `len(x) == len(y) + 1` + Note that in this case, ``len(x) == len(y) + 1`` (added in version 0.9.9) - ========== ============================================================================== + ============ ============================================================================== **Point style keyword arguments:** (see :func:`ScatterPlotItem.setData() ` for more information) diff --git a/pyqtgraph/graphicsWindows.py b/pyqtgraph/graphicsWindows.py index b6a321ee..4033baf3 100644 --- a/pyqtgraph/graphicsWindows.py +++ b/pyqtgraph/graphicsWindows.py @@ -15,11 +15,10 @@ from .widgets.GraphicsView import GraphicsView class GraphicsWindow(GraphicsLayoutWidget): """ - (deprecated; use GraphicsLayoutWidget instead) + (deprecated; use :class:`~pyqtgraph.GraphicsLayoutWidget` instead) - Convenience subclass of :class:`GraphicsLayoutWidget - `. This class is intended for use from - the interactive python prompt. + Convenience subclass of :class:`~pyqtgraph.GraphicsLayoutWidget`. This class + is intended for use from the interactive python prompt. """ def __init__(self, title=None, size=(800,600), **kargs): mkQApp() @@ -50,7 +49,7 @@ class TabWindow(QtGui.QMainWindow): class PlotWindow(PlotWidget): """ - (deprecated; use PlotWidget instead) + (deprecated; use :class:`~pyqtgraph.PlotWidget` instead) """ def __init__(self, title=None, **kargs): mkQApp() @@ -66,7 +65,7 @@ class PlotWindow(PlotWidget): class ImageWindow(ImageView): """ - (deprecated; use ImageView instead) + (deprecated; use :class:`~pyqtgraph.ImageView` instead) """ def __init__(self, *args, **kargs): mkQApp() diff --git a/pyqtgraph/widgets/GraphicsLayoutWidget.py b/pyqtgraph/widgets/GraphicsLayoutWidget.py index 3b41a3ca..6249ba26 100644 --- a/pyqtgraph/widgets/GraphicsLayoutWidget.py +++ b/pyqtgraph/widgets/GraphicsLayoutWidget.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- from ..Qt import QtGui, mkQApp from ..graphicsItems.GraphicsLayout import GraphicsLayout from .GraphicsView import GraphicsView @@ -17,21 +18,20 @@ class GraphicsLayoutWidget(GraphicsView): p2 = w.addPlot(row=0, col=1) v = w.addViewBox(row=1, col=0, colspan=2) - Parameters - ---------- - parent : QWidget or None - The parent widget (see QWidget.__init__) - show : bool - If True, then immediately show the widget after it is created. - If the widget has no parent, then it will be shown inside a new window. - size : (width, height) tuple - Optionally resize the widget. Note: if this widget is placed inside a - layout, then this argument has no effect. - title : str or None - If specified, then set the window title for this widget. - kargs : - All extra arguments are passed to - :func:`GraphicsLayout.__init__() ` + ========= ================================================================= + parent (QWidget or None) The parent widget. + show (bool) If True, then immediately show the widget after it is + created. If the widget has no parent, then it will be shown + inside a new window. + size (width, height) tuple. Optionally resize the widget. Note: if + this widget is placed inside a layout, then this argument has no + effect. + title (str or None) If specified, then set the window title for this + widget. + kargs All extra arguments are passed to + :meth:`GraphicsLayout.__init__ + ` + ========= ================================================================= This class wraps several methods from its internal GraphicsLayout: