From 0c7f227ea53ff0525c5bc7c5819a9b6617d2028a Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Thu, 11 Apr 2024 00:04:21 +0200
Subject: [PATCH] DOC: Improve inverted axis example

Closes #28050.
---
 .../subplots_axes_and_figures/invert_axes.py  | 34 ++++++++++++-------
 1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/galleries/examples/subplots_axes_and_figures/invert_axes.py b/galleries/examples/subplots_axes_and_figures/invert_axes.py
index 15ec55d430bd..7082c54ddd7c 100644
--- a/galleries/examples/subplots_axes_and_figures/invert_axes.py
+++ b/galleries/examples/subplots_axes_and_figures/invert_axes.py
@@ -1,25 +1,33 @@
 """
-===========
-Invert Axes
-===========
+=============
+Inverted axis
+=============
 
-You can use decreasing axes by flipping the normal order of the axis
-limits
+To invert an axis, you can explicitly set inverted axis limits or you
+can invert the axis without specifying any limits using
+`.Axis.set_inverted`.
 """
 
 import matplotlib.pyplot as plt
 import numpy as np
 
-t = np.arange(0.01, 5.0, 0.01)
+t = np.arange(0.01, 4.0, 0.01)
 s = np.exp(-t)
 
-fig, ax = plt.subplots()
+fig, (ax1, ax2) = plt.subplots(1, 2)
+fig.suptitle('Should be growing...')
+
+ax1.plot(t, s)
+ax1.set_xlim(4, 0)  # decreasing time
+ax1.set_title('Inverted fixed limits')
+ax1.set_xlabel('decreasing time (s)')
+ax1.grid(True)
+
+ax2.plot(t, s)
+ax2.xaxis.set_inverted(True)  # decreasing time
+ax2.set_title('Inverted axis with autoscaling')
+ax2.set_xlabel('decreasing time (s)')
+ax2.grid(True)
 
-ax.plot(t, s)
-ax.set_xlim(5, 0)  # decreasing time
-ax.set_xlabel('decreasing time (s)')
-ax.set_ylabel('voltage (mV)')
-ax.set_title('Should be growing...')
-ax.grid(True)
 
 plt.show()