From 7d93689aca5356c54c6a73d98feadbcd5a3a47cb Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Wed, 11 Sep 2024 15:45:46 +0100 Subject: [PATCH] Docs: workaround doctest-vs-Sphinx syntax highlighting. --- Lib/fontTools/pens/freetypePen.py | 61 +++++++++-------- Lib/fontTools/ttLib/ttFont.py | 78 ++++++++++++---------- Lib/fontTools/varLib/instancer/__init__.py | 50 +++++++++----- 3 files changed, 108 insertions(+), 81 deletions(-) diff --git a/Lib/fontTools/pens/freetypePen.py b/Lib/fontTools/pens/freetypePen.py index a366b6d05..1e3129cea 100644 --- a/Lib/fontTools/pens/freetypePen.py +++ b/Lib/fontTools/pens/freetypePen.py @@ -46,7 +46,7 @@ class FreeTypePen(BasePen): glyphSet: a dictionary of drawable glyph objects keyed by name used to resolve component references in composite glyphs. - :Examples: + Examples: If `numpy` and `matplotlib` is available, the following code will show the glyph image of `fi` in a new window:: @@ -178,7 +178,7 @@ class FreeTypePen(BasePen): object of the resulted bitmap and ``size`` is a 2-tuple of its dimension. - :Notes: + Notes: The image size should always be given explicitly if you need to get a proper glyph image. When ``width`` and ``height`` are omitted, it forcifully fits to the bounding box and the side bearings get @@ -188,13 +188,14 @@ class FreeTypePen(BasePen): maintained but RSB won’t. The difference between the two becomes more obvious when rotate or skew transformation is applied. - :Example: - .. code-block:: + Example: + .. code-block:: pycon - >>> pen = FreeTypePen(None) - >>> glyph.draw(pen) - >>> buf, size = pen.buffer(width=500, height=1000) - >>> type(buf), len(buf), size + >>> + >> pen = FreeTypePen(None) + >> glyph.draw(pen) + >> buf, size = pen.buffer(width=500, height=1000) + >> type(buf), len(buf), size (, 500000, (500, 1000)) """ transform = transform or Transform() @@ -268,7 +269,7 @@ class FreeTypePen(BasePen): A ``numpy.ndarray`` object with a shape of ``(height, width)``. Each element takes a value in the range of ``[0.0, 1.0]``. - :Notes: + Notes: The image size should always be given explicitly if you need to get a proper glyph image. When ``width`` and ``height`` are omitted, it forcifully fits to the bounding box and the side bearings get @@ -278,15 +279,17 @@ class FreeTypePen(BasePen): maintained but RSB won’t. The difference between the two becomes more obvious when rotate or skew transformation is applied. - :Example: - .. code-block:: + Example: + .. code-block:: pycon - >>> pen = FreeTypePen(None) - >>> glyph.draw(pen) - >>> arr = pen.array(width=500, height=1000) - >>> type(a), a.shape + >>> + >> pen = FreeTypePen(None) + >> glyph.draw(pen) + >> arr = pen.array(width=500, height=1000) + >> type(a), a.shape (, (1000, 500)) """ + import numpy as np buf, size = self.buffer( @@ -317,7 +320,7 @@ class FreeTypePen(BasePen): rendering glyphs with negative sidebearings without clipping. evenOdd: Pass ``True`` for even-odd fill instead of non-zero. - :Notes: + Notes: The image size should always be given explicitly if you need to get a proper glyph image. When ``width`` and ``height`` are omitted, it forcifully fits to the bounding box and the side bearings get @@ -327,12 +330,13 @@ class FreeTypePen(BasePen): maintained but RSB won’t. The difference between the two becomes more obvious when rotate or skew transformation is applied. - :Example: - .. code-block:: + Example: + .. code-block:: pycon - >>> pen = FreeTypePen(None) - >>> glyph.draw(pen) - >>> pen.show(width=500, height=1000) + >>> + >> pen = FreeTypePen(None) + >> glyph.draw(pen) + >> pen.show(width=500, height=1000) """ from matplotlib import pyplot as plt @@ -369,7 +373,7 @@ class FreeTypePen(BasePen): A ``PIL.image`` object. The image is filled in black with alpha channel obtained from the rendered bitmap. - :Notes: + Notes: The image size should always be given explicitly if you need to get a proper glyph image. When ``width`` and ``height`` are omitted, it forcifully fits to the bounding box and the side bearings get @@ -379,13 +383,14 @@ class FreeTypePen(BasePen): maintained but RSB won’t. The difference between the two becomes more obvious when rotate or skew transformation is applied. - :Example: - .. code-block:: + Example: + .. code-block:: pycon - >>> pen = FreeTypePen(None) - >>> glyph.draw(pen) - >>> img = pen.image(width=500, height=1000) - >>> type(img), img.size + >>> + >> pen = FreeTypePen(None) + >> glyph.draw(pen) + >> img = pen.image(width=500, height=1000) + >> type(img), img.size (, (500, 1000)) """ from PIL import Image diff --git a/Lib/fontTools/ttLib/ttFont.py b/Lib/fontTools/ttLib/ttFont.py index ad8756a05..0942bd80d 100644 --- a/Lib/fontTools/ttLib/ttFont.py +++ b/Lib/fontTools/ttLib/ttFont.py @@ -26,37 +26,43 @@ class TTFont(object): accessing tables. Tables will be only decompiled when necessary, ie. when they're actually accessed. This means that simple operations can be extremely fast. - Example usage:: - - >>> from fontTools import ttLib - >>> tt = ttLib.TTFont("afont.ttf") # Load an existing font file - >>> tt['maxp'].numGlyphs - 242 - >>> tt['OS/2'].achVendID - 'B&H\000' - >>> tt['head'].unitsPerEm - 2048 + Example usage: + .. code-block:: pycon + + >>> + >> from fontTools import ttLib + >> tt = ttLib.TTFont("afont.ttf") # Load an existing font file + >> tt['maxp'].numGlyphs + 242 + >> tt['OS/2'].achVendID + 'B&H\000' + >> tt['head'].unitsPerEm + 2048 For details of the objects returned when accessing each table, see :ref:`tables`. - To add a table to the font, use the :py:func:`newTable` function:: - - >>> os2 = newTable("OS/2") - >>> os2.version = 4 - >>> # set other attributes - >>> font["OS/2"] = os2 + To add a table to the font, use the :py:func:`newTable` function: + .. code-block:: pycon + + >>> + >> os2 = newTable("OS/2") + >> os2.version = 4 + >> # set other attributes + >> font["OS/2"] = os2 TrueType fonts can also be serialized to and from XML format (see also the - :ref:`ttx` binary):: - - >>> tt.saveXML("afont.ttx") - Dumping 'LTSH' table... - Dumping 'OS/2' table... - [...] - - >>> tt2 = ttLib.TTFont() # Create a new font object - >>> tt2.importXML("afont.ttx") - >>> tt2['maxp'].numGlyphs - 242 + :ref:`ttx` binary): + .. code-block:: pycon + + >> + >> tt.saveXML("afont.ttx") + Dumping 'LTSH' table... + Dumping 'OS/2' table... + [...] + + >> tt2 = ttLib.TTFont() # Create a new font object + >> tt2.importXML("afont.ttx") + >> tt2['maxp'].numGlyphs + 242 The TTFont object may be used as a context manager; this will cause the file reader to be closed after the context ``with`` block is exited:: @@ -981,14 +987,16 @@ def tagToIdentifier(tag): letters get an underscore after the letter. Trailing spaces are trimmed. Illegal characters are escaped as two hex bytes. If the result starts with a number (as the result of a hex escape), an - extra underscore is prepended. Examples:: - - >>> tagToIdentifier('glyf') - '_g_l_y_f' - >>> tagToIdentifier('cvt ') - '_c_v_t' - >>> tagToIdentifier('OS/2') - 'O_S_2f_2' + extra underscore is prepended. Examples: + .. code-block:: pycon + + >>> + >> tagToIdentifier('glyf') + '_g_l_y_f' + >> tagToIdentifier('cvt ') + '_c_v_t' + >> tagToIdentifier('OS/2') + 'O_S_2f_2' """ import re diff --git a/Lib/fontTools/varLib/instancer/__init__.py b/Lib/fontTools/varLib/instancer/__init__.py index fba79dbaa..8a58dbd92 100644 --- a/Lib/fontTools/varLib/instancer/__init__.py +++ b/Lib/fontTools/varLib/instancer/__init__.py @@ -19,31 +19,37 @@ and returns a new TTFont representing either a partial VF, or full instance if a the VF axes were given an explicit coordinate. E.g. here's how to pin the wght axis at a given location in a wght+wdth variable -font, keeping only the deltas associated with the wdth axis:: +font, keeping only the deltas associated with the wdth axis: +.. code-block:: pycon - >>> from fontTools import ttLib - >>> from fontTools.varLib import instancer - >>> varfont = ttLib.TTFont("path/to/MyVariableFont.ttf") - >>> [a.axisTag for a in varfont["fvar"].axes] # the varfont's current axes + >>> + >> from fontTools import ttLib + >> from fontTools.varLib import instancer + >> varfont = ttLib.TTFont("path/to/MyVariableFont.ttf") + >> [a.axisTag for a in varfont["fvar"].axes] # the varfont's current axes ['wght', 'wdth'] - >>> partial = instancer.instantiateVariableFont(varfont, {"wght": 300}) - >>> [a.axisTag for a in partial["fvar"].axes] # axes left after pinning 'wght' + >> partial = instancer.instantiateVariableFont(varfont, {"wght": 300}) + >> [a.axisTag for a in partial["fvar"].axes] # axes left after pinning 'wght' ['wdth'] If the input location specifies all the axes, the resulting instance is no longer 'variable' (same as using fontools varLib.mutator): +.. code-block:: pycon - >>> instance = instancer.instantiateVariableFont( + >>> + >> instance = instancer.instantiateVariableFont( ... varfont, {"wght": 700, "wdth": 67.5} ... ) - >>> "fvar" not in instance + >> "fvar" not in instance True If one just want to drop an axis at the default location, without knowing in advance what the default value for that axis is, one can pass a `None` value: +.. code-block:: pycon - >>> instance = instancer.instantiateVariableFont(varfont, {"wght": None}) - >>> len(varfont["fvar"].axes) + >>> + >> instance = instancer.instantiateVariableFont(varfont, {"wght": None}) + >> len(varfont["fvar"].axes) 1 From the console script, this is equivalent to passing `wght=drop` as input. @@ -58,25 +64,33 @@ course be combined: L1 dropping one or more axes while leaving the default tables unmodified; + .. code-block:: pycon - >>> font = instancer.instantiateVariableFont(varfont, {"wght": None}) + >>> + >> font = instancer.instantiateVariableFont(varfont, {"wght": None}) L2 dropping one or more axes while pinning them at non-default locations; - - >>> font = instancer.instantiateVariableFont(varfont, {"wght": 700}) + .. code-block:: pycon + + >>> + >> font = instancer.instantiateVariableFont(varfont, {"wght": 700}) L3 restricting the range of variation of one or more axes, by setting either a new minimum or maximum, potentially -- though not necessarily -- dropping entire regions of variations that fall completely outside this new range. - - >>> font = instancer.instantiateVariableFont(varfont, {"wght": (100, 300)}) + .. code-block:: pycon + + >>> + >> font = instancer.instantiateVariableFont(varfont, {"wght": (100, 300)}) L4 moving the default location of an axis, by specifying (min,defalt,max) values: - - >>> font = instancer.instantiateVariableFont(varfont, {"wght": (100, 300, 700)}) + .. code-block:: pycon + + >>> + >> font = instancer.instantiateVariableFont(varfont, {"wght": (100, 300, 700)}) Currently only TrueType-flavored variable fonts (i.e. containing 'glyf' table) are supported, but support for CFF2 variable fonts will be added soon.