Backport PR #12676: Doc: document textpath module (#12714)

meeseeksmachine · timhoffm · commit 4ddf0021f2d8 · 2018-11-02T20:47:05.000+01:00
diff --git a/doc/api/api_overview.rst b/doc/api/api_overview.rst
@@ -38,7 +38,8 @@ Further reading:
 - `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
   plotting functions.
 - Most of the :ref:`examples <examples-index>` use the object-oriented approach
-  (except for the pyplot section).
+  (except for the pyplot section)
+- The list of :doc:`matplotlib modules </api/index>`.
 
 
 The pylab API (disapproved)
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -55,6 +55,7 @@ Modules
    style_api.rst
    table_api.rst
    text_api.rst
+   textpath_api.rst
    ticker_api.rst
    tight_layout_api.rst
    transformations.rst
diff --git a/doc/api/textpath_api.rst b/doc/api/textpath_api.rst
@@ -0,0 +1,12 @@
+********
+textpath
+********
+
+
+:mod:`matplotlib.textpath`
+==========================
+
+.. automodule:: matplotlib.textpath
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/examples/text_labels_and_annotations/demo_text_path.py b/examples/text_labels_and_annotations/demo_text_path.py
@@ -3,6 +3,9 @@
 Demo Text Path
 ==============
 
+Use a text as `Path`. The tool that allows for such conversion is a
+`~matplotlib.textpath.TextPath`. The resulting path can be employed
+e.g. as a clip path for an image.
 """
 
 import matplotlib.pyplot as plt
diff --git a/lib/matplotlib/textpath.py b/lib/matplotlib/textpath.py
@@ -104,22 +104,47 @@ def get_text_width_height_descent(self, s, prop, ismath):
 
     def get_text_path(self, prop, s, ismath=False, usetex=False):
         """
-        convert text *s* to path (a tuple of vertices and codes for
+        Convert text *s* to path (a tuple of vertices and codes for
         matplotlib.path.Path).
 
-        *prop*
-          font property
+        Parameters
+        ----------
 
-        *s*
-          text to be converted
+        prop : `matplotlib.font_manager.FontProperties` instance
+            The font properties for the text.
 
-        *usetex*
-          If True, use matplotlib usetex mode.
+        s : str
+            The text to be converted.
 
-        *ismath*
-          If True, use mathtext parser. Effective only if usetex == False.
+        usetex : bool, optional
+            Whether to use tex rendering. Defaults to ``False``.
 
+        ismath : bool, optional
+            If True, use mathtext parser. Effective only if
+            ``usetex == False``.
 
+        Returns
+        -------
+
+        verts, codes : tuple of lists
+            *verts*  is a list of numpy arrays containing the x and y
+            coordinates of the vertices. *codes* is a list of path codes.
+
+        Examples
+        --------
+
+        Create a list of vertices and codes from a text, and create a `Path`
+        from those::
+
+            from matplotlib.path import Path
+            from matplotlib.textpath import TextToPath
+            from matplotlib.font_manager import FontProperties
+
+            fp = FontProperties(family="Humor Sans", style="italic")
+            verts, codes = TextToPath().get_text_path(fp, "ABC")
+            path = Path(verts, codes, closed=False)
+
+        Also see `TextPath` for a more direct way to create a path from a text.
         """
         if not usetex:
             if not ismath:
@@ -392,16 +417,49 @@ class TextPath(Path):
     def __init__(self, xy, s, size=None, prop=None,
                  _interpolation_steps=1, usetex=False,
                  *kl, **kwargs):
-        """
-        Create a path from the text. No support for TeX yet. Note that
-        it simply is a path, not an artist. You need to use the
-        PathPatch (or other artists) to draw this path onto the
-        canvas.
+        r"""
+        Create a path from the text. Note that it simply is a path,
+        not an artist. You need to use the `~.PathPatch` (or other artists)
+        to draw this path onto the canvas.
+
+        Parameters
+        ----------
+
+        xy : tuple or array of two float values
+            Position of the text. For no offset, use ``xy=(0, 0)``.
+
+        s : str
+            The text to convert to a path.
+
+        size : float, optional
+            Font size in points. Defaults to the size specified via the font
+            properties *prop*.
+
+        prop : `matplotlib.font_manager.FontProperties`, optional
+            Font property. If not provided, will use a default
+            ``FontProperties`` with parameters from the
+            :ref:`rcParams <matplotlib-rcparams>`.
+
+        _interpolation_steps : integer, optional
+            (Currently ignored)
+
+        usetex : bool, optional
+            Whether to use tex rendering. Defaults to ``False``.
+
+        Examples
+        --------
+
+        The following creates a path from the string "ABC" with Helvetica
+        font face; and another path from the latex fraction 1/2::
+
+            from matplotlib.textpath import TextPath
+            from matplotlib.font_manager import FontProperties
+
+            fp = FontProperties(family="Helvetica", style="italic")
+            path1 = TextPath((12,12), "ABC", size=12, prop=fp)
+            path2 = TextPath((0,0), r"$\frac{1}{2}$", size=12, usetex=True)
 
-        xy : position of the text.
-        s : text
-        size : font size
-        prop : font property
+        Also see :doc:`/gallery/text_labels_and_annotations/demo_text_path`.
         """
 
         if prop is None:
