Merge pull request #3627 from n8willis/docs-cleanup

Docs: clean up various code blocks in docstrings, to enable correct syntax highlighting in HTML / RTD output.

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,15 +188,15 @@ class FreeTypePen(BasePen):
             maintained but RSB won’t. The difference between the two becomes
             more obvious when rotate or skew transformation is applied.
 
-        :Example:
+        Example:
-            .. code-block::
+            .. code-block:: pycon
 
+                >>>
                 >> pen = FreeTypePen(None)
                 >> glyph.draw(pen)
                 >> buf, size = pen.buffer(width=500, height=1000)
                 >> type(buf), len(buf), size
                 (<class 'bytes'>, 500000, (500, 1000))
-
         """
         transform = transform or Transform()
         if not hasattr(transform, "transformPoint"):
@@ -269,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
@@ -279,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:
+        Example:
-            .. code-block::
+            .. code-block:: pycon
 
+                >>>
                 >> pen = FreeTypePen(None)
                 >> glyph.draw(pen)
                 >> arr = pen.array(width=500, height=1000)
                 >> type(a), a.shape
                 (<class 'numpy.ndarray'>, (1000, 500))
         """
+
         import numpy as np
 
         buf, size = self.buffer(
@@ -318,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
@@ -328,9 +330,10 @@ class FreeTypePen(BasePen):
             maintained but RSB won’t. The difference between the two becomes
             more obvious when rotate or skew transformation is applied.
 
-        :Example:
+        Example:
-            .. code-block::
+            .. code-block:: pycon
 
+                >>>
                 >> pen = FreeTypePen(None)
                 >> glyph.draw(pen)
                 >> pen.show(width=500, height=1000)
@@ -370,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
@@ -380,9 +383,10 @@ class FreeTypePen(BasePen):
             maintained but RSB won’t. The difference between the two becomes
             more obvious when rotate or skew transformation is applied.
 
-        :Example:
+        Example:
-            .. code-block::
+            .. code-block:: pycon
 
+                >>>
                 >> pen = FreeTypePen(None)
                 >> glyph.draw(pen)
                 >> img = pen.image(width=500, height=1000)

Lib/fontTools/pens/pointInsidePen.py

@@ -15,7 +15,8 @@ class PointInsidePen(BasePen):
     Instances of this class can be recycled, as long as the
     setTestPoint() method is used to set the new point to test.
 
-    Typical usage:
+    :Example:
+        .. code-block::
 
             pen = PointInsidePen(glyphSet, (100, 200))
             outline.draw(pen)

Lib/fontTools/pens/recordingPen.py

@@ -33,6 +33,7 @@ class RecordingPen(AbstractPen):
     pen.replay(otherPen).
 
     :Example:
+        .. code-block::
 
             from fontTools.ttLib import TTFont
             from fontTools.pens.recordingPen import RecordingPen
@@ -122,6 +123,7 @@ class DecomposingRecordingPen(DecomposingPen, RecordingPen):
         b: [('moveTo', ((-1, 1),)), ('curveTo', ((0, 2), (1, 3), (2, 4))), ('closePath', ())]
         c: []
         d: [('moveTo', ((0, 0),)), ('curveTo', ((-1, 1), (-2, 2), (-3, 3))), ('closePath', ())]
+
         >>> for name, glyph in sorted(glyphSet.items()):
         ...     pen = DecomposingRecordingPen(
         ...         glyphSet, skipMissingComponents=True, reverseFlipped=True,
@@ -145,6 +147,7 @@ class RecordingPointPen(AbstractPointPen):
     pointPen.replay(otherPointPen).
 
     :Example:
+        .. code-block::
 
             from defcon import Font
             from fontTools.pens.recordingPen import RecordingPointPen
@@ -261,6 +264,7 @@ class DecomposingRecordingPointPen(DecomposingPointPen, RecordingPointPen):
                ('addPoint', ((-2, 2), None, False, None), {}),
                ('addPoint', ((-3, 3), 'curve', False, None), {}),
                ('endPath', (), {})]}
+
         >>> for name, glyph in sorted(glyphSet.items()):
         ...     pen = DecomposingRecordingPointPen(
         ...         glyphSet, skipMissingComponents=True, reverseFlipped=True,

Lib/fontTools/pens/svgPathPen.py

@@ -9,7 +9,15 @@ def pointToString(pt, ntos=str):
 class SVGPathPen(BasePen):
     """Pen to draw SVG path d commands.
 
-    Example::
+    Args:
+        glyphSet: a dictionary of drawable glyph objects keyed by name
+            used to resolve component references in composite glyphs.
+        ntos: a callable that takes a number and returns a string, to
+            customize how numbers are formatted (default: str).
+
+    :Example:
+        .. code-block::
+
             >>> pen = SVGPathPen(None)
             >>> pen.moveTo((0, 0))
             >>> pen.lineTo((1, 1))
@@ -18,18 +26,13 @@ class SVGPathPen(BasePen):
             >>> pen.getCommands()
             'M0 0 1 1C2 2 3 3 4 4Z'
 
-    Args:
-        glyphSet: a dictionary of drawable glyph objects keyed by name
-            used to resolve component references in composite glyphs.
-        ntos: a callable that takes a number and returns a string, to
-            customize how numbers are formatted (default: str).
-
     Note:
         Fonts have a coordinate system where Y grows up, whereas in SVG,
         Y grows down.  As such, rendering path data from this pen in
         SVG typically results in upside-down glyphs.  You can fix this
         by wrapping the data from this pen in an SVG group element with
         transform, or wrap this pen in a transform pen.  For example:
+        .. code-block:: python
 
             spen = svgPathPen.SVGPathPen(glyphset)
             pen= TransformPen(spen , (1, 0, 0, -1, 0, 0))

Lib/fontTools/pens/transformPen.py

@@ -58,6 +58,8 @@ class TransformPointPen(FilterPointPen):
     """PointPen that transforms all coordinates using a Affine transformation,
     and passes them to another PointPen.
 
+    For example::
+
         >>> from fontTools.pens.recordingPen import RecordingPointPen
         >>> rec = RecordingPointPen()
         >>> pen = TransformPointPen(rec, (2, 0, 0, 2, -10, 5))
@@ -65,12 +67,15 @@ class TransformPointPen(FilterPointPen):
         >>> pen.beginPath(identifier="contour-0")
         >>> next(v)
         ('beginPath', (), {'identifier': 'contour-0'})
+
         >>> pen.addPoint((100, 100), "line")
         >>> next(v)
         ('addPoint', ((190, 205), 'line', False, None), {})
+
         >>> pen.endPath()
         >>> next(v)
         ('endPath', (), {})
+
         >>> pen.addComponent("a", (1, 0, 0, 1, -10, 5), identifier="component-0")
         >>> next(v)
         ('addComponent', ('a', <Transform [2 0 0 2 -30 15]>), {'identifier': 'component-0'})

Lib/fontTools/svgLib/path/__init__.py

@@ -14,6 +14,8 @@ class SVGPath(object):
 
     For example, reading from an SVG file and drawing to a Defcon Glyph:
 
+    .. code-block::
+
         import defcon
         glyph = defcon.Glyph()
         pen = glyph.getPen()
@@ -23,6 +25,8 @@ class SVGPath(object):
     Or reading from a string containing SVG data, using the alternative
     'fromstring' (a class method):
 
+    .. code-block::
+
         data = '<?xml version="1.0" ...'
         svg = SVGPath.fromstring(data)
         svg.draw(pen)

Lib/fontTools/svgLib/path/parser.py

@@ -103,6 +103,8 @@ def parse_path(pathdef, pen, current_pos=(0, 0), arc_class=EllipticalArc):
     If the pen has an "arcTo" method, it is called with the original values
     of the elliptical arc curve commands:
 
+    .. code-block::
+
         pen.arcTo(rx, ry, rotation, arc_large, arc_sweep, (x, y))
 
     Otherwise, the arcs are approximated by series of cubic Bezier segments

Lib/fontTools/ttLib/sfnt.py

@@ -1,8 +1,9 @@
 """ttLib/sfnt.py -- low-level module to deal with the sfnt file format.
 
 Defines two public classes:
-	SFNTReader
+
-	SFNTWriter
+- SFNTReader
+- SFNTWriter
 
 (Normally you don't have to use these classes explicitly; they are
 used automatically by ttLib.TTFont.)

Lib/fontTools/ttLib/ttFont.py

@@ -26,8 +26,10 @@ 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::
+    Example usage:
+    .. code-block:: pycon
 
+        >>>
         >> from fontTools import ttLib
         >> tt = ttLib.TTFont("afont.ttf") # Load an existing font file
         >> tt['maxp'].numGlyphs
@@ -38,16 +40,20 @@ class TTFont(object):
         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::
+    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)::
+    :ref:`ttx` binary):
+    .. code-block:: pycon
 
+        >>
         >> tt.saveXML("afont.ttx")
         Dumping 'LTSH' table...
         Dumping 'OS/2' table...
@@ -981,13 +987,15 @@ 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::
+    extra underscore is prepended. Examples:
+    .. code-block:: pycon
 
-            >>> tagToIdentifier('glyf')
+        >>>
+        >> tagToIdentifier('glyf')
         '_g_l_y_f'
-            >>> tagToIdentifier('cvt ')
+        >> tagToIdentifier('cvt ')
         '_c_v_t'
-            >>> tagToIdentifier('OS/2')
+        >> tagToIdentifier('OS/2')
         'O_S_2f_2'
     """
     import re

Lib/fontTools/ufoLib/__init__.py

@@ -7,25 +7,29 @@ of the specification.
 
 Sets that list the font info attribute names for the fontinfo.plist
 formats are available for external use. These are:
-	fontInfoAttributesVersion1
+
-	fontInfoAttributesVersion2
+- fontInfoAttributesVersion1
-	fontInfoAttributesVersion3
+- fontInfoAttributesVersion2
+- fontInfoAttributesVersion3
 
 A set listing the fontinfo.plist attributes that were deprecated
 in version 2 is available for external use:
-	deprecatedFontInfoAttributesVersion2
+
+- deprecatedFontInfoAttributesVersion2
 
 Functions that do basic validation on values for fontinfo.plist
 are available for external use. These are
-	validateFontInfoVersion2ValueForAttribute
+
-	validateFontInfoVersion3ValueForAttribute
+- validateFontInfoVersion2ValueForAttribute
+- validateFontInfoVersion3ValueForAttribute
 
 Value conversion functions are available for converting
 fontinfo.plist values between the possible format versions.
-	convertFontInfoValueForAttributeFromVersion1ToVersion2
+
-	convertFontInfoValueForAttributeFromVersion2ToVersion1
+- convertFontInfoValueForAttributeFromVersion1ToVersion2
-	convertFontInfoValueForAttributeFromVersion2ToVersion3
+- convertFontInfoValueForAttributeFromVersion2ToVersion1
-	convertFontInfoValueForAttributeFromVersion3ToVersion2
+- convertFontInfoValueForAttributeFromVersion2ToVersion3
+- convertFontInfoValueForAttributeFromVersion3ToVersion2
 """
 
 import os

Lib/fontTools/varLib/__init__.py

@@ -10,10 +10,14 @@ ttf-interpolatable files for the masters and build a variable-font from
 them.  Such ttf-interpolatable and designspace files can be generated from
 a Glyphs source, eg., using noto-source as an example:
 
+    .. code-block:: sh
+
 	$ fontmake -o ttf-interpolatable -g NotoSansArabic-MM.glyphs
 
 Then you can make a variable-font this way:
 
+    .. code-block:: sh
+
 	$ fonttools varLib master_ufo/NotoSansArabic.designspace
 
 API *will* change in near future.

Lib/fontTools/varLib/instancer/__init__.py

@@ -5,7 +5,9 @@ create full instances (i.e. static fonts) from variable fonts, as well as "parti
 variable fonts that only contain a subset of the original variation space.
 
 For example, if you wish to pin the width axis to a given location while also
-restricting the weight axis to 400..700 range, you can do::
+restricting the weight axis to 400..700 range, you can do:
+
+.. code-block:: sh
 
     $ fonttools varLib.instancer ./NotoSans-VF.ttf wdth=85 wght=400:700
 
@@ -17,32 +19,38 @@ 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
+    >> from fontTools import ttLib
-| >>> varfont = ttLib.TTFont("path/to/MyVariableFont.ttf")
+    >> from fontTools.varLib import instancer
-| >>> [a.axisTag for a in varfont["fvar"].axes]  # the varfont's current axes
+    >> varfont = ttLib.TTFont("path/to/MyVariableFont.ttf")
-| ['wght', 'wdth']
+    >> [a.axisTag for a in varfont["fvar"].axes]  # the varfont's current axes
-| >>> partial = instancer.instantiateVariableFont(varfont, {"wght": 300})
+    ['wght', 'wdth']
-| >>> [a.axisTag for a in partial["fvar"].axes]  # axes left after pinning 'wght'
+    >> partial = instancer.instantiateVariableFont(varfont, {"wght": 300})
-| ['wdth']
+    >> [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(
+    >>>    
-| ...     varfont, {"wght": 700, "wdth": 67.5}
+    >> instance = instancer.instantiateVariableFont(
-| ... )
+    ...     varfont, {"wght": 700, "wdth": 67.5}
-| >>> "fvar" not in instance
+    ... )
-| True
+    >> "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})
-| 1
+    >> len(varfont["fvar"].axes)
+    1
 
 From the console script, this is equivalent to passing `wght=drop` as input.
 
@@ -56,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;
+    .. code-block:: pycon
     
-    | >>> font = instancer.instantiateVariableFont(varfont, {"wght": 700})
+        >>>
+        >> 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.
+    .. code-block:: pycon
     
-    | >>> font = instancer.instantiateVariableFont(varfont, {"wght": (100, 300)})
+        >>>
+        >> font = instancer.instantiateVariableFont(varfont, {"wght": (100, 300)})
 
 L4
     moving the default location of an axis, by specifying (min,defalt,max) values:
+    .. code-block:: pycon
     
-    | >>> font = instancer.instantiateVariableFont(varfont, {"wght": (100, 300, 700)})
+        >>>
+        >> 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.

Lib/fontTools/varLib/mutator.py

@@ -1,7 +1,9 @@
 """
 Instantiate a variation font.  Run, eg:
 
-$ fonttools varLib.mutator ./NotoSansArabic-VF.ttf wght=140 wdth=85
+.. code-block:: sh
+
+    $ fonttools varLib.mutator ./NotoSansArabic-VF.ttf wght=140 wdth=85
 """
 
 from fontTools.misc.fixedTools import floatToFixedToFloat, floatToFixed
@@ -162,6 +164,8 @@ def instantiateVariableFont(varfont, location, inplace=False, overlap=True):
     defining the desired location along the variable font's axes.
     The location values must be specified as user-space coordinates, e.g.:
 
+    .. code-block::
+
         {'wght': 400, 'wdth': 100}
 
     By default, a new TTFont object is returned. If ``inplace`` is True, the

Lib/fontTools/voltLib/voltToFea.py

@@ -7,12 +7,16 @@ Usage
 To convert a VTP project file:
 
 
+.. code-block:: sh
+
     $ fonttools voltLib.voltToFea input.vtp output.fea
 
 It is also possible convert font files with `TSIV` table (as saved from Volt),
 in this case the glyph names used in the Volt project will be mapped to the
 actual glyph names in the font files when written to the feature file:
 
+.. code-block:: sh
+
     $ fonttools voltLib.voltToFea input.ttf output.fea
 
 The ``--quiet`` option can be used to suppress warnings.