From 982f6bda61ca8d05af1858002829b3504eabea29 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Thu, 29 Jun 2023 09:29:01 +0200
Subject: [PATCH] Rewrite Tick formatters example

- Collect all relevant descriptions in the summary text at the top
- Merge everything into one figure. The code should be mostly
  irrelevant for the example. The figure can serve as a
  standalone reference.
---
 galleries/examples/ticks/dollar_ticks.py    |  39 -------
 galleries/examples/ticks/tick-formatters.py | 123 ++++++++------------
 lib/matplotlib/ticker.py                    |   2 +
 3 files changed, 48 insertions(+), 116 deletions(-)
 delete mode 100644 galleries/examples/ticks/dollar_ticks.py

diff --git a/galleries/examples/ticks/dollar_ticks.py b/galleries/examples/ticks/dollar_ticks.py
deleted file mode 100644
index 4186e8c369e9..000000000000
--- a/galleries/examples/ticks/dollar_ticks.py
+++ /dev/null
@@ -1,39 +0,0 @@
-"""
-============
-Dollar ticks
-============
-
-Use a `~.ticker.FormatStrFormatter` to prepend dollar signs on y-axis labels.
-
-.. redirect-from:: /gallery/pyplots/dollar_ticks
-"""
-import matplotlib.pyplot as plt
-import numpy as np
-
-# Fixing random state for reproducibility
-np.random.seed(19680801)
-
-fig, ax = plt.subplots()
-ax.plot(100*np.random.rand(20))
-
-# Use automatic StrMethodFormatter
-ax.yaxis.set_major_formatter('${x:1.2f}')
-
-ax.yaxis.set_tick_params(which='major', labelcolor='green',
-                         labelleft=False, labelright=True)
-
-plt.show()
-
-
-# %%
-#
-# .. admonition:: References
-#
-#    The use of the following functions, methods, classes and modules is shown
-#    in this example:
-#
-#    - `matplotlib.pyplot.subplots`
-#    - `matplotlib.axis.Axis.set_major_formatter`
-#    - `matplotlib.axis.Axis.set_tick_params`
-#    - `matplotlib.axis.Tick`
-#    - `matplotlib.ticker.StrMethodFormatter`
diff --git a/galleries/examples/ticks/tick-formatters.py b/galleries/examples/ticks/tick-formatters.py
index 45f59d0b48c2..543aec57e4d2 100644
--- a/galleries/examples/ticks/tick-formatters.py
+++ b/galleries/examples/ticks/tick-formatters.py
@@ -8,6 +8,23 @@
 
 This example illustrates the usage and effect of the most common formatters.
 
+The tick format is configured via the function `~.Axis.set_major_formatter`
+or `~.Axis.set_minor_formatter`. It accepts:
+
+- a format string, which implicitly creates a `.StrMethodFormatter`.
+- a function,  implicitly creates a `.FuncFormatter`.
+- an instance of a `.Formatter` subclass. The most common are
+
+  - `.NullFormatter`: No labels on the ticks.
+  - `.StrMethodFormatter`: Use string `str.format` method.
+  - `.FormatStrFormatter`: Use %-style formatting.
+  - `.FuncFormatter`: Define labels through a function.
+  - `.FixedFormatter`: Set the label strings explicitly.
+  - `.ScalarFormatter`: Default formatter for scalars: auto-pick the format string.
+  - `.PercentFormatter`: Format labels as a percentage.
+
+  See :ref:`formatters` for a complete list.
+
 """
 
 import matplotlib.pyplot as plt
@@ -34,103 +51,55 @@ def setup(ax, title):
             fontsize=14, fontname='Monospace', color='tab:blue')
 
 
-# %%
-# Tick formatters can be set in one of two ways, either by passing a ``str``
-# or function to `~.Axis.set_major_formatter` or `~.Axis.set_minor_formatter`,
-# or by creating an instance of one of the various `~.ticker.Formatter` classes
-# and providing that to `~.Axis.set_major_formatter` or
-# `~.Axis.set_minor_formatter`.
-#
-# The first two examples directly pass a ``str`` or function.
+fig = plt.figure(figsize=(8, 8), layout='constrained')
+fig0, fig1, fig2 = fig.subfigures(3, height_ratios=[1.5, 1.5, 7.5])
 
-fig0, axs0 = plt.subplots(2, 1, figsize=(8, 2))
-fig0.suptitle('Simple Formatting')
+fig0.suptitle('String Formatting', fontsize=16, x=0, ha='left')
+ax0 = fig0.subplots()
 
-# A ``str``, using format string function syntax, can be used directly as a
-# formatter.  The variable ``x`` is the tick value and the variable ``pos`` is
-# tick position.  This creates a StrMethodFormatter automatically.
-setup(axs0[0], title="'{x} km'")
-axs0[0].xaxis.set_major_formatter('{x} km')
+setup(ax0, title="'{x} km'")
+ax0.xaxis.set_major_formatter('{x} km')
 
-# A function can also be used directly as a formatter. The function must take
-# two arguments: ``x`` for the tick value and ``pos`` for the tick position,
-# and must return a ``str``. This creates a FuncFormatter automatically.
-setup(axs0[1], title="lambda x, pos: str(x-5)")
-axs0[1].xaxis.set_major_formatter(lambda x, pos: str(x-5))
 
-fig0.tight_layout()
+fig1.suptitle('Function Formatting', fontsize=16, x=0, ha='left')
+ax1 = fig1.subplots()
 
+setup(ax1, title="def(x, pos): return str(x-5)")
+ax1.xaxis.set_major_formatter(lambda x, pos: str(x-5))
 
-# %%
-# The remaining examples use `.Formatter` objects.
 
-fig1, axs1 = plt.subplots(7, 1, figsize=(8, 6))
-fig1.suptitle('Formatter Object Formatting')
+fig2.suptitle('Formatter Object Formatting', fontsize=16, x=0, ha='left')
+axs2 = fig2.subplots(7, 1)
 
-# Null formatter
-setup(axs1[0], title="NullFormatter()")
-axs1[0].xaxis.set_major_formatter(ticker.NullFormatter())
+setup(axs2[0], title="NullFormatter()")
+axs2[0].xaxis.set_major_formatter(ticker.NullFormatter())
 
-# StrMethod formatter
-setup(axs1[1], title="StrMethodFormatter('{x:.3f}')")
-axs1[1].xaxis.set_major_formatter(ticker.StrMethodFormatter("{x:.3f}"))
+setup(axs2[1], title="StrMethodFormatter('{x:.3f}')")
+axs2[1].xaxis.set_major_formatter(ticker.StrMethodFormatter("{x:.3f}"))
 
+setup(axs2[2], title="FormatStrFormatter('#%d')")
+axs2[2].xaxis.set_major_formatter(ticker.FormatStrFormatter("#%d"))
 
-# FuncFormatter can be used as a decorator
-@ticker.FuncFormatter
-def major_formatter(x, pos):
+
+def fmt_two_digits(x, pos):
     return f'[{x:.2f}]'
 
 
-setup(axs1[2], title='FuncFormatter("[{:.2f}]".format)')
-axs1[2].xaxis.set_major_formatter(major_formatter)
+setup(axs2[3], title='FuncFormatter("[{:.2f}]".format)')
+axs2[3].xaxis.set_major_formatter(ticker.FuncFormatter(fmt_two_digits))
 
-# Fixed formatter
-setup(axs1[3], title="FixedFormatter(['A', 'B', 'C', ...])")
+setup(axs2[4], title="FixedFormatter(['A', 'B', 'C', 'D', 'E', 'F'])")
 # FixedFormatter should only be used together with FixedLocator.
 # Otherwise, one cannot be sure where the labels will end up.
 positions = [0, 1, 2, 3, 4, 5]
 labels = ['A', 'B', 'C', 'D', 'E', 'F']
-axs1[3].xaxis.set_major_locator(ticker.FixedLocator(positions))
-axs1[3].xaxis.set_major_formatter(ticker.FixedFormatter(labels))
-
-# Scalar formatter
-setup(axs1[4], title="ScalarFormatter()")
-axs1[4].xaxis.set_major_formatter(ticker.ScalarFormatter(useMathText=True))
+axs2[4].xaxis.set_major_locator(ticker.FixedLocator(positions))
+axs2[4].xaxis.set_major_formatter(ticker.FixedFormatter(labels))
 
-# FormatStr formatter
-setup(axs1[5], title="FormatStrFormatter('#%d')")
-axs1[5].xaxis.set_major_formatter(ticker.FormatStrFormatter("#%d"))
+setup(axs2[5], title="ScalarFormatter()")
+axs2[5].xaxis.set_major_formatter(ticker.ScalarFormatter(useMathText=True))
 
-# Percent formatter
-setup(axs1[6], title="PercentFormatter(xmax=5)")
-axs1[6].xaxis.set_major_formatter(ticker.PercentFormatter(xmax=5))
+setup(axs2[6], title="PercentFormatter(xmax=5)")
+axs2[6].xaxis.set_major_formatter(ticker.PercentFormatter(xmax=5))
 
-fig1.tight_layout()
 plt.show()
-
-
-# %%
-#
-# .. admonition:: References
-#
-#    The use of the following functions, methods, classes and modules is shown
-#    in this example:
-#
-#    - `matplotlib.pyplot.subplots`
-#    - `matplotlib.axes.Axes.text`
-#    - `matplotlib.axis.Axis.set_major_formatter`
-#    - `matplotlib.axis.Axis.set_major_locator`
-#    - `matplotlib.axis.Axis.set_minor_locator`
-#    - `matplotlib.axis.XAxis.set_ticks_position`
-#    - `matplotlib.axis.YAxis.set_ticks_position`
-#    - `matplotlib.ticker.FixedFormatter`
-#    - `matplotlib.ticker.FixedLocator`
-#    - `matplotlib.ticker.FormatStrFormatter`
-#    - `matplotlib.ticker.FuncFormatter`
-#    - `matplotlib.ticker.MultipleLocator`
-#    - `matplotlib.ticker.NullFormatter`
-#    - `matplotlib.ticker.NullLocator`
-#    - `matplotlib.ticker.PercentFormatter`
-#    - `matplotlib.ticker.ScalarFormatter`
-#    - `matplotlib.ticker.StrMethodFormatter`
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
index 1aea4e946144..3c49f3a07700 100644
--- a/lib/matplotlib/ticker.py
+++ b/lib/matplotlib/ticker.py
@@ -77,6 +77,8 @@
         ax.xaxis.set_major_locator(MultipleLocator(5))
         ax2.xaxis.set_major_locator(MultipleLocator(5))
 
+.. _formatters:
+
 Tick formatting
 ---------------