Merge pull request #84 from wpfff/feature/plotwidgets

Feature/plotwidgets

doc/api/index.rst

@@ -0,0 +1,9 @@
+API documentation
+=================
+
+.. toctree::
+    :maxdepth: 3
+    :caption: Contents:
+
+    node
+    plot

doc/api/node.rst

@@ -0,0 +1,7 @@
+Node and Flowchart core elements
+--------------------------------
+
+Node essentials: the node module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: plottr.node.node
+    :members:

doc/api/plot.rst

@@ -0,0 +1,12 @@
+Plotting elements
+-----------------
+
+Base elements
+^^^^^^^^^^^^^
+.. automodule:: plottr.plot.base
+    :members:
+
+Matplotlib plotting tools
+^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: plottr.plot.mpl
+    :members:

doc/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'plottr'
+copyright = '2020, Wolfgang Pfaff'
+author = 'Wolfgang Pfaff'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx_autodoc_typehints',
+    'sphinx.ext.todo',
+    'sphinx.ext.mathjax',
+]
+napoleon_use_param = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

doc/examples/Live plotting qcodes data.ipynb

@@ -263,10 +263,10 @@
     "For the implementation, see the ``autonode_app.py`` file in the ``doc/examples`` folder.\n",
     "(Note: you need `lmfit` installed for this one).\n",
     "\n",
-    "To see what it does, start the example below -- it's purposefully set to a very slow repetition rate. Then note down the runId that's displayed, and from this directory run:\n",
+    "To see what it does, start the example below -- it's purposefully set to a very slow repetition rate. Then note down the runId that's displayed, and run:\n",
     "\n",
     "``\n",
-    "$ python autonode.py ./qcodes_liveplot_demo.db <runid>\n",
+    "$ python ./doc/examples/autonode_app.py ./doc/examples/qcodes_liveplot_demo.db <runid>\n",
     "``\n",
     "\n",
     "You can of course kill it anytime you're getting bored."
@@ -327,9 +327,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python [conda env:qcodes]",
    "language": "python",
-   "name": "python3"
+   "name": "conda-env-qcodes-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -341,7 +341,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.7"
+   "version": "3.7.5"
   },
   "toc": {
    "base_numbering": 1,
@@ -387,5 +387,5 @@
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

doc/examples/autonode_app.py

@@ -14,7 +14,7 @@
 from plottr.node.grid import DataGridder
 from plottr.node.dim_reducer import XYSelector
 from plottr.node.autonode import autonode
-from plottr.plot.mpl import PlotNode
+from plottr.plot.base import PlotNode
 from plottr.apps.autoplot import QCAutoPlotMainWindow
 
 
@@ -73,7 +73,8 @@ def main(pathAndId):
         ('plot', PlotNode),
     )
 
-    win = QCAutoPlotMainWindow(fc, pathAndId=pathAndId)
+    win = QCAutoPlotMainWindow(fc, pathAndId=pathAndId,
+                               loaderName='Dataset loader')
     win.show()
 
     return app.exec_()

doc/source/index.rst → doc/index.rst

@@ -7,11 +7,13 @@ Welcome to plottr's documentation!
 ==================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
    dataformat
    nodes
+   plotnode
+   api/index
 
 
 

doc/source/nodes.rst → doc/nodes.rst

@@ -104,9 +104,3 @@ That is essentially all that is needed for the Node; only the process function t
 
 
 This node can then already be used, with the UI if desired, in a flowchart.
-
-API documentation for the node module
--------------------------------------
-
-.. automodule:: plottr.node.node
-    :members:

doc/plotnode.rst

@@ -0,0 +1,27 @@
+Plotting
+========
+
+Plot Nodes
+----------
+Plots have a somewhat special role in the node system:
+We need a node to make plots aware of incoming data, but the node will (typically) not do anything to the data.
+In the simplest case, :meth:`Node.process <plottr.node.node.Node.process>` will just call a function that triggers plotting, using the just received data.
+For many applications the base class :class:`PlotNode <plottr.plot.base.PlotNode>` will do the job without any need to customize.
+
+
+Plot Widgets
+------------
+To make the plot node aware of the presence of a GUI, a suitable widget must be connected to it.
+This can be done by instantiating :class:`PlotWidgetContainer <plottr.plot.base.PlotWidgetContainer>`, and passing the instance to the node's :meth:`setPlotWidgetContainer <plottr.plot.base.PlotWidgetContainer.setPlotWidgetContainer>` method.
+This will make sure that the container's :meth:`setData <plottr.plot.base.PlotWidgetContainer.setData>` is called whenever the node receives data.
+The container can then in turn host a :class:`PlotWidgetContainer <plottr.plot.base.PlotWidget>`, which is connected by using :meth:`setPlotWidget <plottr.plot.base.PlotWidgetContainer.setPlotWidget>`.
+The reason why we don't connect the widget directly to the node is that the container may provide controls to change the widgets through user controls.
+
+.. image:: img/plot-node-system.png
+
+
+Automatic plotting with Matplotlib
+----------------------------------
+The most commonly used plot widget is based on matplotlib: :class:`AutoPlot <plottr.plot.mpl.AutoPlot>`.
+It determines automatically what an appropriate visualization of the received data is, and then plots that (at least if it can determine a good way to plot).
+At the same time it gives the user a little bit of control over the appearance (partially through native matplotlib tools).

doc/requirements.txt

@@ -0,0 +1,3 @@
+sphinx==2.4.4
+sphinx-autodoc-typehints>=1.10.3
+PyQt5>=5.9.0