Merge pull request #30440 from DominikStiller/relative-font-sizes

timhoffm · web-flow · commit b132b5bd1289 · 2025-08-18T00:20:00.000+02:00
Document relative font sizes
diff --git a/galleries/examples/pie_and_polar_charts/pie_features.py b/galleries/examples/pie_and_polar_charts/pie_features.py
@@ -108,7 +108,7 @@
 fig, ax = plt.subplots()
 
 ax.pie(sizes, labels=labels, autopct='%.0f%%',
-       textprops={'size': 'smaller'}, radius=0.5)
+       textprops={'size': 'small'}, radius=0.5)
 plt.show()
 
 # %%
diff --git a/galleries/users_explain/text/text_props.py b/galleries/users_explain/text/text_props.py
@@ -34,7 +34,7 @@
 picker                      [None|float|bool|callable]
 position                    (x, y)
 rotation                    [ angle in degrees | ``'vertical'`` | ``'horizontal'`` ]
-size or fontsize            [ size in points | relative size, e.g., ``'smaller'``, ``'x-large'`` ]
+        size or fontsize            [ size in points | relative size, e.g., ``'small'``, ``'x-large'`` ]
 style or fontstyle          [ ``'normal'`` | ``'italic'`` | ``'oblique'`` ]
 text                        string or anything printable with '%s' conversion
 transform                   `~matplotlib.transforms.Transform` subclass
@@ -48,6 +48,9 @@
 ==========================  ======================================================================================================================
 
 
+Text alignment
+==============
+
 You can lay out text with the alignment arguments
 ``horizontalalignment``, ``verticalalignment``, and
 ``multialignment``.  ``horizontalalignment`` controls whether the x
@@ -69,8 +72,8 @@
 import matplotlib.patches as patches
 
 # build a rectangle in axes coords
-left, width = .25, .5
-bottom, height = .25, .5
+left, width = 0.25, 0.5
+bottom, height = 0.25, 0.5
 right = left + width
 top = bottom + height
 
@@ -144,6 +147,25 @@
 plt.show()
 
 # %%
+# Relative font sizes
+# ===================
+#
+# Font sizes can be specified in points, or as a string that indicates the size
+# relative to the default font size. The following are valid values for relative font sizes:
+#
+# ====================    ================================
+# Relative font size      Scaling of default font size
+# ====================    ================================
+# xx-small                0.579
+# x-small                 0.694
+# small                   0.833
+# medium                  1.000
+# large                   1.200
+# x-large                 1.440
+# xx-large                1.728
+# ====================    ================================
+#
+#
 # ==============
 #  Default Font
 # ==============
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1024,7 +1024,7 @@ def rc(group, **kwargs):
 
       font = {'family' : 'monospace',
               'weight' : 'bold',
-              'size'   : 'larger'}
+              'size'   : 'large'}
       rc('font', **font)  # pass in the font dict as kwargs
 
     This enables you to easily switch between several configurations.  Use
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -76,7 +76,7 @@ def clabel(self, levels=None, *,
             a subset of ``cs.levels``. If not given, all levels are labeled.
 
         fontsize : str or float, default: :rc:`font.size`
-            Size in points or relative size e.g., 'smaller', 'x-large'.
+            Size in points or relative size e.g., 'small', 'x-large'.
             See `.Text.set_size` for accepted string values.
 
         colors : :mpltype:`color` or colors or None, default: None
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -243,7 +243,7 @@
 ##
 ## The font.variant property has two values: normal or small-caps.  For
 ## TrueType fonts, which are scalable fonts, small-caps is equivalent
-## to using a font size of 'smaller', or about 83 % of the current font
+## to using a font size of 'small', or about 83 % of the current font
 ## size.
 ##
 ## The font.weight property has effectively 13 values: normal, bold,
@@ -263,7 +263,7 @@
 ## special text sizes tick labels, axes, labels, title, etc., see the rc
 ## settings for axes and ticks.  Special text sizes can be defined
 ## relative to font.size, using the following values: xx-small, x-small,
-## small, medium, large, x-large, xx-large, larger, or smaller
+## small, medium, large, x-large, xx-large
 
 #font.family:  sans-serif
 #font.style:   normal
diff --git a/lib/matplotlib/mpl-data/stylelib/classic.mplstyle b/lib/matplotlib/mpl-data/stylelib/classic.mplstyle
@@ -61,7 +61,7 @@ hist.bins              : 10
 #
 # The font.variant property has two values: normal or small-caps.  For
 # TrueType fonts, which are scalable fonts, small-caps is equivalent
-# to using a font size of 'smaller', or about 83% of the current font
+# to using a font size of 'small', or about 83% of the current font
 # size.
 #
 # The font.weight property has effectively 13 values: normal, bold,
@@ -86,7 +86,7 @@ font.stretch        : normal
 # special text sizes tick labels, axes, labels, title, etc, see the rc
 # settings for axes and ticks. Special text sizes can be defined
 # relative to font.size, using the following values: xx-small, x-small,
-# small, medium, large, x-large, xx-large, larger, or smaller
+# small, medium, large, x-large, xx-large
 font.size           : 12.0
 font.serif     : DejaVu Serif, New Century Schoolbook, Century Schoolbook L, Utopia, ITC Bookman, Bookman, Nimbus Roman No9 L, Times New Roman, Times, Palatino, Charter, serif
 font.sans-serif: DejaVu Sans, Lucida Grande, Verdana, Geneva, Lucid, Arial, Helvetica, Avant Garde, sans-serif
