From af8782058ad6669f5091e09ee2a13566bbcf60f4 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sun, 6 Nov 2022 09:54:41 +0100
Subject: [PATCH] Backport PR #24377: DOC: Cleanup Spine placement example

---
 examples/spines/spine_placement_demo.py | 60 +++++++++++--------------
 lib/matplotlib/spines.py                |  8 +++-
 2 files changed, 32 insertions(+), 36 deletions(-)

diff --git a/examples/spines/spine_placement_demo.py b/examples/spines/spine_placement_demo.py
index d433236657f9..7d14d854f41a 100644
--- a/examples/spines/spine_placement_demo.py
+++ b/examples/spines/spine_placement_demo.py
@@ -1,9 +1,9 @@
 """
 ===============
-Spine Placement
+Spine placement
 ===============
 
-Adjusting the location and appearance of axis spines.
+The position of the axis spines can be influenced using `~.Spine.set_position`.
 
 Note: If you want to obtain arrow heads at the ends of the axes, also check
 out the :doc:`/gallery/spines/centered_spines_with_arrows` example.
@@ -14,49 +14,41 @@
 
 ###############################################################################
 
-fig = plt.figure()
-x = np.linspace(-np.pi, np.pi, 100)
+x = np.linspace(0, 2*np.pi, 100)
 y = 2 * np.sin(x)
 
-ax = fig.add_subplot(2, 2, 1)
-ax.set_title('centered spines')
+fig, ax_dict = plt.subplot_mosaic(
+    [['center', 'zero'],
+     ['axes', 'data']]
+)
+fig.suptitle('Spine positions')
+
+
+ax = ax_dict['center']
+ax.set_title("'center'")
 ax.plot(x, y)
-ax.spines.left.set_position('center')
-ax.spines.right.set_color('none')
-ax.spines.bottom.set_position('center')
-ax.spines.top.set_color('none')
-ax.xaxis.set_ticks_position('bottom')
-ax.yaxis.set_ticks_position('left')
+ax.spines[['left', 'bottom']].set_position('center')
+ax.spines[['top', 'right']].set_visible(False)
 
-ax = fig.add_subplot(2, 2, 2)
-ax.set_title('zeroed spines')
+ax = ax_dict['zero']
+ax.set_title("'zero'")
 ax.plot(x, y)
-ax.spines.left.set_position('zero')
-ax.spines.right.set_color('none')
-ax.spines.bottom.set_position('zero')
-ax.spines.top.set_color('none')
-ax.xaxis.set_ticks_position('bottom')
-ax.yaxis.set_ticks_position('left')
+ax.spines[['left', 'bottom']].set_position('zero')
+ax.spines[['top', 'right']].set_visible(False)
 
-ax = fig.add_subplot(2, 2, 3)
-ax.set_title('spines at axes (0.6, 0.1)')
+ax = ax_dict['axes']
+ax.set_title("'axes' (0.2, 0.2)")
 ax.plot(x, y)
-ax.spines.left.set_position(('axes', 0.6))
-ax.spines.right.set_color('none')
-ax.spines.bottom.set_position(('axes', 0.1))
-ax.spines.top.set_color('none')
-ax.xaxis.set_ticks_position('bottom')
-ax.yaxis.set_ticks_position('left')
+ax.spines.left.set_position(('axes', 0.2))
+ax.spines.bottom.set_position(('axes', 0.2))
+ax.spines[['top', 'right']].set_visible(False)
 
-ax = fig.add_subplot(2, 2, 4)
-ax.set_title('spines at data (1, 2)')
+ax = ax_dict['data']
+ax.set_title("'data' (1, 2)")
 ax.plot(x, y)
 ax.spines.left.set_position(('data', 1))
-ax.spines.right.set_color('none')
 ax.spines.bottom.set_position(('data', 2))
-ax.spines.top.set_color('none')
-ax.xaxis.set_ticks_position('bottom')
-ax.yaxis.set_ticks_position('left')
+ax.spines[['top', 'right']].set_visible(False)
 
 ###############################################################################
 # Define a method that adjusts the location of the axis spines
diff --git a/lib/matplotlib/spines.py b/lib/matplotlib/spines.py
index 3395c220a74e..44b136d02f3f 100644
--- a/lib/matplotlib/spines.py
+++ b/lib/matplotlib/spines.py
@@ -302,8 +302,12 @@ def set_position(self, position):
 
         Additionally, shorthand notations define a special positions:
 
-        * 'center' -> ('axes', 0.5)
-        * 'zero' -> ('data', 0.0)
+        * 'center' -> ``('axes', 0.5)``
+        * 'zero' -> ``('data', 0.0)``
+
+        Examples
+        --------
+        :doc:`/gallery/spines/spine_placement_demo`
         """
         if position in ('center', 'zero'):  # special positions
             pass