Repository: bokeh/bokeh

Issue:
Add simple inline examples to all or most plotting.py glyph functions
Use new `:bokeh-plot:` directive. This depends on #1690 being merged first (some fixes are included in that PR)



Discussion:

Resolving patch:
diff --git a/bokeh/_glyph_functions.py b/bokeh/_glyph_functions.py
--- a/bokeh/_glyph_functions.py
+++ b/bokeh/_glyph_functions.py
@@ -144,6 +144,20 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.annulus(x=[1, 2, 3], y=[1, 2, 3], inner_radius=0.2,
+                    outer_radius=0.5, color="#7FC97F"
+                    )
+
+        show(plot)
 """
 )
 
@@ -183,6 +197,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.asterisk(x=[1,2,3], y=[1,2,3], size=20, color="#F0027F")
+
+        show(plot)
+
 """
 )
 
@@ -228,6 +255,19 @@ def func(plot, *args, **kwargs):
 
 Notes:
     Only one of `size` or `radius` should be provided. Note that `radius` defaults to data units.
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.circle(x=[1, 2, 3], y=[1, 2, 3], radius=0.1, size=20)
+
+        show(plot)
+
 """
 )
 
@@ -246,6 +286,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.circle_cross(x=[1,2,3], y=[4,5,6], fill_alpha=0, line_width=2,
+                         color="#FB8072", size=20)
+
+        show(plot)
 """
 )
 
@@ -264,6 +317,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.circle_x(x=[1, 2, 3], y=[1, 2, 3], radius=0.1, size=20,
+                     fill_alpha=0, color="#DD1C77")
+
+        show(plot)
 """
 )
 
@@ -282,6 +348,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.cross(x=[1, 2, 3], y=[1, 2, 3], size=20,
+                    color="#E6550D", line_width=2)
+
+        show(plot)
 """
 )
 
@@ -300,6 +379,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.diamond(x=[1, 2, 3], y=[1, 2, 3], size=20,
+                    color="#1C9099", line_width=2)
+
+        show(plot)
 """
 )
 
@@ -318,6 +410,21 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.diamond_cross(x=[1, 2, 3], y=[1, 2, 3], size=20,
+                            color="#386CB0",fill_color=None, line_width=2)
+
+        show(plot)
+
+
 """
 )
 
@@ -398,6 +505,20 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.inverted_triangle(x=[1, 2, 3], y=[1, 2, 3], size=20,
+                              color="#DE2D26")
+
+        show(plot)
 """
 )
 
@@ -427,10 +548,8 @@ def func(plot, *args, **kwargs):
 
        from bokeh.plotting import figure, output_file, show
 
-       output_file("lines.html")
-
        p = figure(title="line", plot_width=300, plot_height=300)
-       p.line([1, 2, 3, 4, 5], [6, 7, 2, 4, 5])
+       p.line(x=[1, 2, 3, 4, 5], y=[6, 7, 2, 4, 5])
 
        show(p)
 """
@@ -453,6 +572,18 @@ def func(plot, *args, **kwargs):
 Returns:
     plot
 
+Examples:
+
+    .. bokeh-plot::
+       :source-position: above
+
+       from bokeh.plotting import figure, output_file, show
+
+       p = figure(plot_width=300, plot_height=300)
+       p.multi_line(xs=[[1, 2, 3], [2, 3, 4]], ys=[[6, 7, 2], [4, 5, 7]],
+                    color=['red','green'])
+
+       show(p)
 """,
     xfields=["xs"], yfields=["ys"],
 )
@@ -474,6 +605,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.oval(x=[1, 2, 3], y=[1, 2, 3], width=15, height=25, angle=-0.7, color="#1D91C0",
+                 width_units="screen", height_units="screen")
+
+        show(plot)
 """
 )
 
@@ -491,6 +635,18 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+       :source-position: above
+
+       from bokeh.plotting import figure, output_file, show
+
+       p = figure(plot_width=300, plot_height=300)
+       p.patch(x=[1, 2, 3, 2], y=[6, 7, 2, 2], color="#99d8c9")
+
+       show(p)
 """
 )
 
@@ -511,6 +667,18 @@ def func(plot, *args, **kwargs):
 Returns:
     plot
 
+Examples:
+
+    .. bokeh-plot::
+       :source-position: above
+
+       from bokeh.plotting import figure, output_file, show
+
+       p = figure(plot_width=300, plot_height=300)
+       p.patches(xs=[[1,2,3],[4,5,6,5]], ys=[[1,2,1],[4,5,5,4]],
+                color=["#43a2ca", "#a8ddb5"])
+
+       show(p)
 """,
     xfields=["xs"], yfields=["ys"],
 )
@@ -531,6 +699,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.quad(top=[2, 3, 4], bottom=[1, 2, 3], left=[1, 2, 3],
+            right=[1.2, 2.5, 3.7], color="#B3DE69")
+
+        show(plot)
 """,
     xfields=["left", "right"], yfields=["top", "bottom"])
 
@@ -572,6 +753,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.ray(x=[1, 2, 3], y=[1, 2, 3], length=45, angle=-0.7, color="#FB8072",
+                 line_width=2)
+
+        show(plot)
 """
 )
 
@@ -598,6 +792,19 @@ def func(plot, *args, **kwargs):
     setting `dilate` to True will cause pixel distances (e.g., for `width` and `height`) to
     be rounded up, always.
 
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.rect(x=[1, 2, 3], y=[1, 2, 3], width=10, height=20, color="#CAB2D6",
+            width_units="screen", height_units="screen")
+
+        show(plot)
 """
 )
 
@@ -616,6 +823,21 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.segment(x0=[1, 2, 3], y0=[1, 2, 3], x1=[1, 2, 3],
+                    y1=[1.2, 2.5, 3.7], color="#F4A582",
+                    line_width=3)
+
+        show(plot)
+
 """,
     xfields=["x0", "x1"], yfields=["y0", "y1"])
 
@@ -634,6 +856,18 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.square(x=[1, 2, 3], y=[1, 2, 3], size=[10,20,30], color="#74ADD1")
+
+        show(plot)
 """
 )
 
@@ -651,6 +885,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.square_cross(x=[1, 2, 3], y=[1, 2, 3], size=[10,20,25],
+                         color="#7FC97F",fill_color=None, line_width=2)
+
+        show(plot)
 """
 )
 
@@ -668,6 +915,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.square_x(x=[1, 2, 3], y=[1, 2, 3], size=[10,20,25],
+                     color="#FDAE6B",fill_color=None, line_width=2)
+
+        show(plot)
 """
 )
 
@@ -688,6 +948,7 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
 """
 )
 
@@ -706,6 +967,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.triangle(x=[1, 2, 3], y=[1, 2, 3], size=[10,20,25],
+                     color="#99D594", line_width=2)
+
+        show(plot)
 """
 )
 
@@ -726,6 +1000,19 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.wedge(x=[1, 2, 3], y=[1, 2, 3], radius=15, start_angle=0.6,
+                     end_angle=4.1, radius_units="screen", color="#2b8cbe")
+
+        show(plot)
 """
 )
 
@@ -744,5 +1031,17 @@ def func(plot, *args, **kwargs):
 
 Returns:
     plot
+
+Examples:
+
+    .. bokeh-plot::
+        :source-position: above
+
+        from bokeh.plotting import figure, output_file, show
+
+        plot = figure(width=300, height=300)
+        plot.x(x=[1, 2, 3], y=[1, 2, 3], size=[10, 20, 25], color="#fa9fb5")
+
+        show(plot)
 """
 )


Test patch: