matplotlib
diff --git a/‎examples/text_labels_and_annotations/text_alignment.py
Lines changed: 40 additions & 5 deletions b/‎examples/text_labels_and_annotations/text_alignment.py
Lines changed: 40 additions & 5 deletions
diff --git a/‎lib/matplotlib/text.py
Lines changed: 13 additions & 4 deletions b/‎lib/matplotlib/text.py
Lines changed: 13 additions & 4 deletions
@@ -1,12 +1,47 @@
 """
-===================
-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.77]
+    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=40)
+    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()
 
@@ -132,6 +132,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 ``horizontalalingment`` (default: 'left') and ``verticalalignment``
+        (default: 'bottom'). See also
+        :doc:`/gallery/text_labels_and_annotations/text_alignment`.
+
         Valid keyword arguments are:
 
         %(Text:kwdoc)s
@@ -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
@@ -1194,11 +1201,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'],