Merge branch 'develop' into bad-pixel-monitor

jwql/bokeh_templating/example/example_interface.yaml

@@ -1,35 +1,35 @@
-- !ColumnDataSource: &dummy
+- !ColumnDataSource: &dummy # This is a dummy ColumnDataSource used to trigger the controller method whenever a slider is changed.
     data:
         value: []
     on_change: ['data', !self.controller ]
-- !CustomJS: &callback
+- !CustomJS: &callback # This callback changes the value of the dummy ColumnDataSource data to trigger the controller method.
     ref: "callback"
     args:
         source: *dummy
     code: "\n    source.data = { value: [cb_obj.value] }\n"
-- !Slider: &a_slider
+- !Slider: &a_slider # a slider for the a value
     ref: "a_slider"
     title: "A"
     value: 4
     range: !!python/tuple [1, 20, 0.1]
     callback: *callback
-- !Slider: &b_slider
+- !Slider: &b_slider # a slider for the b value
     ref: "b_slider"
     title: "B"
     value: 2
     range: !!python/tuple [1, 20, 0.1]
     callback: *callback
-- !ColumnDataSource: &figure_source
+- !ColumnDataSource: &figure_source # the ColumnDataSource for the figure
     ref: "figure_source"
     data:
         x: !self.x
         y: !self.y
-- !Figure: &the_figure
+- !Figure: &the_figure # the Figure itself, which includes a single line element.
     ref: 'the_figure'
     elements:
         - {'kind': 'line', 'source': *figure_source, 'line_color': 'orange', 'line_width': 2}
-- !Document:
+- !Document: # the Bokeh document layout: a single column with the figure and two sliders
     - !column:
-        - *the_figure
+        - *the_figure # note the use of YAML anchors to add the Bokeh objects to the Document layout directly.
         - *a_slider
         - *b_slider

jwql/bokeh_templating/example/main.py

@@ -1,10 +1,19 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 """
-Created on Fri Jul 20 10:03:35 2018
+This is a minimal example demonstrating how to create a Bokeh app using
+the ``bokeh-templating`` package and the associated YAML template files.
 
-@author: gkanarek
+Author
+-------
+
+    - Graham Kanarek
+
+Dependencies
+------------
+
+    The user must have PyYAML, Bokeh, and the ``bokeh-templating``
+    packages installed.
 """
+
 import os
 import numpy as np
 
@@ -14,24 +23,37 @@
 
 
 class TestBokehApp(BokehTemplate):
+    """This is a minimal ``BokehTemplate`` app."""
 
     def pre_init(self):
+        """Before creating the Bokeh interface (by parsing the interface
+        file), we must initialize our ``a`` and ``b`` variables, and set
+        the path to the interface file.
+        """
+
         self.a, self.b = 4, 2
 
         self.format_string = None
         self.interface_file = os.path.join(file_dir, "example_interface.yaml")
 
+    # No post-initialization tasks are required.
     post_init = None
 
     @property
     def x(self):
+        """The x-value of the Lissajous curves."""
         return 4. * np.sin(self.a * np.linspace(0, 2 * np.pi, 500))
 
     @property
     def y(self):
+        """The y-value of the Lissajous curves."""
         return 3. * np.sin(self.b * np.linspace(0, 2 * np.pi, 500))
 
     def controller(self, attr, old, new):
+        """This is the controller function which is used to update the
+        curves when the sliders are adjusted. Note the use of the
+        ``self.refs`` dictionary for accessing the Bokeh object
+        attributes."""
         self.a = self.refs["a_slider"].value
         self.b = self.refs["b_slider"].value