From c0cb163c627fe52e38311954226e3349f34f6914 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Thu, 11 Nov 2021 00:32:34 +0100
Subject: [PATCH] Document text alignment

Closes #21571.
---
 .../text_alignment.py                         | 46 +++++++++++++++++--
 lib/matplotlib/text.py                        | 17 +++++--
 2 files changed, 54 insertions(+), 9 deletions(-)

diff --git a/examples/text_labels_and_annotations/text_alignment.py b/examples/text_labels_and_annotations/text_alignment.py
index 6ad79fb18fb8..a12002972233 100644
--- a/examples/text_labels_and_annotations/text_alignment.py
+++ b/examples/text_labels_and_annotations/text_alignment.py
@@ -1,12 +1,48 @@
 """
-===================
-Precise text layout
-===================
+==============
+Text alignment
+==============
+
+Texts are aligned relative to their anchor point depending on the properties
+``horizontalalignment`` and ``verticalalignment``.
+
+.. plot::
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    y = [0.22, 0.34, 0.5, 0.56, 0.78]
+    x = [0.17, 0.5, 0.855]
+    X, Y = np.meshgrid(x, y)
+
+    fig, ax = plt.subplots(figsize=(6, 4), dpi=100)
+    ax.set(xlim=(0, 1), ylim=(0, 1), xticks=[], yticks=[])
+    ax.spines[:].set_visible(False)
+    ax.text(0.5, 0.5, 'plot', fontsize=128, ha='center', va='center', zorder=1)
+    ax.hlines(y, x[0], x[-1], color='grey')
+    ax.vlines(x, y[0], y[-1], color='grey')
+    ax.plot(X.ravel(), Y.ravel(), 'o')
+    pad_x = 0.02
+    pad_y = 0.04
+    ax.text(x[0] - pad_x, y[0], 'bottom', ha='right', va='center')
+    ax.text(x[0] - pad_x, y[1], 'baseline', ha='right', va='center')
+    ax.text(x[0] - pad_x, y[2], 'center', ha='right', va='center')
+    ax.text(x[0] - pad_x, y[3], 'center_baseline', ha='right', va='center')
+    ax.text(x[0] - pad_x, y[4], 'top', ha='right', va='center')
+    ax.text(x[0], y[0] - pad_y, 'left', ha='center', va='top')
+    ax.text(x[1], y[0] - pad_y, 'center', ha='center', va='top')
+    ax.text(x[2], y[0] - pad_y, 'right', ha='center', va='top')
+    ax.set_xlabel('horizontalalignment', fontsize=14)
+    ax.set_ylabel('verticalalignment', fontsize=14, labelpad=35)
+    ax.set_title(
+        'Relative position of text anchor point depending on alignment')
+    plt.show()
 
-You can precisely layout text in data or axes coordinates.  This example shows
-you some of the alignment and rotation specifications for text layout.
 """
 
+#############################################################################
+# The following plot uses this to align text relative to a plotted rectangle.
+
 import matplotlib.pyplot as plt
 
 fig, ax = plt.subplots()
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
index be26b14d0026..e607c04e38f0 100644
--- a/lib/matplotlib/text.py
+++ b/lib/matplotlib/text.py
@@ -148,6 +148,11 @@ def __init__(self,
         """
         Create a `.Text` instance at *x*, *y* with string *text*.
 
+        The text is aligned relative to the anchor point (*x*, *y*) according
+        to ``horizontalalignment`` (default: 'left') and ``verticalalignment``
+        (default: 'bottom'). See also
+        :doc:`/gallery/text_labels_and_annotations/text_alignment`.
+
         While Text accepts the 'label' keyword argument, by default it is not
         added to the handles of a legend.
 
@@ -956,11 +961,13 @@ def set_color(self, color):
 
     def set_horizontalalignment(self, align):
         """
-        Set the horizontal alignment to one of
+        Set the horizontal alignment relative to the anchor point.
+
+        See also :doc:`/gallery/text_labels_and_annotations/text_alignment`.
 
         Parameters
         ----------
-        align : {'center', 'right', 'left'}
+        align : {'left', 'center', 'right'}
         """
         _api.check_in_list(['center', 'right', 'left'], align=align)
         self._horizontalalignment = align
@@ -1202,11 +1209,13 @@ def set_transform_rotates_text(self, t):
 
     def set_verticalalignment(self, align):
         """
-        Set the vertical alignment.
+        Set the vertical alignment relative to the anchor point.
+
+        See also :doc:`/gallery/text_labels_and_annotations/text_alignment`.
 
         Parameters
         ----------
-        align : {'center', 'top', 'bottom', 'baseline', 'center_baseline'}
+        align : {'bottom', 'baseline', 'center', 'center_baseline', 'top'}
         """
         _api.check_in_list(
             ['top', 'bottom', 'center', 'baseline', 'center_baseline'],