Merge pull request #3720 from n8willis/ttLib

[Docs] ttLib: higher-level navigation and helper documentation

Doc/source/ttLib/index.rst

@@ -2,7 +2,13 @@
 ttLib: Read and write OpenType and TrueType fonts
 #################################################
 
-Most users of the fontTools library will be using it to generate or manipulate
+.. contents:: On this page:
+    :local:
+
+.. rubric:: Overview:
+   :heading-level: 2
+
+Most users of the :mod:`fontTools` library will be using it to generate or manipulate
 OpenType and TrueType fonts. (FontTools initially only supported TrueType fonts,
 gaining OpenType support in version 2.0, and so uses the ``tt`` prefix to refer to
 both kinds of font. Because of this we will refer to both as "TrueType fonts"
@@ -10,14 +16,46 @@ unless we need to make a distinction.)
 
 The main entry point for such operations is the :py:mod:`fontTools.ttLib.ttFont`
 module, but other modules also provide useful functionality for handling OpenType
-fonts.
+fonts:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ttFont
+
+:mod:`.ttLib` supports fonts with TrueType-flavored glyphs (i.e., with
+a ``glyf`` table), with PostScript-flavored glyphs (i.e., ``CFF`` or
+``CFF2`` tables), and with all of the glyph formats used for color fonts
+(``CBDT``, ``COLR``, ``sbix``, and ``SVG``). Static and variable fonts
+are both supported.
+
+
+Command-line utilities
+----------------------
+
+:mod:`.ttLib` includes two modules that provide command-line operations:
+     
+.. toctree::
+   :maxdepth: 1
+   
+   removeOverlaps
+   scaleUpem
+
+
+Supporting modules
+------------------
+
+It also contains helper modules that enable lower-level
+functionality. In most cases, users will not need to access these
+modules directly:
+
+.. toctree::
+   :maxdepth: 1
+   
    ttCollection
+   ttGlyphSet
    macUtils
+   reorderGlyphs
    sfnt
    standardGlyphOrder
    tables

Doc/source/ttLib/macUtils.rst

@@ -1,8 +1,7 @@
-########
-macUtils
-########
+##########################################
+macUtils: Access fonts in Mac file formats
+##########################################
 
 .. automodule:: fontTools.ttLib.macUtils
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/removeOverlaps.rst

@@ -0,0 +1,13 @@
+##############################################################
+removeOverlaps: Tools to remove overlapping contours in glyphs
+##############################################################
+
+.. rubric:: Overview
+   :heading-level: 2
+
+The :mod:`fontTools.ttLib.removeOverlaps` module is a helper for
+:mod:`fontTools.ttLib`.
+
+.. automodule:: fontTools.ttLib.removeOverlaps
+   :members:
+   :undoc-members:

Doc/source/ttLib/reorderGlyphs.rst

@@ -0,0 +1,13 @@
+########################################################
+reorderGlyphs: Functions to reorder the glyphs in a font
+########################################################
+
+.. rubric:: Overview
+   :heading-level: 2
+
+The :mod:`fontTools.ttLib.reorderGlyphs` module is a helper for
+:mod:`fontTools.ttLib`.
+
+.. automodule:: fontTools.ttLib.reorderGlyphs
+   :members:
+   :undoc-members:

Doc/source/ttLib/scaleUpem.rst

@@ -0,0 +1,13 @@
+###########################################################
+scaleUpem: Tools to change the units-per-Em value in a font
+###########################################################
+
+.. rubric:: Overview
+   :heading-level: 2
+
+The :mod:`fontTools.ttLib.scaleUpem` module is a helper for
+:mod:`fontTools.ttLib`.
+
+.. automodule:: fontTools.ttLib.scaleUpem
+   :members:
+   :undoc-members:

Doc/source/ttLib/sfnt.rst

@@ -1,8 +1,7 @@
-####
-sfnt
-####
+#########################################
+sfnt: Read and write the SFNT file format
+#########################################
 
 .. automodule:: fontTools.ttLib.sfnt
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/standardGlyphOrder.rst

@@ -1,9 +1,8 @@
-##################
-standardGlyphOrder
-##################
+###########################################################
+standardGlyphOrder: Interface with the Standard Glyph Order
+###########################################################
 
 .. automodule:: fontTools.ttLib.standardGlyphOrder
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/TupleVariation.rst

@@ -2,6 +2,8 @@
 OpenType variations helper module
 #################################
 
+.. currentmodule:: fontTools.ttLib.tables.TupleVariation
+
 .. rubric:: Overview:
    :heading-level: 2
 

Doc/source/ttLib/ttCollection.rst

@@ -1,8 +1,15 @@
-############
-ttCollection
-############
+################################################################
+ttCollection: Access fonts within a TrueType/OpenType Collection
+################################################################
+
+.. rubric:: Overview
+   :heading-level: 2
+
+The :mod:`fontTools.ttLib.ttCollection` module is a helper for
+:mod:`fontTools.ttLib`. It supports the reading of TrueType and
+OpenType `Collection <https://learn.microsoft.com/en-us/typography/opentype/spec/otff#font-collections>`_ files (\*.ttc, \*.otc) so that each member font in
+the collection is accessible as a :class:`.TTFont` instance.
 
 .. automodule:: fontTools.ttLib.ttCollection
-   :inherited-members:
    :members:
-   :undoc-members:
+   :undoc-members:

Doc/source/ttLib/ttFont.rst

@@ -1,17 +1,99 @@
-##############################################
-ttFont: Read/write OpenType and TrueType fonts
-##############################################
+####################################
+ttFont: Read and write font contents
+####################################
+
+.. contents:: On this page:
+    :local:
+
+.. rubric:: Overview
+   :heading-level: 2
+
+:mod:`.ttLib.ttFont` is the primary fontTools interface for
+inspecting, constructing, or deconstructing TrueType and OpenType
+fonts.
+
+The :class:`fontTools.ttLib.ttFont.TTFont` class provides access to
+font-level data, including font metrics, substitution and positioning
+features, and metadata, through a set of :doc:`table converters
+</ttLib/tables>`. A :class:`.TTFont` may be instantiated from a single
+font file, or it may be a member of a
+:class:`.TTCollection`. :class:`.TTFont` objects can also be
+constructed from scratch. 
+
+
+glyphSets and ttGlyphs
+----------------------
+
+In addition to font-wide data, :mod:`.ttLib.ttFont` provides access to
+individual glyphs through a :class:`.TTFont` instance's
+``.glyphSet[]`` attribute. A ``.glyphSet`` is a dict-like object that is
+indexed by glyph names. Users can use the glyphSet to interact with
+each glyph's contours, components, points, and glyph metrics.
+
+Informally, some fontTools code or documentation will make reference to
+the individual glyphs in a ``.glyphSet`` as a "ttGlyph" or the
+like. This is convenient terminology, particularly for
+discussion. However, it is important to note that there is not a
+"ttGlyph" class. Instead, the ``.glyphSet`` attribute of a
+:class:`.TTFont` serves as an abstraction layer that provides a
+uniform interface to the glyphs, regardless of whether the
+:class:`.TTFont` instance in use comes from a font file with
+TrueType-flavored glyphs (and, therefore, has a `glyf` table
+containing glyph contours) or a font with PostScript-flavored outlines
+(and, therefore, with a ``CFF`` or ``CFF2`` table containing the glyph
+contours).
+
+Regardless of the flavor, each "ttGlyph" entry in the ``.glyphSet``
+includes the corresponding Bezier outlines and components from the
+``glyf`` or ``CFF``/``CFF2`` table and the glyph's metrics. Horizontal
+metrics are drawn from the font's ``hmtx`` table, and vertical metrics
+(if any) are drawn from the ``vmtx`` table. These attributes are:
+
+    width
+        The advance width of the glyph
+    
+    lsb
+        The left sidebearing of the glyph
+    
+    height
+        (For vertical-layout fonts) The advance height of the glyph
+    
+    tsb
+        (for vertical-layout fonts) The top sidebearing of the glyph
+
+Note that these attributes do not describe the bounding box of the
+glyph filled shape, because the filled area might include negative
+coordinate values or extend beyond the advance width due to overhang.
+
+The bounds of the glyph are accessible as ``xMin``, ``xMax``,
+``yMin``, and ``yMax`` attributes.
+
+For implementation details regarding the different flavors of
+"ttGlyph", see the :doc:`ttGlyphSet </ttLib/ttGlyphSet>`
+documentation.
+
+These glyph objects also implement the :doc:`Pen Protocol
+</pens/index>` by providing ``.draw()`` and ``.drawPoints()``
+methods. See the :doc:`pens </pens/index>` package documenation
+for more.
+
+
+Package contents
+----------------
+ 
 
 .. autoclass:: fontTools.ttLib.ttFont.TTFont
-   :inherited-members:
    :members:
+   :undoc-members:
 
+
+      
 .. autoclass:: fontTools.ttLib.ttFont.GlyphOrder
-   :inherited-members:
    :members:
    :undoc-members:
    :private-members:
 
+
 .. automodule:: fontTools.ttLib.ttFont
    :members: getTableModule, registerCustomTableClass, unregisterCustomTableClass, getCustomTableClass, getClassTag, newTable, tagToIdentifier, identifierToTag, tagToXML, xmlToTag, sortedTagList, reorderFontTables
    :exclude-members: TTFont, GlyphOrder

Doc/source/ttLib/ttGlyphSet.rst

@@ -0,0 +1,18 @@
+#################################################
+ttGlyphSet: GlyphSets returned by a TTFont object
+#################################################
+
+.. rubric:: Overview
+   :heading-level: 2
+
+The :mod:`fontTools.ttLib.ttGlyphSet` module is a helper for
+:mod:`fontTools.ttLib`.
+
+Most users will not need to access this module directly. Instead, the
+glyphs in a font are accessible as a ``.glyphSet`` dictionary in a
+:class:`TTFont` instance.
+
+.. automodule:: fontTools.ttLib.ttGlyphSet
+   :members:
+   :undoc-members:
+   :private-members:

Doc/source/ttLib/woff2.rst

@@ -1,8 +1,11 @@
-#####
-woff2
-#####
+################################################
+woff2: Read and write the WOFF2 font file format
+################################################
+
+Note also that :mod:`woff2` supports some :doc:`optional </optional>`
+external libraries.
+
 
 .. automodule:: fontTools.ttLib.woff2
-   :inherited-members:
    :members:
    :undoc-members:

Lib/fontTools/ttLib/tables/otTables.py

@@ -2226,24 +2226,28 @@ _equivalents = {
 def fixLookupOverFlows(ttf, overflowRecord):
     """Either the offset from the LookupList to a lookup overflowed, or
     an offset from a lookup to a subtable overflowed.
-    The table layout is:
-    GPSO/GUSB
-            Script List
-            Feature List
-            LookUpList
-                    Lookup[0] and contents
-                            SubTable offset list
-                                    SubTable[0] and contents
-                                    ...
-                                    SubTable[n] and contents
-                    ...
-                    Lookup[n] and contents
-                            SubTable offset list
-                                    SubTable[0] and contents
-                                    ...
-                                    SubTable[n] and contents
+
+    The table layout is::
+
+      GPSO/GUSB
+              Script List
+              Feature List
+              LookUpList
+                      Lookup[0] and contents
+                              SubTable offset list
+                                      SubTable[0] and contents
+                                      ...
+                                      SubTable[n] and contents
+                      ...
+                      Lookup[n] and contents
+                              SubTable offset list
+                                      SubTable[0] and contents
+                                      ...
+                                      SubTable[n] and contents
+
     If the offset to a lookup overflowed (SubTableIndex is None)
-            we must promote the *previous*	lookup to an Extension type.
+            we must promote the *previous* lookup to an Extension type.
+
     If the offset from a lookup to subtable overflowed, then we must promote it
             to an Extension Lookup type.
     """

Lib/fontTools/ttLib/tables/otTraverse.py

@@ -79,7 +79,8 @@ def bfs_base_table(
     """Breadth-first search tree of BaseTables.
 
     Args:
-    the root of the tree.
+        root
+            the root of the tree.
         root_accessor (Optional[str]): attribute name for the root table, if any (mostly
             useful for debugging).
         skip_root (Optional[bool]): if True, the root itself is not visited, only its

Lib/fontTools/ttLib/ttFont.py

@@ -27,6 +27,7 @@ class TTFont(object):
     they're actually accessed. This means that simple operations can be extremely fast.
 
     Example usage:
+
     .. code-block:: pycon
 
         >>>
@@ -39,8 +40,10 @@ class TTFont(object):
         >> tt['head'].unitsPerEm
         2048
 
-    For details of the objects returned when accessing each table, see :ref:`tables`.
+    For details of the objects returned when accessing each table, see the
+    :doc:`tables </ttLib/tables>` documentation.
     To add a table to the font, use the :py:func:`newTable` function:
+
     .. code-block:: pycon
 
         >>>
@@ -50,7 +53,8 @@ class TTFont(object):
         >> font["OS/2"] = os2
 
     TrueType fonts can also be serialized to and from XML format (see also the
-    :ref:`ttx` binary):
+    :doc:`ttx </ttx>` binary):
+
     .. code-block:: pycon
 
         >>