Improve documentation of FontManager

oscargus · oscargus · commit f56ea70012b5 · 2022-03-03T19:10:59.000+01:00
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -629,30 +629,31 @@ class FontProperties:
       The items may include a generic font family name, either
       'sans-serif' (default), 'serif', 'cursive', 'fantasy', or 'monospace'.
       In that case, the actual font to be used will be looked up
-      from the associated rcParam.
+      from the associated rcParam. Default: :rc:`font.family`
 
     - style: Either 'normal' (default), 'italic' or 'oblique'.
+      Default: :rc:`font.style`
 
     - variant: Either 'normal' (default) or 'small-caps'.
+      Default: :rc:`font.variant`
 
     - stretch: A numeric value in the range 0-1000 or one of
       'ultra-condensed', 'extra-condensed', 'condensed',
       'semi-condensed', 'normal' (default), 'semi-expanded', 'expanded',
-      'extra-expanded' or 'ultra-expanded'.
+      'extra-expanded' or 'ultra-expanded'. Default: :rc:`font.stretch`
 
     - weight: A numeric value in the range 0-1000 or one of
       'ultralight', 'light', 'normal' (default), 'regular', 'book', 'medium',
       'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy',
-      'extra bold', 'black'.
+      'extra bold', 'black'. Default: :rc:`font.weight`
 
     - size: Either an relative value of 'xx-small', 'x-small',
       'small', 'medium', 'large', 'x-large', 'xx-large' or an
-      absolute font size, e.g., 10 (default).
+      absolute font size, e.g., 10. Default: :rc:`font.size`
 
-    - math_fontfamily: The family of fonts used to render math text; overrides
-      :rc:`mathtext.fontset`. Supported values are the same as the ones
-      supported by :rc:`mathtext.fontset`: 'dejavusans', 'dejavuserif', 'cm',
-      'stix', 'stixsans' and 'custom'.
+    - math_fontfamily: The family of fonts used to render math text.
+      Supported values are: 'dejavusans', 'dejavuserif', 'cm',
+      'stix', 'stixsans' and 'custom'. Default: :rc:`mathtext.fontset`
 
     Alternatively, a font may be specified using the absolute path to a font
     file, by using the *fname* kwarg.  However, in this case, it is typically
@@ -807,7 +808,7 @@ def set_family(self, family):
         is CSS parlance), such as: 'serif', 'sans-serif', 'cursive',
         'fantasy', or 'monospace', a real font name or a list of real
         font names.  Real font names are not supported when
-        :rc:`text.usetex` is `True`.
+        :rc:`text.usetex` is `True`. Default: :rc:`font.family`
         """
         if family is None:
             family = rcParams['font.family']
@@ -817,7 +818,11 @@ def set_family(self, family):
 
     def set_style(self, style):
         """
-        Set the font style.  Values are: 'normal', 'italic' or 'oblique'.
+        Set the font style.
+
+        Parameters
+        ----------
+        style : {'normal', 'italic', 'oblique'}, default: :rc:`font.style`
         """
         if style is None:
             style = rcParams['font.style']
@@ -826,7 +831,11 @@ def set_style(self, style):
 
     def set_variant(self, variant):
         """
-        Set the font variant.  Values are: 'normal' or 'small-caps'.
+        Set the font variant.
+
+        Parameters
+        ----------
+        variant : {'normal', 'small-caps'}, default: :rc:`font.variant`
         """
         if variant is None:
             variant = rcParams['font.variant']
@@ -838,7 +847,8 @@ def set_weight(self, weight):
         Set the font weight.  May be either a numeric value in the
         range 0-1000 or one of 'ultralight', 'light', 'normal',
         'regular', 'book', 'medium', 'roman', 'semibold', 'demibold',
-        'demi', 'bold', 'heavy', 'extra bold', 'black'
+        'demi', 'bold', 'heavy', 'extra bold', 'black'.
+        Default: :rc:`font.weight`
         """
         if weight is None:
             weight = rcParams['font.weight']
@@ -857,6 +867,7 @@ def set_stretch(self, stretch):
         'extra-condensed', 'condensed', 'semi-condensed', 'normal',
         'semi-expanded', 'expanded', 'extra-expanded' or
         'ultra-expanded', or a numeric value in the range 0-1000.
+        Default: :rc:`font.stretch`
         """
         if stretch is None:
             stretch = rcParams['font.stretch']
@@ -871,9 +882,14 @@ def set_stretch(self, stretch):
 
     def set_size(self, size):
         """
-        Set the font size.  Either an relative value of 'xx-small',
-        'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'
-        or an absolute font size, e.g., 12.
+        Set the font size.
+
+        Parameters
+        ----------
+        size : float or {'xx-small', 'x-small', 'small', 'medium', \
+'large', 'x-large', 'xx-large'}, default: :rc:`font.size`
+            If float, the font size in points. The string values denote sizes
+            relative to the default font size.
         """
         if size is None:
             size = rcParams['font.size']
