Minor improvements to Annotations Tutorial

timhoffm · timhoffm · commit ba03e4862d69 · 2022-11-01T13:03:16.000+01:00
- Move the basic text() vs. annotate() discussion to the top
- Styling in "Annotating with boxed text": move the text from
  Axes edge to center; less glaring colors
diff --git a/tutorials/text/annotations.py b/tutorials/text/annotations.py
@@ -2,7 +2,17 @@
 Annotations
 ===========
 
-Annotating text with Matplotlib.
+An annotation is a piece of text referring to a data point.  While one can
+add a text with `~.Axes.text`, this is usually not convenient, because
+the text should usually not be placed exactly at the data point, requiring
+manual calculation of the coordinates.
+
+`~.Axes.annotate` makes annotations easier because
+
+- it uses explicit coordinates for both the text and the data point. This
+  makes placing the text in a desired position easier.
+- it allows adding an arrow from the text to the data point. The arrow can be
+  styled in various ways.
 
 .. contents:: Table of Contents
    :depth: 3
@@ -13,14 +23,9 @@
 # Basic annotation
 # ----------------
 #
-# The uses of the basic :func:`~matplotlib.pyplot.text` will place text
-# at an arbitrary position on the Axes.  A common use case of text is to
-# annotate some feature of the plot, and the
-# :func:`~matplotlib.axes.Axes.annotate` method provides helper functionality
-# to make annotations easy.  In an annotation, there are two points to
-# consider: the location being annotated represented by the argument
-# *xy* and the location of the text *xytext*.  Both of these
-# arguments are ``(x, y)`` tuples:
+# In an annotation, there are two points to consider: the location being
+# annotated represented by the argument *xy* and the location of the text
+# *xytext*.  Both of these arguments are ``(x, y)`` tuples:
 
 import numpy as np
 import matplotlib.pyplot as plt
@@ -177,9 +182,10 @@
 # text:
 
 fig, ax = plt.subplots(figsize=(5, 5))
-t = ax.text(0, 0, "Direction",
+t = ax.text(0.5, 0.5, "Direction",
             ha="center", va="center", rotation=45, size=15,
-            bbox=dict(boxstyle="rarrow,pad=0.3", fc="cyan", ec="b", lw=2))
+            bbox=dict(boxstyle="rarrow,pad=0.3",
+                      fc="lightblue", ec="steelblue", lw=2))
 
 ###############################################################################
 # The arguments are the name of the box style with its attributes as
