Repository: bokeh/bokeh

Issue:
Mention nonselection_glyph and selection_glyph options in Tools documentation.
(plan to do this, just noting for now)

In each documentation for a select tool, where there is already:

"Selections can be comprised of multiple regions, even those
made by different selection tools. Hold down the <<shift>> key
while making a selection to append the new selection to any
previous seletion that might exist."
e.g. https://github.com/bokeh/bokeh/blob/master/bokeh/models/tools.py#L150

Add a note that you can customize the display of the selected and unselected glyphs by passing selection_glyph and nonselection_glyph parameter to add_glyph method.



Discussion:

Resolving patch:
diff --git a/bokeh/models/tools.py b/bokeh/models/tools.py
--- a/bokeh/models/tools.py
+++ b/bokeh/models/tools.py
@@ -29,6 +29,7 @@
 from .renderers import Renderer
 from .actions import Action, Callback
 
+
 class ToolEvents(PlotObject):
     """
 
@@ -36,6 +37,7 @@ class ToolEvents(PlotObject):
 
     geometries = List(Dict(String, Any))
 
+
 class Tool(PlotObject):
     """ A base class for all interactive tool types. ``Tool`` is
     not generally useful to instantiate on its own.
@@ -46,6 +48,7 @@ class Tool(PlotObject):
     The Plot that this tool will act on.
     """)
 
+
 class PanTool(Tool):
     """ *toolbar icon*: |pan_icon|
 
@@ -70,6 +73,7 @@ class PanTool(Tool):
     height of the plot.
     """)
 
+
 class WheelZoomTool(Tool):
     """ *toolbar icon*: |wheel_zoom_icon|
 
@@ -93,6 +97,7 @@ class WheelZoomTool(Tool):
     vertically across the height of the plot.
     """)
 
+
 class PreviewSaveTool(Tool):
     """ *toolbar icon*: |save_icon|
 
@@ -110,6 +115,7 @@ class PreviewSaveTool(Tool):
 
     """
 
+
 class ResetTool(Tool):
     """ *toolbar icon*: |reset_icon|
 
@@ -126,6 +132,7 @@ class ResetTool(Tool):
         :height: 18pt
     """
 
+
 class ResizeTool(Tool):
     """ *toolbar icon*: |resize_icon|
 
@@ -137,21 +144,24 @@ class ResizeTool(Tool):
 
     """
 
+
 class TapTool(Tool):
     """ *toolbar icon*: |tap_select_icon|
 
     The tap selection tool allows the user to select at single points by
     left-clicking a mouse, or tapping with a finger.
 
+    See :ref:`userguide_styling_selected_unselected_glyphs` for information
+    on styling selected and unselected glyphs.
+
     .. |tap_select_icon| image:: /_images/icons/TapSelect.png
         :height: 18pt
 
-   .. note::
+    .. note::
         Selections can be comprised of multiple regions, even those
         made by different selection tools. Hold down the <<shift>> key
         while making a selection to append the new selection to any
         previous seletion that might exist.
-
     """
 
     names = List(String, help="""
@@ -166,13 +176,14 @@ class TapTool(Tool):
 
     action = Instance(Action, help="""
     A client-side action specification, like opening a URL, showing
-    a dialog box, etc. See :class:`bokeh.models.Action` for details.
+    a dialog box, etc. See :class:`~bokeh.models.actions.Action` for details.
     """)
 
     always_active = Bool(True, help="""
     Whether the hover tool must be explicitly activated.
     """)
 
+
 class CrosshairTool(Tool):
     """ *toolbar icon*: |inspector_icon|
 
@@ -197,6 +208,7 @@ class CrosshairTool(Tool):
     only a vertical line will be drawn.
     """)
 
+
 class BoxZoomTool(Tool):
     """ *toolbar icon*: |box_zoom_icon|
 
@@ -220,6 +232,7 @@ class BoxZoomTool(Tool):
     dimension can be controlled.
     """)
 
+
 class BoxSelectTool(Tool):
     """ *toolbar icon*: |box_select_icon|
 
@@ -228,6 +241,10 @@ class BoxSelectTool(Tool):
     mouse or a finger over the plot region. The end of the drag
     event indicates the selection region is ready.
 
+    See :ref:`userguide_styling_selected_unselected_glyphs` for information
+    on styling selected and unselected glyphs.
+
+
     .. |box_select_icon| image:: /_images/icons/BoxSelect.png
         :height: 18pt
 
@@ -266,6 +283,7 @@ class BoxSelectTool(Tool):
     :geometry: object containing the coordinates of the selection box
     """)
 
+
 class BoxSelectionOverlay(Renderer):
     """ An overlay renderer that Tool objects can use to render a
     'rubber band' selection box on a Plot.
@@ -278,6 +296,7 @@ class BoxSelectionOverlay(Renderer):
     The tool that this overlay should respond to.
     """)
 
+
 class LassoSelectTool(Tool):
     """ *toolbar icon*: |lasso_select_icon|
 
@@ -286,6 +305,9 @@ class LassoSelectTool(Tool):
     mouse or a finger over the plot region. The end of the drag
     event indicates the selection region is ready.
 
+    See :ref:`userguide_styling_selected_unselected_glyphs` for information
+    on styling selected and unselected glyphs.
+
     .. note::
         Selections can be comprised of multiple regions, even those
         made by different selection tools. Hold down the <<shift>> key
@@ -311,6 +333,7 @@ class LassoSelectTool(Tool):
     event, or only once, when the selection region is completed.
     """)
 
+
 class PolySelectTool(Tool):
     """ *toolbar icon*: |poly_select_icon|
 
@@ -320,6 +343,9 @@ class PolySelectTool(Tool):
     polygon, and a double click (or tap) indicates the selection
     region is ready.
 
+    See :ref:`userguide_styling_selected_unselected_glyphs` for information
+    on styling selected and unselected glyphs.
+
     .. note::
         Selections can be comprised of multiple regions, even those
         made by different selection tools. Hold down the <<shift>> key
@@ -340,6 +366,7 @@ class PolySelectTool(Tool):
     defaults to all renderers on a plot.
     """)
 
+
 class HoverTool(Tool):
     """ *toolbar icon*: |inspector_icon|
 
@@ -450,6 +477,7 @@ class HoverTool(Tool):
     mouse position.
     """)
 
+
 class HelpTool(Tool):
     """
     The help tool is a widget designed to replace the hardcoded 'Help' link.
diff --git a/sphinx/source/docs/user_guide/source_examples/styling_glyph_selections.py b/sphinx/source/docs/user_guide/source_examples/styling_glyph_selections.py
--- a/sphinx/source/docs/user_guide/source_examples/styling_glyph_selections.py
+++ b/sphinx/source/docs/user_guide/source_examples/styling_glyph_selections.py
@@ -1,14 +1,17 @@
-from bokeh.plotting import figure, output_file, show
+from bokeh.io import output_file, show
+from bokeh.plotting import figure
+from bokeh.models import Circle
 
-output_file("axes.html")
+output_file("styling_selections.html")
 
-p = figure(plot_width=400, plot_height=400, tools="lasso_select")
-p.circle([1,2,3,4,5], [2,5,8,2,7], size=50, name="mycircle")
+p = figure(plot_width=400, plot_height=400, tools="tap", title="Select a circle")
+p.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=50, name="mycircle")
 
-glyph = p.select(name="mycircle")[0].nonselection_glyph
-glyph.fill_alpha = 0.2
-glyph.line_color = "firebrick"
-glyph.line_dash = [6, 3]
-glyph.line_width = 2
+selected_circle = Circle(fill_alpha=1, fill_color="firebrick", line_color=None)
+nonselected_circle = Circle(fill_alpha=0.2, fill_color="blue", line_color="firebrick")
+
+renderer = p.select(name="mycircle")
+renderer.selection_glyph = selected_circle
+renderer.nonselection_glyph = nonselected_circle
 
 show(p)


Test patch: