DOCS: add examples of how one "should" use Bbox

brunobeltran · brunobeltran · commit b8cd9e4deef8 · 2020-04-09T21:51:02.000-07:00
diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py
@@ -682,6 +682,42 @@ def intersection(bbox1, bbox2):
 class Bbox(BboxBase):
     """
     A mutable bounding box.
+
+
+    Examples
+    --------
+    >>> # the default constructor takes the boundary "points" [[xmin, ymin],
+    >>> # [xmax, ymax]]
+    >>> unit_box = Bbox([[1, 1], [2, 2]])
+
+    >>> # the "zero" Bbox (i.e. "identity" object for Bbox.intersection), the
+    >>> # null bbox has (min, max) = (np.inf, -np.inf) for each dimension
+    >>> null = Bbox.null()
+    >>> assert unit_box == Bbox.intersection(unit_box, null)
+
+    >>> # and thus it overlaps with every bbox
+    >>> assert unit_bbox.overlaps(null)
+
+    >>> # a union containing null (the "zero" Bbox) will always return null
+    >>> assert null == Bbox.union([unit_bbox, null])
+
+    >>> # a Bbox can be created from extents (xmin, ymin, xmax, ymax)
+    >>> assert unit_bbox == Bbox.from_extents(1, 1, 2, 2)
+
+    >>> # or from "bounds" (xmin, ymin, width, height)
+    >>> assert unit_bbox == Bbox.from_bounds(1, 1, 1, 1)
+
+    >>> # or from an arbitrary list of points (here, 10 random points)
+    >>> random_bbox = Bbox.null()
+    >>> random_bbox.update_from_data_xy(np.random.rand((10, 2)))
+
+    >>> # to quickly update a Bbox to include new point(s), simply use
+    >>> # `ignore=False`, it's faster than using `union` directly
+    >>> new_data = np.random.rand(10, 2)  # 10 new points
+    >>> new_bbox = Bbox.null()
+    >>> new_bbox.update_from_data_xy(new_data)
+    >>> assert random_bbox.update_from_data_xy(new_data, ignore=False) \
+    >>>     == Bbox.union([new_bbox, random_bbox])
     """
 
     def __init__(self, points, **kwargs):
