write addfont example (#24866)

saranti · web-flow · commit f2100d5e67d1 · 2023-01-30T16:40:10.000-08:00
* write addfont example
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -7,6 +7,8 @@
 system font path that matches the specified `FontProperties`
 instance.  The `FontManager` also handles Adobe Font Metrics
 (AFM) font files for use by the PostScript backend.
+The `FontManager.addfont` function adds a custom font from a file without
+installing it into your operating system.
 
 The design is based on the `W3C Cascading Style Sheet, Level 1 (CSS1)
 font specification <http://www.w3.org/TR/1998/REC-CSS2-19980512/>`_.
@@ -980,6 +982,27 @@ class FontManager:
     method does a nearest neighbor search to find the font that most closely
     matches the specification.  If no good enough match is found, the default
     font is returned.
+
+    Fonts added with the `FontManager.addfont` method will not persist in the
+    cache; therefore, `addfont` will need to be called every time Matplotlib is
+    imported. This method should only be used if and when a font cannot be
+    installed on your operating system by other means.
+
+    Notes
+    -----
+    The `FontManager.addfont` method must be called on the global `FontManager`
+    instance.
+
+    Example usage::
+
+        import matplotlib.pyplot as plt
+        from matplotlib import font_manager
+
+        font_dirs = ["/resources/fonts"]  # The path to the custom font file.
+        font_files = font_manager.findSystemFonts(fontpaths=font_dirs)
+
+        for font_file in font_files:
+            font_manager.fontManager.addfont(font_file)
     """
     # Increment this version number whenever the font cache data
     # format or behavior has changed and requires an existing font
@@ -1030,6 +1053,12 @@ def addfont(self, path):
         Parameters
         ----------
         path : str or path-like
+
+        Notes
+        -----
+        This method is useful for adding a custom font without installing it in
+        your operating system. See the `FontManager` singleton instance for
+        usage and caveats about this function.
         """
         # Convert to string in case of a path as
         # afmFontProperty and FT2Font expect this
