diff --git a/Doc/source/cffLib/index.rst b/Doc/source/cffLib/index.rst index 281a0b128..4a40f92f4 100644 --- a/Doc/source/cffLib/index.rst +++ b/Doc/source/cffLib/index.rst @@ -11,43 +11,3 @@ This package also contains two modules for manipulating CFF format glyphs: specializer width - -.. autoclass:: fontTools.cffLib.CFFFontSet - :inherited-members: - :members: - -.. autoclass:: fontTools.cffLib.TopDict - :members: - -.. autoclass:: fontTools.cffLib.CharStrings - :members: - -.. autoclass:: fontTools.cffLib.Index - :members: - -.. autoclass:: fontTools.cffLib.GlobalSubrsIndex - :members: - -.. autoclass:: fontTools.cffLib.TopDictIndex - :members: - -.. autoclass:: fontTools.cffLib.CFFWriter - :members: - -.. autoclass:: fontTools.cffLib.IndexCompiler - :members: - -.. autoclass:: fontTools.cffLib.TopDictIndexCompiler - :members: - -.. autoclass:: fontTools.cffLib.FDArrayIndexCompiler - :members: - -.. autoclass:: fontTools.cffLib.GlobalSubrsCompiler - :members: - -.. autoclass:: fontTools.cffLib.SubrsCompiler - :members: - -.. autoclass:: fontTools.cffLib.CharStringsCompiler - :members: diff --git a/Doc/source/colorLib/index.rst b/Doc/source/colorLib/index.rst index d4eb9f83d..5a9bf8a16 100644 --- a/Doc/source/colorLib/index.rst +++ b/Doc/source/colorLib/index.rst @@ -3,9 +3,3 @@ colorLib.builder: Build COLR/CPAL tables from scratch ##################################################### .. automodule:: fontTools.colorLib.builder - :members: buildCPAL, buildCOLR, populateCOLRv0 - -.. autoclass:: fontTools.colorLib.builder.ColorPaletteType - :inherited-members: - :members: - :undoc-members: diff --git a/Doc/source/conf.py b/Doc/source/conf.py index 2fdc4ebed..b95119dbb 100644 --- a/Doc/source/conf.py +++ b/Doc/source/conf.py @@ -32,7 +32,12 @@ needs_sphinx = "1.3" # ones. extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.napoleon", "sphinx.ext.coverage", "sphinx.ext.autosectionlabel"] -autodoc_mock_imports = ["gtk"] +autodoc_mock_imports = ["gtk", "reportlab"] + +autodoc_default_options = { + 'members': True, + 'inherited-members': True +} # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -99,7 +104,7 @@ html_theme_options = {"display_version": False} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] +# html_static_path = ["_static"] html_favicon = "assets/img/favicon.ico" diff --git a/Doc/source/designspaceLib/readme.rst b/Doc/source/designspaceLib/readme.rst index c5757a6e1..b9ba85a63 100644 --- a/Doc/source/designspaceLib/readme.rst +++ b/Doc/source/designspaceLib/readme.rst @@ -95,7 +95,7 @@ Class Methods - +.. _source-descriptor-object: SourceDescriptor object ======================= @@ -883,7 +883,7 @@ Attributes is not important for compiling variable fonts. 5.1.1 conditionset element -======================= +========================== - Child element of ``rule`` - Contains one or more ``condition`` elements. diff --git a/Doc/source/developer.rst b/Doc/source/developer.rst index 3e259f0ee..dc4d425c8 100644 --- a/Doc/source/developer.rst +++ b/Doc/source/developer.rst @@ -1,3 +1,4 @@ +:orphan: .. _developerinfo: .. image:: ../../Icons/FontToolsIconGreenCircle.png :width: 200px diff --git a/Doc/source/misc/plistlib.rst b/Doc/source/misc/plistlib.rst index 685709671..7409aa222 100644 --- a/Doc/source/misc/plistlib.rst +++ b/Doc/source/misc/plistlib.rst @@ -4,6 +4,3 @@ plistlib: Tools for handling .plist files .. automodule:: fontTools.misc.plistlib :members: totree, fromtree, load, loads, dump, dumps - -.. autoclass:: fontTools.misc.plistlib.Data - :members: diff --git a/Doc/source/optional.rst b/Doc/source/optional.rst index 09376a26a..c0d34d967 100644 --- a/Doc/source/optional.rst +++ b/Doc/source/optional.rst @@ -1,3 +1,5 @@ +:orphan: + Optional Dependencies ===================== diff --git a/Doc/source/otlLib/index.rst b/Doc/source/otlLib/index.rst index 1984914c3..272db73a4 100644 --- a/Doc/source/otlLib/index.rst +++ b/Doc/source/otlLib/index.rst @@ -11,16 +11,31 @@ lookups, coverage tables and so on. High-level OpenType Layout Lookup Builders ------------------------------------------ -.. automodule:: fontTools.otlLib.builder - :members: AlternateSubstBuilder, ChainContextPosBuilder, ChainContextSubstBuilder, LigatureSubstBuilder, MultipleSubstBuilder, CursivePosBuilder, MarkBasePosBuilder, MarkLigPosBuilder, MarkMarkPosBuilder, ReverseChainSingleSubstBuilder, SingleSubstBuilder, ClassPairPosSubtableBuilder, PairPosBuilder, SinglePosBuilder - :member-order: bysource +.. currentmodule:: fontTools.otlLib.builder + +.. autoclass:: AlternateSubstBuilder +.. autoclass:: ChainContextPosBuilder +.. autoclass:: ChainContextSubstBuilder +.. autoclass:: LigatureSubstBuilder +.. autoclass:: MultipleSubstBuilder +.. autoclass:: CursivePosBuilder +.. autoclass:: MarkBasePosBuilder +.. autoclass:: MarkLigPosBuilder +.. autoclass:: MarkMarkPosBuilder +.. autoclass:: ReverseChainSingleSubstBuilder +.. autoclass:: SingleSubstBuilder +.. autoclass:: ClassPairPosSubtableBuilder +.. autoclass:: PairPosBuilder +.. autoclass:: SinglePosBuilder -------------------------------------- Common OpenType Layout Data Structures -------------------------------------- -.. automodule:: fontTools.otlLib.builder - :members: buildCoverage, buildLookup +.. currentmodule:: fontTools.otlLib.builder + +.. autofunction:: buildCoverage +.. autofunction:: buildLookup ------------------------------------ Low-level GSUB Table Lookup Builders @@ -29,8 +44,12 @@ Low-level GSUB Table Lookup Builders These functions deal with the "simple" lookup types. See above for classes to help build more complex lookups (contextual and chaining lookups). -.. automodule:: fontTools.otlLib.builder - :members: buildSingleSubstSubtable, buildMultipleSubstSubtable, buildAlternateSubstSubtable, buildLigatureSubstSubtable +.. currentmodule:: fontTools.otlLib.builder + +.. autofunction:: buildSingleSubstSubtable +.. autofunction:: buildMultipleSubstSubtable +.. autofunction:: buildAlternateSubstSubtable +.. autofunction:: buildLigatureSubstSubtable -------------------------- GPOS Shared Table Builders @@ -40,9 +59,13 @@ The functions help build the `GPOS shared tables C_O_L_R_.table_C_O_L_R_: """Build COLR table from color layers mapping. + Args: + colorGlyphs: map of base glyph name to, either list of (layer glyph name, - color palette index) tuples for COLRv0; or a single Paint (dict) or - list of Paint for COLRv1. + color palette index) tuples for COLRv0; or a single ``Paint`` (dict) or + list of ``Paint`` for COLRv1. version: the version of COLR table. If None, the version is determined by the presence of COLRv1 paints or variation data (varStore), which require version 1; otherwise, if all base glyphs use only simple color @@ -206,7 +208,8 @@ def buildCOLR( varIndexMap: Optional DeltaSetIndexMap for deltas associated with v1 layer. clipBoxes: Optional map of base glyph name to clip box 4- or 5-tuples: (xMin, yMin, xMax, yMax) or (xMin, yMin, xMax, yMax, varIndexBase). - Return: + + Returns: A new COLR table. """ self = C_O_L_R_.table_C_O_L_R_() diff --git a/Lib/fontTools/designspaceLib/__init__.py b/Lib/fontTools/designspaceLib/__init__.py index b447a1b77..4b7068276 100644 --- a/Lib/fontTools/designspaceLib/__init__.py +++ b/Lib/fontTools/designspaceLib/__init__.py @@ -160,18 +160,22 @@ class SourceDescriptor(SimpleDescriptor): class RuleDescriptor(SimpleDescriptor): - """ - - - - - - - - - - - + """Represents the rule descriptor element + + .. code-block:: xml + + + + + + + + + + + + + """ _attrs = ['name', 'conditionSets', 'subs'] # what do we need here @@ -996,7 +1000,10 @@ class BaseDocReader(LogMixin): def readGlyphElement(self, glyphElement, instanceObject): """ - Read the glyph element. + Read the glyph element: + + .. code-block:: xml + diff --git a/Lib/fontTools/misc/fixedTools.py b/Lib/fontTools/misc/fixedTools.py index f87e3322f..6ec7d06e0 100644 --- a/Lib/fontTools/misc/fixedTools.py +++ b/Lib/fontTools/misc/fixedTools.py @@ -150,9 +150,9 @@ def strToFixed(string, precisionBits): Examples:: - >>> ## to convert a float string to a 2.14 fixed-point number: - >>> strToFixed('-0.61884', precisionBits=14) - -10139 + >>> ## to convert a float string to a 2.14 fixed-point number: + >>> strToFixed('-0.61884', precisionBits=14) + -10139 """ value = float(string) return otRound(value * (1 << precisionBits)) diff --git a/Lib/fontTools/misc/transform.py b/Lib/fontTools/misc/transform.py index 22ad776a2..94e1f6220 100644 --- a/Lib/fontTools/misc/transform.py +++ b/Lib/fontTools/misc/transform.py @@ -10,12 +10,16 @@ used as dictionary keys. This module exports the following symbols: - Transform -- this is the main class - Identity -- Transform instance set to the identity transformation - Offset -- Convenience function that returns a translating transformation - Scale -- Convenience function that returns a scaling transformation +Transform + this is the main class +Identity + Transform instance set to the identity transformation +Offset + Convenience function that returns a translating transformation +Scale + Convenience function that returns a scaling transformation -Examples: +:Example: >>> t = Transform(2, 0, 0, 3, 0, 0) >>> t.transformPoint((100, 100)) @@ -72,7 +76,8 @@ class Transform(NamedTuple): Transform instances are immutable: all transforming methods, eg. rotate(), return a new Transform instance. - Examples: + :Example: + >>> t = Transform() >>> t @@ -85,7 +90,8 @@ class Transform(NamedTuple): (200, 300) Transform's constructor takes six arguments, all of which are - optional, and can be used as keyword arguments: + optional, and can be used as keyword arguments:: + >>> Transform(12) >>> Transform(dx=12) @@ -93,7 +99,8 @@ class Transform(NamedTuple): >>> Transform(yx=12) - Transform instances also behave like sequences of length 6: + Transform instances also behave like sequences of length 6:: + >>> len(Identity) 6 >>> list(Identity) @@ -101,13 +108,15 @@ class Transform(NamedTuple): >>> tuple(Identity) (1, 0, 0, 1, 0, 0) - Transform instances are comparable: + Transform instances are comparable:: + >>> t1 = Identity.scale(2, 3).translate(4, 6) >>> t2 = Identity.translate(8, 18).scale(2, 3) >>> t1 == t2 1 - But beware of floating point rounding errors: + But beware of floating point rounding errors:: + >>> t1 = Identity.scale(0.2, 0.3).translate(0.4, 0.6) >>> t2 = Identity.translate(0.08, 0.18).scale(0.2, 0.3) >>> t1 @@ -118,12 +127,14 @@ class Transform(NamedTuple): 0 Transform instances are hashable, meaning you can use them as - keys in dictionaries: + keys in dictionaries:: + >>> d = {Scale(12, 13): None} >>> d {: None} - But again, beware of floating point rounding errors: + But again, beware of floating point rounding errors:: + >>> t1 = Identity.scale(0.2, 0.3).translate(0.4, 0.6) >>> t2 = Identity.translate(0.08, 0.18).scale(0.2, 0.3) >>> t1 @@ -149,7 +160,8 @@ class Transform(NamedTuple): def transformPoint(self, p): """Transform a point. - Example: + :Example: + >>> t = Transform() >>> t = t.scale(2.5, 5.5) >>> t.transformPoint((100, 100)) @@ -162,7 +174,8 @@ class Transform(NamedTuple): def transformPoints(self, points): """Transform a list of points. - Example: + :Example: + >>> t = Scale(2, 3) >>> t.transformPoints([(0, 0), (0, 100), (100, 100), (100, 0)]) [(0, 0), (0, 300), (200, 300), (200, 0)] @@ -174,7 +187,8 @@ class Transform(NamedTuple): def transformVector(self, v): """Transform an (dx, dy) vector, treating translation as zero. - Example: + :Example: + >>> t = Transform(2, 0, 0, 2, 10, 20) >>> t.transformVector((3, -4)) (6, -8) @@ -187,7 +201,7 @@ class Transform(NamedTuple): def transformVectors(self, vectors): """Transform a list of (dx, dy) vector, treating translation as zero. - Example: + :Example: >>> t = Transform(2, 0, 0, 2, 10, 20) >>> t.transformVectors([(3, -4), (5, -6)]) [(6, -8), (10, -12)] @@ -199,7 +213,7 @@ class Transform(NamedTuple): def translate(self, x=0, y=0): """Return a new transformation, translated (offset) by x, y. - Example: + :Example: >>> t = Transform() >>> t.translate(20, 30) @@ -211,7 +225,7 @@ class Transform(NamedTuple): """Return a new transformation, scaled by x, y. The 'y' argument may be None, which implies to use the x value for y as well. - Example: + :Example: >>> t = Transform() >>> t.scale(5) @@ -226,7 +240,7 @@ class Transform(NamedTuple): def rotate(self, angle): """Return a new transformation, rotated by 'angle' (radians). - Example: + :Example: >>> import math >>> t = Transform() >>> t.rotate(math.pi / 2) @@ -241,7 +255,7 @@ class Transform(NamedTuple): def skew(self, x=0, y=0): """Return a new transformation, skewed by x and y. - Example: + :Example: >>> import math >>> t = Transform() >>> t.skew(math.pi / 4) @@ -255,7 +269,7 @@ class Transform(NamedTuple): """Return a new transformation, transformed by another transformation. - Example: + :Example: >>> t = Transform(2, 0, 0, 3, 1, 6) >>> t.transform((4, 3, 2, 1, 5, 6)) @@ -276,7 +290,7 @@ class Transform(NamedTuple): transformed by self. self.reverseTransform(other) is equivalent to other.transform(self). - Example: + :Example: >>> t = Transform(2, 0, 0, 3, 1, 6) >>> t.reverseTransform((4, 3, 2, 1, 5, 6)) @@ -297,7 +311,7 @@ class Transform(NamedTuple): def inverse(self): """Return the inverse transformation. - Example: + :Example: >>> t = Identity.translate(2, 3).scale(4, 5) >>> t.transformPoint((10, 20)) (42, 103) @@ -315,7 +329,10 @@ class Transform(NamedTuple): return self.__class__(xx, xy, yx, yy, dx, dy) def toPS(self): - """Return a PostScript representation: + """Return a PostScript representation + + :Example: + >>> t = Identity.scale(2, 3).translate(4, 5) >>> t.toPS() '[2 0 0 3 8 15]' @@ -325,6 +342,9 @@ class Transform(NamedTuple): def __bool__(self): """Returns True if transform is not identity, False otherwise. + + :Example: + >>> bool(Identity) False >>> bool(Transform()) @@ -351,7 +371,7 @@ Identity = Transform() def Offset(x=0, y=0): """Return the identity transformation offset by x, y. - Example: + :Example: >>> Offset(2, 3) >>> @@ -362,7 +382,7 @@ def Scale(x, y=None): """Return the identity transformation scaled by x, y. The 'y' argument may be None, which implies to use the x value for y as well. - Example: + :Example: >>> Scale(2, 3) >>> diff --git a/Lib/fontTools/otlLib/builder.py b/Lib/fontTools/otlLib/builder.py index 6e98e4b21..cafb8ba0a 100644 --- a/Lib/fontTools/otlLib/builder.py +++ b/Lib/fontTools/otlLib/builder.py @@ -24,7 +24,7 @@ log = logging.getLogger(__name__) def buildCoverage(glyphs, glyphMap): """Builds a coverage table. - Coverage tables (as defined in the `OpenType spec `_) + Coverage tables (as defined in the `OpenType spec `__) are used in all OpenType Layout lookups apart from the Extension type, and define the glyphs involved in a layout subtable. This allows shaping engines to compare the glyph stream with the coverage table and quickly determine @@ -66,7 +66,7 @@ LOOKUP_FLAG_USE_MARK_FILTERING_SET = 0x0010 def buildLookup(subtables, flags=0, markFilterSet=None): """Turns a collection of rules into a lookup. - A Lookup (as defined in the `OpenType Spec `_) + A Lookup (as defined in the `OpenType Spec `__) wraps the individual rules in a layout operation (substitution or positioning) in a data structure expressing their overall lookup type - for example, single substitution, mark-to-base attachment, and so on - diff --git a/Lib/fontTools/pens/basePen.py b/Lib/fontTools/pens/basePen.py index 72e3918b9..e06c00efa 100644 --- a/Lib/fontTools/pens/basePen.py +++ b/Lib/fontTools/pens/basePen.py @@ -8,7 +8,7 @@ it is an abstraction for drawing outlines, making sure that outline objects don't need to know the details about how and where they're being drawn, and that drawings don't need to know the details of how outlines are stored. -The most basic pattern is this: +The most basic pattern is this:: outline.draw(pen) # 'outline' draws itself onto 'pen' @@ -21,13 +21,13 @@ The AbstractPen class defines the Pen protocol. It implements almost nothing (only no-op closePath() and endPath() methods), but is useful for documentation purposes. Subclassing it basically tells the reader: "this class implements the Pen protocol.". An examples of an AbstractPen -subclass is fontTools.pens.transformPen.TransformPen. +subclass is :py:class:`fontTools.pens.transformPen.TransformPen`. The BasePen class is a base implementation useful for pens that actually draw (for example a pen renders outlines using a native graphics engine). BasePen contains a lot of base functionality, making it very easy to build a pen that fully conforms to the pen protocol. Note that if you subclass -BasePen, you _don't_ override moveTo(), lineTo(), etc., but _moveTo(), +BasePen, you *don't* override moveTo(), lineTo(), etc., but _moveTo(), _lineTo(), etc. See the BasePen doc string for details. Examples of BasePen subclasses are fontTools.pens.boundsPen.BoundsPen and fontTools.pens.cocoaPen.CocoaPen. @@ -151,7 +151,7 @@ class NullPen(AbstractPen): class LoggingPen(LogMixin, AbstractPen): - """A pen with a `log` property (see fontTools.misc.loggingTools.LogMixin) + """A pen with a ``log`` property (see fontTools.misc.loggingTools.LogMixin) """ pass diff --git a/Lib/fontTools/pens/boundsPen.py b/Lib/fontTools/pens/boundsPen.py index 810715caa..227c22f56 100644 --- a/Lib/fontTools/pens/boundsPen.py +++ b/Lib/fontTools/pens/boundsPen.py @@ -14,10 +14,11 @@ class ControlBoundsPen(BasePen): on their extremes. When the shape has been drawn, the bounds are available as the - 'bounds' attribute of the pen object. It's a 4-tuple: + ``bounds`` attribute of the pen object. It's a 4-tuple:: + (xMin, yMin, xMax, yMax). - If 'ignoreSinglePoints' is True, single points are ignored. + If ``ignoreSinglePoints`` is True, single points are ignored. """ def __init__(self, glyphSet, ignoreSinglePoints=False): @@ -73,7 +74,8 @@ class BoundsPen(ControlBoundsPen): than the "control bounds". When the shape has been drawn, the bounds are available as the - 'bounds' attribute of the pen object. It's a 4-tuple: + ``bounds`` attribute of the pen object. It's a 4-tuple:: + (xMin, yMin, xMax, yMax) """ diff --git a/Lib/fontTools/pens/cu2quPen.py b/Lib/fontTools/pens/cu2quPen.py index 497585bc3..3c4ceae97 100644 --- a/Lib/fontTools/pens/cu2quPen.py +++ b/Lib/fontTools/pens/cu2quPen.py @@ -23,13 +23,15 @@ class Cu2QuPen(AbstractPen): """ A filter pen to convert cubic bezier curves to quadratic b-splines using the FontTools SegmentPen protocol. - other_pen: another SegmentPen used to draw the transformed outline. - max_err: maximum approximation error in font units. For optimal results, - if you know the UPEM of the font, we recommend setting this to a - value equal, or close to UPEM / 1000. - reverse_direction: flip the contours' direction but keep starting point. - stats: a dictionary counting the point numbers of quadratic segments. - ignore_single_points: don't emit contours containing only a single point + Args: + + other_pen: another SegmentPen used to draw the transformed outline. + max_err: maximum approximation error in font units. For optimal results, + if you know the UPEM of the font, we recommend setting this to a + value equal, or close to UPEM / 1000. + reverse_direction: flip the contours' direction but keep starting point. + stats: a dictionary counting the point numbers of quadratic segments. + ignore_single_points: don't emit contours containing only a single point NOTE: The "ignore_single_points" argument is deprecated since v1.3.0, which dropped Robofab subpport. It's no longer needed to special-case @@ -138,12 +140,13 @@ class Cu2QuPointPen(BasePointToSegmentPen): """ A filter pen to convert cubic bezier curves to quadratic b-splines using the RoboFab PointPen protocol. - other_point_pen: another PointPen used to draw the transformed outline. - max_err: maximum approximation error in font units. For optimal results, - if you know the UPEM of the font, we recommend setting this to a - value equal, or close to UPEM / 1000. - reverse_direction: reverse the winding direction of all contours. - stats: a dictionary counting the point numbers of quadratic segments. + Args: + other_point_pen: another PointPen used to draw the transformed outline. + max_err: maximum approximation error in font units. For optimal results, + if you know the UPEM of the font, we recommend setting this to a + value equal, or close to UPEM / 1000. + reverse_direction: reverse the winding direction of all contours. + stats: a dictionary counting the point numbers of quadratic segments. """ def __init__(self, other_point_pen, max_err, reverse_direction=False, diff --git a/Lib/fontTools/pens/recordingPen.py b/Lib/fontTools/pens/recordingPen.py index 203082a43..70f05e83b 100644 --- a/Lib/fontTools/pens/recordingPen.py +++ b/Lib/fontTools/pens/recordingPen.py @@ -29,21 +29,21 @@ class RecordingPen(AbstractPen): The recording can be accessed as pen.value; or replayed using pen.replay(otherPen). - Usage example: - ============== - from fontTools.ttLib import TTFont - from fontTools.pens.recordingPen import RecordingPen + :Example: - glyph_name = 'dollar' - font_path = 'MyFont.otf' + from fontTools.ttLib import TTFont + from fontTools.pens.recordingPen import RecordingPen - font = TTFont(font_path) - glyphset = font.getGlyphSet() - glyph = glyphset[glyph_name] + glyph_name = 'dollar' + font_path = 'MyFont.otf' - pen = RecordingPen() - glyph.draw(pen) - print(pen.value) + font = TTFont(font_path) + glyphset = font.getGlyphSet() + glyph = glyphset[glyph_name] + + pen = RecordingPen() + glyph.draw(pen) + print(pen.value) """ def __init__(self): @@ -72,23 +72,23 @@ class DecomposingRecordingPen(DecomposingPen, RecordingPen): The constructor takes a single 'glyphSet' positional argument, a dictionary of glyph objects (i.e. with a 'draw' method) keyed - by thir name. + by thir name:: - >>> class SimpleGlyph(object): - ... def draw(self, pen): - ... pen.moveTo((0, 0)) - ... pen.curveTo((1, 1), (2, 2), (3, 3)) - ... pen.closePath() - >>> class CompositeGlyph(object): - ... def draw(self, pen): - ... pen.addComponent('a', (1, 0, 0, 1, -1, 1)) - >>> glyphSet = {'a': SimpleGlyph(), 'b': CompositeGlyph()} - >>> for name, glyph in sorted(glyphSet.items()): - ... pen = DecomposingRecordingPen(glyphSet) - ... glyph.draw(pen) - ... print("{}: {}".format(name, pen.value)) - a: [('moveTo', ((0, 0),)), ('curveTo', ((1, 1), (2, 2), (3, 3))), ('closePath', ())] - b: [('moveTo', ((-1, 1),)), ('curveTo', ((0, 2), (1, 3), (2, 4))), ('closePath', ())] + >>> class SimpleGlyph(object): + ... def draw(self, pen): + ... pen.moveTo((0, 0)) + ... pen.curveTo((1, 1), (2, 2), (3, 3)) + ... pen.closePath() + >>> class CompositeGlyph(object): + ... def draw(self, pen): + ... pen.addComponent('a', (1, 0, 0, 1, -1, 1)) + >>> glyphSet = {'a': SimpleGlyph(), 'b': CompositeGlyph()} + >>> for name, glyph in sorted(glyphSet.items()): + ... pen = DecomposingRecordingPen(glyphSet) + ... glyph.draw(pen) + ... print("{}: {}".format(name, pen.value)) + a: [('moveTo', ((0, 0),)), ('curveTo', ((1, 1), (2, 2), (3, 3))), ('closePath', ())] + b: [('moveTo', ((-1, 1),)), ('curveTo', ((0, 2), (1, 3), (2, 4))), ('closePath', ())] """ # raises KeyError if base glyph is not found in glyphSet skipMissingComponents = False @@ -100,23 +100,23 @@ class RecordingPointPen(AbstractPointPen): The recording can be accessed as pen.value; or replayed using pointPen.replay(otherPointPen). - Usage example: - ============== - from defcon import Font - from fontTools.pens.recordingPen import RecordingPointPen + :Example: - glyph_name = 'a' - font_path = 'MyFont.ufo' + from defcon import Font + from fontTools.pens.recordingPen import RecordingPointPen - font = Font(font_path) - glyph = font[glyph_name] + glyph_name = 'a' + font_path = 'MyFont.ufo' - pen = RecordingPointPen() - glyph.drawPoints(pen) - print(pen.value) + font = Font(font_path) + glyph = font[glyph_name] - new_glyph = font.newGlyph('b') - pen.replay(new_glyph.getPointPen()) + pen = RecordingPointPen() + glyph.drawPoints(pen) + print(pen.value) + + new_glyph = font.newGlyph('b') + pen.replay(new_glyph.getPointPen()) """ def __init__(self): diff --git a/Lib/fontTools/pens/reportLabPen.py b/Lib/fontTools/pens/reportLabPen.py index c0a4610b7..43217d428 100644 --- a/Lib/fontTools/pens/reportLabPen.py +++ b/Lib/fontTools/pens/reportLabPen.py @@ -7,7 +7,7 @@ __all__ = ["ReportLabPen"] class ReportLabPen(BasePen): - """A pen for drawing onto a reportlab.graphics.shapes.Path object.""" + """A pen for drawing onto a ``reportlab.graphics.shapes.Path`` object.""" def __init__(self, glyphSet, path=None): BasePen.__init__(self, glyphSet) diff --git a/Lib/fontTools/subset/__init__.py b/Lib/fontTools/subset/__init__.py index 8fb732f34..da2b8416f 100644 --- a/Lib/fontTools/subset/__init__.py +++ b/Lib/fontTools/subset/__init__.py @@ -24,82 +24,100 @@ __usage__ = "pyftsubset font-file [glyph...] [--option=value]..." __doc__="""\ pyftsubset -- OpenType font subsetter and optimizer - pyftsubset is an OpenType font subsetter and optimizer, based on fontTools. - It accepts any TT- or CFF-flavored OpenType (.otf or .ttf) or WOFF (.woff) - font file. The subsetted glyph set is based on the specified glyphs - or characters, and specified OpenType layout features. +pyftsubset is an OpenType font subsetter and optimizer, based on fontTools. +It accepts any TT- or CFF-flavored OpenType (.otf or .ttf) or WOFF (.woff) +font file. The subsetted glyph set is based on the specified glyphs +or characters, and specified OpenType layout features. - The tool also performs some size-reducing optimizations, aimed for using - subset fonts as webfonts. Individual optimizations can be enabled or - disabled, and are enabled by default when they are safe. +The tool also performs some size-reducing optimizations, aimed for using +subset fonts as webfonts. Individual optimizations can be enabled or +disabled, and are enabled by default when they are safe. -Usage: - """+__usage__+""" +Usage: """+__usage__+""" - At least one glyph or one of --gids, --gids-file, --glyphs, --glyphs-file, - --text, --text-file, --unicodes, or --unicodes-file, must be specified. +At least one glyph or one of --gids, --gids-file, --glyphs, --glyphs-file, +--text, --text-file, --unicodes, or --unicodes-file, must be specified. -Arguments: - font-file - The input font file. - glyph - Specify one or more glyph identifiers to include in the subset. Must be - PS glyph names, or the special string '*' to keep the entire glyph set. +Args: -Initial glyph set specification: - These options populate the initial glyph set. Same option can appear - multiple times, and the results are accummulated. - --gids=[,...] - Specify comma/whitespace-separated list of glyph IDs or ranges as - decimal numbers. For example, --gids=10-12,14 adds glyphs with - numbers 10, 11, 12, and 14. - --gids-file= - Like --gids but reads from a file. Anything after a '#' on any line - is ignored as comments. - --glyphs=[,...] - Specify comma/whitespace-separated PS glyph names to add to the subset. - Note that only PS glyph names are accepted, not gidNNN, U+XXXX, etc - that are accepted on the command line. The special string '*' will keep - the entire glyph set. - --glyphs-file= - Like --glyphs but reads from a file. Anything after a '#' on any line - is ignored as comments. - --text= - Specify characters to include in the subset, as UTF-8 string. - --text-file= - Like --text but reads from a file. Newline character are not added to - the subset. - --unicodes=[,...] - Specify comma/whitespace-separated list of Unicode codepoints or - ranges as hex numbers, optionally prefixed with 'U+', 'u', etc. - For example, --unicodes=41-5a,61-7a adds ASCII letters, so does - the more verbose --unicodes=U+0041-005A,U+0061-007A. - The special strings '*' will choose all Unicode characters mapped - by the font. - --unicodes-file= - Like --unicodes, but reads from a file. Anything after a '#' on any - line in the file is ignored as comments. - --ignore-missing-glyphs - Do not fail if some requested glyphs or gids are not available in - the font. - --no-ignore-missing-glyphs - Stop and fail if some requested glyphs or gids are not available - in the font. [default] - --ignore-missing-unicodes [default] - Do not fail if some requested Unicode characters (including those - indirectly specified using --text or --text-file) are not available - in the font. - --no-ignore-missing-unicodes - Stop and fail if some requested Unicode characters are not available - in the font. - Note the default discrepancy between ignoring missing glyphs versus - unicodes. This is for historical reasons and in the future - --no-ignore-missing-unicodes might become default. +font-file + The input font file. +glyph + Specify one or more glyph identifiers to include in the subset. Must be + PS glyph names, or the special string '*' to keep the entire glyph set. + +Initial glyph set specification +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These options populate the initial glyph set. Same option can appear +multiple times, and the results are accummulated. + +--gids=[,...] + Specify comma/whitespace-separated list of glyph IDs or ranges as decimal + numbers. For example, --gids=10-12,14 adds glyphs with numbers 10, 11, + 12, and 14. + +--gids-file= + Like --gids but reads from a file. Anything after a '#' on any line is + ignored as comments. + +--glyphs=[,...] + Specify comma/whitespace-separated PS glyph names to add to the subset. + Note that only PS glyph names are accepted, not gidNNN, U+XXXX, etc + that are accepted on the command line. The special string '*' will keep + the entire glyph set. + +--glyphs-file= + Like --glyphs but reads from a file. Anything after a '#' on any line + is ignored as comments. + +--text= + Specify characters to include in the subset, as UTF-8 string. + +--text-file= + Like --text but reads from a file. Newline character are not added to + the subset. + +--unicodes=[,...] + Specify comma/whitespace-separated list of Unicode codepoints or + ranges as hex numbers, optionally prefixed with 'U+', 'u', etc. + For example, --unicodes=41-5a,61-7a adds ASCII letters, so does + the more verbose --unicodes=U+0041-005A,U+0061-007A. + The special strings '*' will choose all Unicode characters mapped + by the font. + +--unicodes-file= + Like --unicodes, but reads from a file. Anything after a '#' on any + line in the file is ignored as comments. + +--ignore-missing-glyphs + Do not fail if some requested glyphs or gids are not available in + the font. + +--no-ignore-missing-glyphs + Stop and fail if some requested glyphs or gids are not available + in the font. [default] + +--ignore-missing-unicodes [default] + Do not fail if some requested Unicode characters (including those + indirectly specified using --text or --text-file) are not available + in the font. + +--no-ignore-missing-unicodes + Stop and fail if some requested Unicode characters are not available + in the font. + Note the default discrepancy between ignoring missing glyphs versus + unicodes. This is for historical reasons and in the future + --no-ignore-missing-unicodes might become default. + +Other options +^^^^^^^^^^^^^ + +For the other options listed below, to see the current value of the option, +pass a value of '?' to it, with or without a '='. + +Examples:: -Other options: - For the other options listed below, to see the current value of the option, - pass a value of '?' to it, with or without a '='. - Examples: $ pyftsubset --glyph-names? Current setting for 'glyph-names' is: False $ ./pyftsubset --name-IDs=? @@ -108,242 +126,299 @@ Other options: Current setting for 'hinting' is: True Current setting for 'hinting' is: False -Output options: - --output-file= - The output font file. If not specified, the subsetted font - will be saved in as font-file.subset. - --flavor= - Specify flavor of output font file. May be 'woff' or 'woff2'. - Note that WOFF2 requires the Brotli Python extension, available - at https://github.com/google/brotli - --with-zopfli - Use the Google Zopfli algorithm to compress WOFF. The output is 3-8 % - smaller than pure zlib, but the compression speed is much slower. - The Zopfli Python bindings are available at: - https://pypi.python.org/pypi/zopfli +Output options +^^^^^^^^^^^^^^ -Glyph set expansion: - These options control how additional glyphs are added to the subset. - --retain-gids - Retain glyph indices; just empty glyphs not needed in-place. - --notdef-glyph - Add the '.notdef' glyph to the subset (ie, keep it). [default] - --no-notdef-glyph - Drop the '.notdef' glyph unless specified in the glyph set. This - saves a few bytes, but is not possible for Postscript-flavored - fonts, as those require '.notdef'. For TrueType-flavored fonts, - this works fine as long as no unsupported glyphs are requested - from the font. - --notdef-outline - Keep the outline of '.notdef' glyph. The '.notdef' glyph outline is - used when glyphs not supported by the font are to be shown. It is not - needed otherwise. - --no-notdef-outline - When including a '.notdef' glyph, remove its outline. This saves - a few bytes. [default] - --recommended-glyphs - Add glyphs 0, 1, 2, and 3 to the subset, as recommended for - TrueType-flavored fonts: '.notdef', 'NULL' or '.null', 'CR', 'space'. - Some legacy software might require this, but no modern system does. - --no-recommended-glyphs - Do not add glyphs 0, 1, 2, and 3 to the subset, unless specified in - glyph set. [default] - --no-layout-closure - Do not expand glyph set to add glyphs produced by OpenType layout - features. Instead, OpenType layout features will be subset to only - rules that are relevant to the otherwise-specified glyph set. - --layout-features[+|-]=[,...] - Specify (=), add to (+=) or exclude from (-=) the comma-separated - set of OpenType layout feature tags that will be preserved. - Glyph variants used by the preserved features are added to the - specified subset glyph set. By default, 'calt', 'ccmp', 'clig', 'curs', - 'dnom', 'frac', 'kern', 'liga', 'locl', 'mark', 'mkmk', 'numr', 'rclt', - 'rlig', 'rvrn', and all features required for script shaping are - preserved. To see the full list, try '--layout-features=?'. - Use '*' to keep all features. - Multiple --layout-features options can be provided if necessary. - Examples: - --layout-features+=onum,pnum,ss01 - * Keep the default set of features and 'onum', 'pnum', 'ss01'. - --layout-features-='mark','mkmk' - * Keep the default set of features but drop 'mark' and 'mkmk'. - --layout-features='kern' - * Only keep the 'kern' feature, drop all others. - --layout-features='' - * Drop all features. - --layout-features='*' - * Keep all features. - --layout-features+=aalt --layout-features-=vrt2 - * Keep default set of features plus 'aalt', but drop 'vrt2'. - --layout-scripts[+|-]=