Merge pull request #13839 from meeseeksmachine/auto-backport-of-pr-13815-on-v3.1.x

tacaswell · web-flow · commit 38b94434be23 · 2019-04-02T09:10:48.000-04:00
Backport PR #13815 on branch v3.1.x (Numpydocify FontManager.findfont())
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -1179,28 +1179,53 @@ def score_size(self, size1, size2):
     def findfont(self, prop, fontext='ttf', directory=None,
                  fallback_to_default=True, rebuild_if_missing=True):
         """
-        Search the font list for the font that most closely matches
-        the :class:`FontProperties` *prop*.
-
-        :meth:`findfont` performs a nearest neighbor search.  Each
-        font is given a similarity score to the target font
-        properties.  The first font with the highest score is
-        returned.  If no matches below a certain threshold are found,
-        the default font (usually DejaVu Sans) is returned.
-
-        `directory`, is specified, will only return fonts from the
-        given directory (or subdirectory of that directory).
+        Find a font that most closely matches the given font properties.
+
+        Parameters
+        ----------
+        prop : str or `~matplotlib.font_manager.FontProperties`
+            The font properties to search for. This can be either a
+            `.FontProperties` object or a string defining a
+            `fontconfig patterns`_.
+
+        fontext : {'ttf', 'afm'}, optional, default: 'ttf'
+            The extension of the font file:
+
+            - 'ttf': TrueType and OpenType fonts (.ttf, .ttc, .otf)
+            - 'afm': Adobe Font Metrics (.afm)
+
+        directory : str, optional
+            If given, only search this directory and its subdirectories.
+        fallback_to_default : bool
+            If True, will fallback to the default font family (usually
+            "DejaVu Sans" or "Helvetica") if the first lookup hard-fails.
+        rebuild_if_missing : bool
+            Whether to rebuild the font cache and search again if no match
+            is found.
+
+        Returns
+        -------
+        fontfile : str
+            The filename of the best matching font.
+
+        Notes
+        -----
+        This performs a nearest neighbor search.  Each font is given a
+        similarity score to the target font properties.  The first font with
+        the highest score is returned.  If no matches below a certain
+        threshold are found, the default font (usually DejaVu Sans) is
+        returned.
 
         The result is cached, so subsequent lookups don't have to
         perform the O(n) nearest neighbor search.
 
-        If `fallback_to_default` is True, will fallback to the default
-        font family (usually "DejaVu Sans" or "Helvetica") if
-        the first lookup hard-fails.
-
         See the `W3C Cascading Style Sheet, Level 1
         <http://www.w3.org/TR/1998/REC-CSS2-19980512/>`_ documentation
         for a description of the font finding algorithm.
+
+        .. _fontconfig patterns:
+           https://www.freedesktop.org/software/fontconfig/fontconfig-user.html
+
         """
         # Pass the relevant rcParams (and the font manager, as `self`) to
         # _findfont_cached so to prevent using a stale cache entry after an
