DOC: Document the parameter *position* of apply_aspect() as internal

timhoffm · timhoffm · commit dbd1f4ea8c46 · 2024-06-04T23:06:04.000+02:00
Superseeds #23629. It is somewhat surprising that "_apply_aspect" takes an optional position as input, which seems more functionality than what the name suggests. The parameter was introduced in 66290aa. Generally, applying an aspect will modify the size and position of an Axes. The fact that position is updated anyway was used to funnel additional position information from a layout into the already existing positioning code. Deprecating and removing the parameter would be a medium compatibility hassle. Therefore, I chose only to document the status quo and its intention, so that users are less surprised. See #23629 (comment)
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1881,6 +1881,11 @@ def apply_aspect(self, position=None):
         Parameters
         ----------
         position : None or .Bbox
+
+            .. note::
+                This parameter exists for historic reasons and is considered
+                internal. End users should not use it.
+
             If not ``None``, this defines the position of the
             Axes within the figure as a Bbox. See `~.Axes.get_position`
             for further details.
@@ -1891,6 +1896,10 @@ def apply_aspect(self, position=None):
         to call it yourself if you need to update the Axes position and/or
         view limits before the Figure is drawn.
 
+        An alternative with a broader scope is `.Figure.draw_without_rendering`,
+        which updates all stale components of a figure, not only the positioning /
+        view limits of a single Axes.
+
         See Also
         --------
         matplotlib.axes.Axes.set_aspect
@@ -1899,6 +1908,23 @@ def apply_aspect(self, position=None):
             Set how the Axes adjusts to achieve the required aspect ratio.
         matplotlib.axes.Axes.set_anchor
             Set the position in case of extra space.
+        matplotlib.figure.Figure.draw_without_rendering
+            Update all stale components of a figure.
+
+        Examples
+        --------
+        A typical usage example would be the following. `~.Axes.imshow` sets the
+        aspect to 1, but the Axes will only be updated for that on rendering.
+        If you need to know the Axes size before, you need to call `.apply_aspect`
+        to get the correct values.
+
+        >>> fig, ax = plt.subplots()
+        >>> ax.imshow(np.zeros((3, 3)))
+        >>> ax.bbox.width, ax.bbox.height
+        (496.0, 369.59999999999997)
+        >>> ax.apply_aspect()
+        >>> ax.bbox.width, ax.bbox.height
+        (369.59999999999997, 369.59999999999997)
         """
         if position is None:
             position = self.get_position(original=True)
