Finalize figure.subplot() and add a docstring

src/bokeh/core/property/singletons.py

@@ -18,19 +18,28 @@
 # Imports
 #-----------------------------------------------------------------------------
 
-#-----------------------------------------------------------------------------
-# Globals and constants
-#-----------------------------------------------------------------------------
+# Standard library imports
+from typing import TypeVar, Union
+
+# External imports
+from typing_extensions import TypeAlias
 
 #-----------------------------------------------------------------------------
-# General API
+# Globals and constants
 #-----------------------------------------------------------------------------
 
 __all__ = (
     "Intrinsic",
+    "Optional",
     "Undefined",
 )
 
+T = TypeVar("T")
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
 #-----------------------------------------------------------------------------
 # Dev API
 #-----------------------------------------------------------------------------
@@ -49,6 +58,8 @@ def __repr__(self) -> str:
 
 Undefined = UndefinedType()
 
+Optional: TypeAlias = Union[T, UndefinedType]
+
 class IntrinsicType:
     """ Indicates usage of the intrinsic default value of a property. """
 

src/bokeh/plotting/_figure.py

@@ -44,6 +44,7 @@
     TimeDelta,
     Tuple,
 )
+from ..core.property.singletons import Optional, Undefined
 from ..models import (
     ColumnDataSource,
     CoordinateMapping,
@@ -224,12 +225,37 @@ def coordinates(self):
 
     def subplot(self,
             *,
-            x_source: Range | None = None, y_source: Range | None = None,
-            x_scale: Scale | None = None, y_scale: Scale | None = None,
-            x_target: Range, y_target: Range,
+            x_source: Optional[Range] = Undefined,
+            y_source: Optional[Range] = Undefined,
+            x_scale: Optional[Scale] = Undefined,
+            y_scale: Optional[Scale] = Undefined,
+            x_target: Range,
+            y_target: Range,
         ) -> GlyphAPI:
-        """ Create a new sub-coordinate system and expose a plotting API. """
-        coordinates = CoordinateMapping(x_source=x_source, y_source=y_source, x_target=x_target, y_target=y_target)
+        """
+        Create a new sub-coordinate system and expose the plotting API.
+
+        Example:
+
+            .. bokeh-plot::
+                :source-position: above
+
+                from bokeh.plotting import figure, show
+
+                p = figure(x_range=[0, 10], y_range=[0, 10])
+                p.subplot(x_target=[0, 1], y_target=p.y_range).circle([0, 1, 2], [0, 1, 2])
+                p.subplot(x_target=[2, 3], y_target=p.y_range).circle([0, 1, 2], [0, 1, 2])
+
+                show(p)
+        """
+        coordinates = CoordinateMapping(
+            x_source=x_source,
+            y_source=y_source,
+            x_scale=x_scale,
+            y_scale=y_scale,
+            x_target=x_target,
+            y_target=y_target,
+        )
         return GlyphAPI(self, coordinates)
 
     def hexbin(self, x, y, size, orientation="pointytop", palette="Viridis256", line_color=None, fill_color=None, aspect_scale=1, **kwargs):

src/bokeh/plotting/glyph_api.py

@@ -46,7 +46,7 @@
 #-----------------------------------------------------------------------------
 
 class GlyphAPI:
-    """ """
+    """ Generalized glyph/plotting API for figures and sub-plots. """
 
     @property
     def plot(self) -> Plot | None: