From e6a9e25f650d175e0767b4ffb7043fdf165a7778 Mon Sep 17 00:00:00 2001
From: Khushi_29 <121342846+Khushikela29@users.noreply.github.com>
Date: Fri, 24 Jan 2025 19:19:28 +0530
Subject: [PATCH] Backport PR #29471: Fix subplot docs

---
 doc/api/axes_api.rst     |  1 +
 lib/matplotlib/pyplot.py | 14 ++++----------
 2 files changed, 5 insertions(+), 10 deletions(-)

diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
index 6afdad4e768e..bf2e30ea983c 100644
--- a/doc/api/axes_api.rst
+++ b/doc/api/axes_api.rst
@@ -616,5 +616,6 @@ Other
    Axes.get_transformed_clip_path_and_affine
    Axes.has_data
    Axes.set
+   Axes.remove
 
 .. autoclass:: matplotlib.axes.Axes.ArtistList
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index ba7a5e32f5d0..12aedf5157ca 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -1449,16 +1449,10 @@ def subplot(*args, **kwargs) -> Axes:
 
     Notes
     -----
-    Creating a new Axes will delete any preexisting Axes that
-    overlaps with it beyond sharing a boundary::
-
-        import matplotlib.pyplot as plt
-        # plot a line, implicitly creating a subplot(111)
-        plt.plot([1, 2, 3])
-        # now create a subplot which represents the top plot of a grid
-        # with 2 rows and 1 column. Since this subplot will overlap the
-        # first, the plot (and its Axes) previously created, will be removed
-        plt.subplot(211)
+    .. versionchanged:: 3.8
+        In versions prior to 3.8, any preexisting Axes that overlap with the new Axes
+        beyond sharing a boundary was deleted. Deletion does not happen in more
+        recent versions anymore. Use `.Axes.remove` explicitly if needed.
 
     If you do not want this behavior, use the `.Figure.add_subplot` method
     or the `.pyplot.axes` function instead.