Merge pull request matplotlib#29875 from timhoffm/doc-text-bbox

Author: timhoffm

lib/matplotlib/text.py

@@ -516,14 +516,21 @@ def _get_layout(self, renderer):
 
     def set_bbox(self, rectprops):
         """
-        Draw a bounding box around self.
+        Draw a box behind/around the text.
+
+        This can be used to set a background and/or a frame around the text.
+        It's realized through a `.FancyBboxPatch` behind the text (see also
+        `.Text.get_bbox_patch`). The bbox patch is None by default and only
+        created when needed.
 
         Parameters
         ----------
-        rectprops : dict with properties for `.patches.FancyBboxPatch`
+        rectprops : dict with properties for `.FancyBboxPatch` or None
              The default boxstyle is 'square'. The mutation
              scale of the `.patches.FancyBboxPatch` is set to the fontsize.
 
+             Pass ``None`` to remove the bbox patch completely.
+
         Examples
         --------
         ::
@@ -558,6 +565,8 @@ def get_bbox_patch(self):
         """
         Return the bbox Patch, or None if the `.patches.FancyBboxPatch`
         is not made.
+
+        For more details see `.Text.set_bbox`.
         """
         return self._bbox_patch
 
@@ -981,7 +990,10 @@ def get_window_extent(self, renderer=None, dpi=None):
 
     def set_backgroundcolor(self, color):
         """
-        Set the background color of the text by updating the bbox.
+        Set the background color of the text.
+
+        This is realized through the bbox (see `.set_bbox`),
+        creating the bbox patch if needed.
 
         Parameters
         ----------

lib/matplotlib/text.pyi

@@ -48,7 +48,7 @@ class Text(Artist):
     def get_transform_rotates_text(self) -> bool: ...
     def set_rotation_mode(self, m: None | Literal["default", "anchor", "xtick", "ytick"]) -> None: ...
     def get_rotation_mode(self) -> Literal["default", "anchor", "xtick", "ytick"]: ...
-    def set_bbox(self, rectprops: dict[str, Any]) -> None: ...
+    def set_bbox(self, rectprops: dict[str, Any] | None) -> None: ...
     def get_bbox_patch(self) -> None | FancyBboxPatch: ...
     def update_bbox_position_size(self, renderer: RendererBase) -> None: ...
     def get_wrap(self) -> bool: ...