From 06e6d95683ccbf9302c7c0431224a0fd54d87b5f Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 4 Jun 2024 14:26:50 +0200
Subject: [PATCH] DOC: Document the parameter *position* of apply_aspect() as
 internal

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 66290aae. 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
https://github.com/matplotlib/matplotlib/pull/23629#issuecomment-2145669284
---
 lib/matplotlib/axes/_base.py | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
index 980ef2f51c94..1aa1af53c9a9 100644
--- 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,24 @@ 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 adapting the Axes position and extent to reflect this is
+        deferred until rendering for performance reasons. If you want 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)