8000 Backport PR #12676: Doc: document textpath module (#12714) · matplotlib/matplotlib@4ddf002 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4ddf002

Browse files
meeseeksmachinetimhoffm
meeseeksmachine
authored and
timhoffm
committed
Backport PR #12676: Doc: document textpath module (#12714)
1 parent ef6f479 commit 4ddf002

File tree

5 files changed

+94
-19
lines changed

5 files changed

+94
-19
lines changed

‎doc/api/api_overview.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ Further reading:
3838
- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
3939
plotting functions.
4040
- Most of the :ref:`examples <examples-index>` use the object-oriented approach
41-
(except for the pyplot section).
41+
(except for the pyplot section)
42+
- The list of :doc:`matplotlib modules </api/index>`.
4243

4344

4445
The pylab API (disapproved)

‎doc/api/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ Modules
5555
style_api.rst
5656
table_api.rst
5757
text_api.rst
58+
textpath_api.rst
5859
ticker_api.rst
5960
tight_layout_api.rst
6061
transformations.rst

‎doc/api/textpath_api.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
********
2+
textpath
3+
********
4+
5+
6+
:mod:`matplotlib.textpath`
7+
==========================
8+
9+
.. automodule:: matplotlib.textpath
10+
:members:
11+
:undoc-members:
12+
:show-inheritance:

‎examples/text_labels_and_annotations/demo_text_path.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
Demo Text Path
44
==============
55
6+
Use a text as `Path`. The tool that allows for such conversion is a
7+
`~matplotlib.textpath.TextPath`. The resulting path can be employed
8+
e.g. as a clip path for an image.
69
"""
710

811
import matplotlib.pyplot as plt

‎lib/matplotlib/textpath.py

Lines changed: 76 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -104,22 +104,47 @@ def get_text_width_height_descent(self, s, prop, ismath):
104104

105105
def get_text_path(self, prop, s, ismath=False, usetex=False):
106106
"""
107-
convert text *s* to path (a tuple of vertices and codes for
107+
Convert text *s* to path (a tuple of vertices and codes for
108108
matplotlib.path.Path).
109109
110-
*prop*
111-
font property
110+
Parameters
111+
----------
112112
113-
*s*
114-
text to be converted
113+
prop : `matplotlib.font_manager.FontProperties` instance
114+
The font properties for the text.
115115
116-
*usetex*
117-
If True, use matplotlib usetex mode.
116+
s : str
117+
The text to be converted.
118118
119-
*ismath*
120-
If True, use mathtext parser. Effective only if usetex == False.
119+
usetex : bool, optional
120+
Whether to use tex rendering. Defaults to ``False``.
121121
122+
ismath : bool, optional
123+
If True, use mathtext parser. Effective only if
124+
``usetex == False``.
122125
126+
Returns
127+
-------
128+
129+
verts, codes : tuple of lists
130+
*verts* is a list of numpy arrays containing the x and y
131+
coordinates of the vertices. *codes* is a list of path codes.
132+
133+
Examples
134+
--------
135+
136+
Create a list of vertices and codes from a text, and create a `Path`
137+
from those::
138+
139+
from matplotlib.path import Path
140+
from matplotlib.textpath import TextToPath
141+
from matplotlib.font_manager import FontProperties
142+
143+
fp = FontProperties(family="Humor Sans", style="italic")
144+
verts, codes = TextToPath().get_text_path(fp, "ABC")
145+
path = Path(verts, codes, closed=False)
146+
147+
Also see `TextPath` for a more direct way to create a path from a text.
123148
"""
124149
if not usetex:
125150
if not ismath:
@@ -392,16 +417,49 @@ class TextPath(Path):
392417
def __init__(self, xy, s, size=None, prop=None,
393418
_interpolation_steps=1, usetex=False,
394419
*kl, **kwargs):
395-
"""
396-
Create a path from the text. No support for TeX yet. Note that
397-
it simply is a path, not an artist. You need to use the
398-
PathPatch (or other artists) to draw this path onto the
399-
canvas.
420+
r"""
421+
Create a path from the text. Note that it simply is a path,
422+
not an artist. You need to use the `~.PathPatch` (or other artists)
423+
to draw this path onto the canvas.
424+
425+
Parameters
426+
----------
427+
428+
xy : tuple or array of two float values
429+
Position of the text. For no offset, use ``xy=(0, 0)``.
430+
431+
s : str
432+
The text to convert to a path.
433+
434+
size : float, optional
435+
Font size in points. Defaults to the size specified via the font
436+
properties *prop*.
437+
438+
prop : `matplotlib.font_manager.FontProperties`, optional
439+
Font property. If not provided, will use a default
440+
``FontProperties`` with parameters from the
441+
:ref:`rcParams <matplotlib-rcparams>`.
442+
443+
_interpolation_steps : integer, optional
444+
(Currently ignored)
445+
446+
usetex : bool, optional
447+
Whether to use tex rendering. Defaults to ``False``.
448+
449+
Examples
450+
--------
451+
452+
The following creates a path from the string "ABC" with Helvetica
453+
font face; and another path from the latex fraction 1/2::
454+
455+
from matplotlib.textpath import TextPath
456+
from matplotlib.font_manager import FontProperties
457+
458+
fp = FontProperties(family="Helvetica", style="italic")
459+
path1 = TextPath((12,12), "ABC", size=12, prop=fp)
460+
path2 = TextPath((0,0), r"$\frac{1}{2}$", size=12, usetex=True)
400461
401-
xy : position of the text.
402-
s : text
403-
size : font size
404-
prop : font property
462+
Also see :doc:`/gallery/text_labels_and_annotations/demo_text_path`.
405463
"""
406464

407465
if prop is None:

0 commit comments

Comments
 (0)
0