DOC: Improve inverted axis example

Closes matplotlib#28050.

doc/api/index.rst

@@ -73,13 +73,13 @@ description of both and their recommended use cases.
 Modules
 -------
 
-Alphabetical list of modules:
+Public modules
+``````````````
 
 .. toctree::
    :maxdepth: 1
 
    matplotlib_configuration_api.rst
-   afm_api.rst
    animation_api.rst
    artist_api.rst
    axes_api.rst
@@ -98,7 +98,6 @@ Alphabetical list of modules:
    container_api.rst
    contour_api.rst
    dates_api.rst
-   docstring_api.rst
    dviread.rst
    figure_api.rst
    font_manager_api.rst
@@ -133,17 +132,27 @@ Alphabetical list of modules:
    text_api.rst
    texmanager_api.rst
    ticker_api.rst
-   tight_bbox_api.rst
-   tight_layout_api.rst
    transformations.rst
    tri_api.rst
-   type1font.rst
    typing_api.rst
    units_api.rst
    widgets_api.rst
-   _api_api.rst
-   _enums_api.rst
    toolkits/mplot3d.rst
    toolkits/axes_grid1.rst
    toolkits/axisartist.rst
    pylab.rst
+
+
+Internal modules
+````````````````
+
+.. toctree::
+   :maxdepth: 1
+
+   afm_api.rst
+   docstring_api.rst
+   tight_bbox_api.rst
+   tight_layout_api.rst
+   type1font.rst
+   _api_api.rst
+   _enums_api.rst

galleries/examples/subplots_axes_and_figures/invert_axes.py

@@ -1,25 +1,36 @@
 """
-===========
-Invert Axes
-===========
+=============
+Inverted axis
+=============
 
-You can use decreasing axes by flipping the normal order of the axis
-limits
+There are two ways to invert the direction of an axis:
+
+- If you want to set *explicit axis limits* anyway, e.g. via `.set_xlim`, you can
+  swap the limit values; e.g. ``set_xlim(4, 0)`` instead of ``set_xlim(0, 4)``.
+- Use `.Axis.set_inverted` if you only want to invert the axis *without modifying
+  the limits*, i.e. keep autoscaling behavior or other existing limits.
 """
 
 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, figsize=(6.4,  4), layout="constrained")
+fig.suptitle('Inverted axis with ...')
+
+ax1.plot(t, s)
+ax1.set_xlim(4, 0)   # inverted fixed limits
+ax1.set_title('fixed limits: set_xlim(4, 0)')
+ax1.set_xlabel('decreasing time (s)')
+ax1.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)
+# inverted axis with autoscaling
+ax2.plot(t, s)
+ax2.xaxis.set_inverted(True)  # inverted axis with autoscaling
+ax2.set_title('autoscaling: set_inverted(True)')
+ax2.set_xlabel('decreasing time (s)')
+ax2.grid(True)
 
 plt.show()