Merge pull request #3716 from n8willis/master

[Docs] Fill out ttLib table section. Part of a bottom-up docs rework for ttLib.

Note that 23546cf changes the `import`s for ttLib/tables/_g_v_a_r.py to un-confuse autodoc.

Doc/source/ttLib/tables.rst

@@ -1,13 +1,131 @@
-###############################
+#######################################
-TrueType/OpenType Table Modules
+tables: Access TrueType/OpenType tables
-###############################
+#######################################
+
+.. contents:: On this page
+    :local:
+
+
+.. rubric:: Overview
+   :heading-level: 2
 
 This folder is a subpackage of :py:mod:`fontTools.ttLib`. Each module here is a
-specialized TT/OT table converter: they can convert raw data
+specialized TrueType/OpenType table converter: they can convert raw data
-to Python objects and vice versa. Usually you don't need to
+to Python objects and vice versa. Usually you do not need to
-use the modules directly: they are imported and used
+use these modules directly: they are imported and used
-automatically when needed by :py:mod:`fontTools.ttLib`. The tables currently
+automatically when needed by :py:mod:`fontTools.ttLib`.
-supported are:
+
+In addition to the tables defined in the official TrueType/OpenType
+specification documents, several specialty tables are supported that
+are used by specific vendors (including the Graphite shaping engine
+and Apple's AAT). Note that fontTools supports the tables that provide
+the core functionality of AAT, but does not guarantee everything.
+
+Similarly, fontTools supports some third-party tables used by external
+applications (such as FontForge and Microsoft's VTT), but may not
+support every private table employed by those applications.
+
+
+Accessing tables
+----------------
+
+The Python modules representing the tables have pretty strange names: this is due to the
+fact that we need to map TT/OT table tags (which are case sensitive)
+to filenames (which on macOS and Windows are not case sensitive) as well
+as to Python identifiers. The latter means that each table identifier
+can only contain ``[A-Za-z0-9_]`` and cannot start with a number.
+
+The convention adopted is that capital letters in a table tag are
+transformed into the letter followed by an underscore (e.g., ``A_``), while lowercase
+letters and numbers are preceded by an underscore (e.g., ``_a``).
+
+:py:mod:`fontTools.ttLib` provides functions to expand a tag into the format used here::
+
+    >>> from fontTools import ttLib
+    >>> ttLib.tagToIdentifier("FOO ")
+    'F_O_O_'
+    >>> ttLib.tagToIdentifier("cvt ")
+    '_c_v_t'
+    >>> ttLib.tagToIdentifier("OS/2")
+    'O_S_2f_2'
+    >>> ttLib.tagToIdentifier("glyf")
+    '_g_l_y_f'
+    >>>
+
+And vice versa::
+
+    >>> ttLib.identifierToTag("F_O_O_")
+    'FOO '
+    >>> ttLib.identifierToTag("_c_v_t")
+    'cvt '
+    >>> ttLib.identifierToTag("O_S_2f_2")
+    'OS/2'
+    >>> ttLib.identifierToTag("_g_l_y_f")
+    'glyf'
+    >>>
+
+Eg. the 'glyf' table converter lives in a Python file called::
+
+	_g_l_y_f.py
+
+The converter itself is a class, named ``table_`` + expandedtag. Eg::
+
+
+	class table__g_l_y_f:
+		etc.
+
+Note that if you _do_ need to use such modules or classes manually,
+there are two convenient API functions that let you find them by tag::
+
+    >>> ttLib.getTableModule('glyf')
+    <module 'ttLib.tables._g_l_y_f'>
+    >>> ttLib.getTableClass('glyf')
+    <class ttLib.tables._g_l_y_f.table__g_l_y_f at 645f400>
+    >>
+
+
+Helper modules
+--------------
+
+In addition to the core table-conversion implementations, a set of
+helper and utility modules is also found in this package. 
+You should not normally need to access these modules directly,
+but consulting them might be valuable if you need to add fontTools
+support for a new table type.
+ 
+In that case, a good place to start is with the documentation for
+the base table classes:
+ 
+.. toctree::
+   :maxdepth: 1
+ 
+   tables/table_api
+ 
+The modules that provide lower-level helper functionality
+include implementations of common OpenType data structures, support
+for OpenType font variations, and various classes needed for
+tables containing bitmap data or for tables used by the Graphite engine:
+ 	
+.. toctree::
+   :maxdepth: 1
+ 
+   tables/OpenType_related
+   tables/TupleVariation
+   tables/Bitmap_related
+   tables/grUtils
+ 
+A module is also included for assembling and disassembling
+TrueType bytecode:
+ 
+.. toctree::
+   :maxdepth: 1
+
+   tables/ttProgram
+       
+
+    
+Tables currently supported
+--------------------------
 
 .. toctree::
    :maxdepth: 1
@@ -84,106 +202,7 @@ supported are:
    tables/VTT_related
    tables/V_V_A_R_
 
-The Python modules representing the tables have pretty strange names: this is due to the
-fact that we need to map TT table tags (which are case sensitive)
-to filenames (which on Mac and Win aren't case sensitive) as well
-as to Python identifiers. The latter means it can only contain
-``[A-Za-z0-9_]`` and cannot start with a number.
-
-:py:mod:`fontTools.ttLib` provides functions to expand a tag into the format used here::
-
-    >>> from fontTools import ttLib
-    >>> ttLib.tagToIdentifier("FOO ")
-    'F_O_O_'
-    >>> ttLib.tagToIdentifier("cvt ")
-    '_c_v_t'
-    >>> ttLib.tagToIdentifier("OS/2")
-    'O_S_2f_2'
-    >>> ttLib.tagToIdentifier("glyf")
-    '_g_l_y_f'
-    >>>
-
-And vice versa::
-
-    >>> ttLib.identifierToTag("F_O_O_")
-    'FOO '
-    >>> ttLib.identifierToTag("_c_v_t")
-    'cvt '
-    >>> ttLib.identifierToTag("O_S_2f_2")
-    'OS/2'
-    >>> ttLib.identifierToTag("_g_l_y_f")
-    'glyf'
-    >>>
-
-Eg. the 'glyf' table converter lives in a Python file called::
-
-	_g_l_y_f.py
-
-The converter itself is a class, named ``table_`` + expandedtag. Eg::
-
-
-	class table__g_l_y_f:
-		etc.
-
-Note that if you _do_ need to use such modules or classes manually,
-there are two convenient API functions that let you find them by tag::
-
-    >>> ttLib.getTableModule('glyf')
-    <module 'ttLib.tables._g_l_y_f'>
-    >>> ttLib.getTableClass('glyf')
-    <class ttLib.tables._g_l_y_f.table__g_l_y_f at 645f400>
-    >>
-
-ttProgram: TrueType bytecode assembler/disassembler
----------------------------------------------------
-
-.. automodule:: fontTools.ttLib.tables.ttProgram
-   :inherited-members:
-   :members:
-   :undoc-members:
-
-Contributing your own table convertors
---------------------------------------
-
-To add support for a new font table that fontTools does not currently implement,
-you must subclass from :py:mod:`fontTools.ttLib.tables.DefaultTable.DefaultTable`.
-It provides some default behavior, as well as a constructor method (``__init__``)
-that you don't need to override.
-
-Your converter should minimally provide two methods::
-
-
-    class table_F_O_O_(DefaultTable.DefaultTable): # converter for table 'FOO '
-
-        def decompile(self, data, ttFont):
-            # 'data' is the raw table data. Unpack it into a
-            # Python data structure.
-            # 'ttFont' is a ttLib.TTfile instance, enabling you to
-            # refer to other tables. Do ***not*** keep a reference to
-            # it: it will cause a circular reference (ttFont saves
-            # a reference to us), and that means we'll be leaking
-            # memory. If you need to use it in other methods, just
-            # pass it around as a method argument.
-
-        def compile(self, ttFont):
-            # Return the raw data, as converted from the Python
-            # data structure.
-            # Again, 'ttFont' is there so you can access other tables.
-            # Same warning applies.
-
-
-If you want to support TTX import/export as well, you need to provide two
-additional methods::
-
-
-   def toXML(self, writer, ttFont):
-      # XXX
-
-   def fromXML(self, (name, attrs, content), ttFont):
-      # XXX
-
 .. automodule:: fontTools.ttLib.tables
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/B_A_S_E_.rst

@@ -1,8 +1,9 @@
-``BASE``: Baseline Table
+``BASE``: Baseline table
 ------------------------
 
+The ``BASE`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.B_A_S_E_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/Bitmap_related.rst

@@ -0,0 +1,36 @@
+##########################
+Bitmap-data helper modules
+##########################
+
+.. contents:: On this page:
+    :local:
+
+.. rubric:: Overview:
+   :heading-level: 2
+
+The modules documented on this page are helpers for
+:mod:`fontTools.ttLib` that implement lower-level support for various
+table converters that need to interact with bitmapped data. The
+:mod:`.BitmapGlyphMetrics` module is used for the ``EBDT``/``EBLC`` and
+``CBDT``/``CBLC`` tables, and :mod:`.sbixGlyph` and :mod:`.sbixStrike`
+are used for the ``sbix`` table.
+
+fontTools.ttLib.tables.BitmapGlyphMetrics
+-----------------------------------------
+.. automodule:: fontTools.ttLib.tables.BitmapGlyphMetrics
+   :members:
+   :undoc-members:
+
+      
+fontTools.ttLib.tables.sbixGlyph
+--------------------------------
+.. automodule:: fontTools.ttLib.tables.sbixGlyph
+   :members:
+   :undoc-members:
+
+      
+fontTools.ttLib.tables.sbixStrike
+---------------------------------
+.. automodule:: fontTools.ttLib.tables.sbixStrike
+   :members:
+   :undoc-members:

Doc/source/ttLib/tables/C_B_D_T_.rst

@@ -1,8 +1,13 @@
-``CBDT``: Color Bitmap Data Table
+``CBDT``: Color Bitmap Data table
 ---------------------------------
 
+The ``CBDT`` table is an OpenType table.
+
+This ``CBDT`` table converter module depends on the
+:mod:`.BitmapGlyphMetrics` module, which it shares with the ``EBDT``,
+``EBLC``, and ``CBLC`` converters.
+
 .. automodule:: fontTools.ttLib.tables.C_B_D_T_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/C_B_L_C_.rst

@@ -1,8 +1,13 @@
-``CBLC``: Color Bitmap Location Table
+``CBLC``: Color Bitmap Location table
 -------------------------------------
 
+The ``CBLC`` table is an OpenType table.
+
+This ``CBLC`` table converter module depends on the
+:mod:`.BitmapGlyphMetrics` module, which it shares with the ``EBDT``,
+``EBLC``, and ``CBDT`` converters.
+
 .. automodule:: fontTools.ttLib.tables.C_B_L_C_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/C_F_F_.rst

@@ -1,8 +1,9 @@
-``CFF``: Compact Font Format Table
+``CFF``: Compact Font Format table
 ----------------------------------
 
+The ``CFF`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.C_F_F_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/C_F_F__2.rst

@@ -1,8 +1,9 @@
-``CFF2``: Compact Font Format (CFF) Version 2
+``CFF2``: Compact Font Format (CFF) Version 2 table
----------------------------------------------
+---------------------------------------------------
+
+The ``CFF2`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables.C_F_F__2
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/C_O_L_R_.rst

@@ -1,7 +1,8 @@
-``COLR``: Color Table
+``COLR``: Color table
 ---------------------
 
+The ``COLR`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.C_O_L_R_
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/C_P_A_L_.rst

@@ -1,8 +1,9 @@
-``CPAL``: Color Palette Table
+``CPAL``: Color Palette table
 -----------------------------
 
+The ``CPAL`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.C_P_A_L_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/D_S_I_G_.rst

@@ -1,8 +1,9 @@
-``DSIG``: Digital Signature Table
+``DSIG``: Digital Signature table
 ---------------------------------
 
+The ``DSIG`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.D_S_I_G_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/E_B_D_T_.rst

@@ -1,18 +1,13 @@
-``EBDT``: Embedded Bitmap Data Table
+``EBDT``: Embedded Bitmap Data table
 ------------------------------------
 
+The ``EBDT`` table is an OpenType table.
+
+This ``EBDT`` table converter module depends on the
+:mod:`.BitmapGlyphMetrics` module, which it shares with the ``EBLC``,
+``CBDT``, and ``CBLC`` converters.
+
 .. automodule:: fontTools.ttLib.tables.E_B_D_T_
-   :inherited-members:
-   :members:
-   :undoc-members:
-
-
-BitmapGlyphMetrics
-^^^^^^^^^^^^^^^^^^
-
-.. automodule:: fontTools.ttLib.tables.BitmapGlyphMetrics
-   :noindex:
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/E_B_L_C_.rst

@@ -1,18 +1,12 @@
-``EBLC``: Embedded Bitmap Location Table
+``EBLC``: Embedded Bitmap Location table
 ----------------------------------------
 
+The ``EBLC`` table is an OpenType table.
+
+This ``EBLC`` table converter module depends on the
+:mod:`.BitmapGlyphMetrics` module, which it shares with the ``EBDT``,
+``CBDT``, and ``CBLC`` converters.
+
 .. automodule:: fontTools.ttLib.tables.E_B_L_C_
-   :inherited-members:
    :members:
    :undoc-members:
-
-
-BitmapGlyphMetrics
-^^^^^^^^^^^^^^^^^^
-
-.. automodule:: fontTools.ttLib.tables.BitmapGlyphMetrics
-   :noindex:
-   :inherited-members:
-   :members:
-   :undoc-members:
-

Doc/source/ttLib/tables/F_F_T_M_.rst

@@ -1,8 +1,9 @@
-``FFTM``: FontForge Time Stamp Table
+``FFTM``: FontForge Time Stamp table
 ------------------------------------
 
+The ``FFTM`` table is used by the FontForge font editor.
+
 .. automodule:: fontTools.ttLib.tables.F_F_T_M_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/F__e_a_t.rst

@@ -1,8 +1,9 @@
-``Feat``: Graphite Feature Table
+``Feat``: Graphite Feature table
 --------------------------------
 
+The ``Feat`` table is a Graphite table.
+
 .. automodule:: fontTools.ttLib.tables.F__e_a_t
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/G_D_E_F_.rst

@@ -1,8 +1,9 @@
-``GDEF``: Glyph Definition Table
+``GDEF``: Glyph Definition table
 --------------------------------
 
+The ``GDEF`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.G_D_E_F_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/G_M_A_P_.rst

@@ -1,8 +1,9 @@
-``GMAP``: SING Glyphlet Summary Table
+``GMAP``: SING Glyphlet Summary table
 -------------------------------------
 
+The ``GMAP`` table is an Adobe Glyphlets table.
+
 .. automodule:: fontTools.ttLib.tables.G_M_A_P_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/G_P_K_G_.rst

@@ -1,8 +1,9 @@
-``GPKG``: SING Glyphlet Wrapper Table
+``GPKG``: SING Glyphlet Wrapper table
 -------------------------------------
 
+The ``GPKG`` table is an Adobe Glyphlets table.
+
 .. automodule:: fontTools.ttLib.tables.G_P_K_G_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/G_P_O_S_.rst

@@ -1,8 +1,9 @@
-``GPOS``: Glyph Positioning Table
+``GPOS``: Glyph Positioning table
 ---------------------------------
 
+The ``GPOS`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.G_P_O_S_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/G_S_U_B_.rst

@@ -1,8 +1,9 @@
-``GSUB``: Glyph Substitution Table
+``GSUB``: Glyph Substitution table
 ----------------------------------
 
+The ``GSUB`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.G_S_U_B_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/G__l_a_t.rst

@@ -1,8 +1,9 @@
-``Glat``: Graphite Glyph Attributes Table
+``Glat``: Graphite Glyph Attributes table
 -----------------------------------------
 
+The ``Glat`` table is a Graphite table.
+
 .. automodule:: fontTools.ttLib.tables.G__l_a_t
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/G__l_o_c.rst

@@ -1,8 +1,9 @@
 ``Gloc``: Graphite index to glyph attributes table
 --------------------------------------------------
 
+The ``Gloc`` table is a Graphite table.
+
 .. automodule:: fontTools.ttLib.tables.G__l_o_c
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/H_V_A_R_.rst

@@ -1,7 +1,8 @@
-``HVAR``:Horizontal Metrics Variations Table
+``HVAR``: Horizontal Metrics Variations table
---------------------------------------------
+---------------------------------------------
+
+The ``HVAR`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables.H_V_A_R_
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/J_S_T_F_.rst

@@ -1,7 +1,8 @@
-``JSTF``: Justification Table
+``JSTF``: Justification table
 -----------------------------
 
+The ``JSTF`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.J_S_T_F_
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/L_T_S_H_.rst

@@ -1,8 +1,9 @@
-``LTSH``: Linear Threshold
+``LTSH``: Linear Threshold table
---------------------------
+--------------------------------
+
+The ``LTSH`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables.L_T_S_H_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/M_A_T_H_.rst

@@ -1,7 +1,8 @@
-``MATH``: Mathematical Typesetting Table
+``MATH``: Mathematical Typesetting table
 ----------------------------------------
 
+The ``MATH`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.M_A_T_H_
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/M_E_T_A_.rst

@@ -1,7 +1,8 @@
-``META``: SING Glyphlet Metadata Table
+``META``: SING Glyphlet Metadata table
 --------------------------------------
 
+The ``META`` table is an Adobe Glyphlets table.
+
 .. automodule:: fontTools.ttLib.tables.M_E_T_A_
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/M_V_A_R_.rst

@@ -1,7 +1,8 @@
-``MVAR``: Metrics Variations Table
+``MVAR``: Metrics Variations table
 ----------------------------------
 
+The ``MVAR`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.M_V_A_R_
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/O_S_2f_2.rst

@@ -1,7 +1,8 @@
-``OS/2``: OS/2 and Windows Metrics Table
+``OS/2``: OS/2 and Windows Metrics table
 ----------------------------------------
 
+The ``OS/2`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.O_S_2f_2
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/OpenType_related.rst

@@ -0,0 +1,46 @@
+#############################
+OpenType-table helper modules
+#############################
+
+.. contents:: On this page:
+    :local:
+
+       
+.. rubric:: Overview:
+   :heading-level: 2
+
+The OpenType-table helper modules documented on this page provide
+support for OpenType's common table (and subtable) data formats.
+
+Most users should not need to access these modules directly.
+
+
+fontTools.ttLib.tables.otTables
+-------------------------------
+
+.. automodule:: fontTools.ttLib.tables.otTables
+   :members:
+   :undoc-members:
+
+      
+fontTools.ttLib.tables.otData
+-----------------------------
+
+.. automodule:: fontTools.ttLib.tables.otData
+   :members:
+   :undoc-members:
+
+      
+fontTools.ttLib.tables.otConverters
+-----------------------------------
+
+.. automodule:: fontTools.ttLib.tables.otConverters
+   :members:
+   :undoc-members:
+
+      
+fontTools.ttLib.tables.otTraverse
+---------------------------------
+.. automodule:: fontTools.ttLib.tables.otTraverse
+   :members:
+   :undoc-members:

Doc/source/ttLib/tables/S_I_N_G_.rst

@@ -1,7 +1,8 @@
-``SING``: SING Glyphlet Basic Information Table
+``SING``: SING Glyphlet Basic Information table
 -----------------------------------------------
 
+The ``SING`` table is an Adobe Glyphlets table.
+
 .. automodule:: fontTools.ttLib.tables.S_I_N_G_
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/S_T_A_T_.rst

@@ -1,7 +1,8 @@
-``STAT``: Style Attributes Table
+``STAT``: Style Attributes table
 --------------------------------
 
+The ``STAT`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.S_T_A_T_
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/S_V_G_.rst

@@ -1,8 +1,9 @@
-``SVG``: SVG (Scalable Vector Graphics) Table
+``SVG``: SVG (Scalable Vector Graphics) table
 ---------------------------------------------
 
+The ``SVG`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.S_V_G_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/S__i_l_f.rst

@@ -1,7 +1,8 @@
-``Silf``: Graphite Rules Table
+``Silf``: Graphite Rules table
 ------------------------------
 
+The ``Silf`` table is a Graphite table.
+
 .. automodule:: fontTools.ttLib.tables.S__i_l_f
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/S__i_l_l.rst

@@ -1,7 +1,8 @@
-``Sill``: Graphite Languages Table
+``Sill``: Graphite Languages table
 ----------------------------------
 
+The ``Sill`` table is a Graphite table.
+
 .. automodule:: fontTools.ttLib.tables.S__i_l_l
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/T_T_F_A_.rst

@@ -1,8 +1,9 @@
-``TTFA``: ``ttfautohint`` Parameter Table
+``TTFA``: ttfautohint Parameter table
 -----------------------------------------
 
+The ``TTFA`` table is used by the ``ttfautohint`` hinting program.
+
 .. automodule:: fontTools.ttLib.tables.T_T_F_A_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/TupleVariation.rst

@@ -0,0 +1,16 @@
+#################################
+OpenType variations helper module
+#################################
+
+.. rubric:: Overview:
+   :heading-level: 2
+
+The :mod:`fontTools.ttLib.tables.TupleVariation` module is a helper for
+:mod:`fontTools.ttLib` that implements lower-level support for
+variable-font table converters.
+
+
+
+.. automodule:: fontTools.ttLib.tables.TupleVariation
+   :members:
+   :undoc-members:

Doc/source/ttLib/tables/VTT_related.rst

@@ -1,11 +1,17 @@
-Visual TrueType Private Tables
+``VTT*`` Visual TrueType private tables
-==============================
+=======================================
+
+The tables listed on this page are used by Microsoft's Visual TrueType
+application.
+
+.. contents:: On this page:
+    :local:
+
 
 ``TSI0``: Glyph Program Text Indices
 ------------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I__0
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -13,7 +19,6 @@ Visual TrueType Private Tables
 --------------------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I__1
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -21,7 +26,6 @@ Visual TrueType Private Tables
 -------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I__2
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -29,7 +33,6 @@ Visual TrueType Private Tables
 ----------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I__3
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -37,15 +40,13 @@ Visual TrueType Private Tables
 ----------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I__5
-   :inherited-members:
    :members:
    :undoc-members:
 
-``TSIB``
+``TSIB``: VTT BASE Table Text Source
---------
+------------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I_B_
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -53,7 +54,6 @@ Visual TrueType Private Tables
 -----------------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I_C_
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -61,7 +61,6 @@ Visual TrueType Private Tables
 ------------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I_D_
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -69,7 +68,6 @@ Visual TrueType Private Tables
 ------------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I_J_
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -77,7 +75,6 @@ Visual TrueType Private Tables
 ------------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I_P_
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -85,7 +82,6 @@ Visual TrueType Private Tables
 ------------------------------------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I_S_
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -93,7 +89,6 @@ Visual TrueType Private Tables
 --------
 
 .. automodule:: fontTools.ttLib.tables.T_S_I_V_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/V_D_M_X_.rst

@@ -1,7 +1,8 @@
-``VDMX``: Vertical Device Metrics
+``VDMX``: Vertical Device Metrics table
----------------------------------
+---------------------------------------
+
+The ``VDMX`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables.V_D_M_X_
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/V_O_R_G_.rst

@@ -1,8 +1,9 @@
-``VORG``: Vertical Origin Table
+``VORG``: Vertical Origin table
 -------------------------------
 
+The ``VORG`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.V_O_R_G_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/V_V_A_R_.rst

@@ -1,8 +1,9 @@
-``VVAR``: Vertical Metrics Variations Table
+``VVAR``: Vertical Metrics Variations table
 -------------------------------------------
 
+The ``VVAR`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables.V_V_A_R_
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_a_n_k_r.rst

@@ -1,7 +1,8 @@
-``ankr``: Anchor Point Table
+``ankr``: Anchor Point table
 ----------------------------
 
+The ``ankr`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._a_n_k_r
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/_a_v_a_r.rst

@@ -1,8 +1,9 @@
-``avar``: Axis Variations Table
+``avar``: Axis Variations table
 -------------------------------
 
+The ``avar`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._a_v_a_r
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_b_s_l_n.rst

@@ -1,7 +1,8 @@
 ``bsln``: Baseline
 ------------------
 
+The ``bsln`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._b_s_l_n
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/_c_i_d_g.rst

@@ -1,7 +1,8 @@
 ``cidg``: CID to Glyph ID table
 -------------------------------
 
+The ``cidg`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._c_i_d_g
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/_c_m_a_p.rst

@@ -1,6 +1,8 @@
-``cmap``: Character to Glyph Index Mapping Table
+``cmap``: Character to Glyph Index Mapping table
 ------------------------------------------------
 
+The ``cmap`` table is an OpenType table.
+
 .. autoclass:: fontTools.ttLib.tables._c_m_a_p.table__c_m_a_p
 
 .. autoclass:: fontTools.ttLib.tables._c_m_a_p.CmapSubtable

Doc/source/ttLib/tables/_c_v_a_r.rst

@@ -1,8 +1,9 @@
-``cvar``: CVT Variations Table
+``cvar``: CVT Variations table
 ------------------------------
 
+The ``cvar`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._c_v_a_r
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -12,6 +13,5 @@ TupleVariation
 
 .. automodule:: fontTools.ttLib.tables.TupleVariation
    :noindex:
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/_c_v_t.rst

@@ -1,8 +1,9 @@
 ``cvt``:  Control Value Table
 -----------------------------
 
+The ``cvt`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._c_v_t
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_f_e_a_t.rst

@@ -1,7 +1,8 @@
 ``feat``: Feature name table
 ----------------------------
 
+The ``feat`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._f_e_a_t
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/_f_p_g_m.rst

@@ -1,7 +1,8 @@
-``fpgm``: Font Program
+``fpgm``: Font Program table
-----------------------
+----------------------------
+
+The ``fpgm`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables._f_p_g_m
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/_f_v_a_r.rst

@@ -1,8 +1,9 @@
-``fvar``: Font Variations Table
+``fvar``: Font Variations table
 -------------------------------
 
+The ``fvar`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._f_v_a_r
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_g_a_s_p.rst

@@ -1,8 +1,9 @@
-``gasp``: Grid-fitting and Scan-conversion Procedure Table
+``gasp``: Grid-fitting and Scan-conversion Procedure table
 ----------------------------------------------------------
 
+The ``gasp`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._g_a_s_p
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_g_c_i_d.rst

@@ -1,7 +1,8 @@
 ``gcid``: Glyph ID to CID table
 -------------------------------
 
+The ``gcid`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._g_c_i_d
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/_g_l_y_f.rst

@@ -1,5 +1,7 @@
-``glyf``: Glyph Data
+``glyf``: Glyph Data table
---------------------
+--------------------------
+
+The ``glyf`` table is an OpenType table.
 
 .. autoclass:: fontTools.ttLib.tables._g_l_y_f.table__g_l_y_f
    :members:

Doc/source/ttLib/tables/_g_v_a_r.rst

@@ -1,8 +1,9 @@
-``gvar``:  Glyph Variations Table
+``gvar``:  Glyph Variations table
 ---------------------------------
 
+The ``gvar`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._g_v_a_r
-   :inherited-members:
    :members:
    :undoc-members:
 
@@ -11,6 +12,5 @@ TupleVariation
 ^^^^^^^^^^^^^^
 
 .. automodule:: fontTools.ttLib.tables.TupleVariation
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/_h_d_m_x.rst

@@ -1,8 +1,9 @@
-``hdmx``: Horizontal Device Metrics
+``hdmx``: Horizontal Device Metrics table
------------------------------------
+-----------------------------------------
+
+The ``hdmx`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables._h_d_m_x
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_h_e_a_d.rst

@@ -1,8 +1,9 @@
-``head``: Font Header Table
+``head``: Font Header table
 ---------------------------
 
+The ``head`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._h_e_a_d
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_h_h_e_a.rst

@@ -1,8 +1,9 @@
-``hhea``: Horizontal Header Table
+``hhea``: Horizontal Header table
 ---------------------------------
 
+The ``hhea`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._h_h_e_a
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_h_m_t_x.rst

@@ -1,8 +1,9 @@
-``hmtx``: Horizontal Metrics Table
+``hmtx``: Horizontal Metrics table
 ----------------------------------
 
+The ``hmtx`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._h_m_t_x
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_k_e_r_n.rst

@@ -1,8 +1,9 @@
-``kern``: Kerning
+``kern``: Kerning table
------------------
+-----------------------
+
+The ``kern`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables._k_e_r_n
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_l_c_a_r.rst

@@ -1,8 +1,9 @@
 ``lcar``: Ligature Caret Table
 ------------------------------
 
+The ``lcar`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._l_c_a_r
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_l_o_c_a.rst

@@ -1,8 +1,9 @@
-``loca``: Index to Location
+``loca``: Index to Location table
----------------------------
+---------------------------------
+
+The ``loca`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables._l_o_c_a
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_l_t_a_g.rst

@@ -1,8 +1,9 @@
-``ltag``: Language Tag
+``ltag``: Language Tag table
-----------------------
+----------------------------
+
+The ``ltag`` table is an Apple Advanced Typography (AAT) table.
 
 .. automodule:: fontTools.ttLib.tables._l_t_a_g
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_m_a_x_p.rst

@@ -1,8 +1,9 @@
-``maxp``: Maximum Profile
+``maxp``: Maximum Profile table
--------------------------
+-------------------------------
+
+The ``maxp`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables._m_a_x_p
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_m_e_t_a.rst

@@ -1,8 +1,9 @@
-``meta``: Metadata Table
+``meta``: Metadata table
 ------------------------
 
+The ``meta`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._m_e_t_a
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_m_o_r_t.rst

@@ -1,8 +1,9 @@
 ``mort``: Glyph Metamorphosis Table
 -----------------------------------
 
+The ``mort`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._m_o_r_t
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_m_o_r_x.rst

@@ -1,8 +1,9 @@
 ``morx``: Extended Glyph Metamorphosis Table
 --------------------------------------------
 
+The ``morx`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._m_o_r_x
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_n_a_m_e.rst

@@ -1,8 +1,9 @@
-``name``: Naming Table
+``name``: Naming table
 ----------------------
 
+The ``name`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._n_a_m_e
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_o_p_b_d.rst

@@ -1,8 +1,9 @@
 ``opbd``: Optical Bounds Table
 ------------------------------
 
+The ``opbd`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._o_p_b_d
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_p_o_s_t.rst

@@ -1,8 +1,9 @@
-``post``: PostScript Table
+``post``: PostScript table
 --------------------------
 
+The ``post`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._p_o_s_t
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_p_r_e_p.rst

@@ -1,8 +1,9 @@
-``prep``: Control Value Program
+``prep``: Control Value Program table
--------------------------------
+-------------------------------------
+
+The ``prep`` table is an OpenType table.
 
 .. automodule:: fontTools.ttLib.tables._p_r_e_p
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_p_r_o_p.rst

@@ -1,8 +1,9 @@
 ``prop``: Glyph Properties Table
 --------------------------------
 
+The ``prop`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._p_r_o_p
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_s_b_i_x.rst

@@ -1,25 +1,12 @@
-``sbix``: Standard Bitmap Graphics Table
+``sbix``: Standard Bitmap Graphics table
 ----------------------------------------
 
+The ``sbix`` table is an OpenType table.
+
+This ``sbix`` table converter module depends on the
+:mod:`.sbixGlyph` and :mod:`.sbixStrike` modules.
+
+
 .. automodule:: fontTools.ttLib.tables._s_b_i_x
-   :inherited-members:
-   :members:
-   :undoc-members:
-
-
-
-sbixGlyph
-^^^^^^^^^
-
-.. automodule:: fontTools.ttLib.tables.sbixGlyph
-   :inherited-members:
-   :members:
-   :undoc-members:
-
-sbixStrike
-^^^^^^^^^^
-
-.. automodule:: fontTools.ttLib.tables.sbixStrike
-   :inherited-members:
    :members:
    :undoc-members:

Doc/source/ttLib/tables/_t_r_a_k.rst

@@ -1,8 +1,9 @@
 ``trak``: Tracking table
 ------------------------
 
+The ``trak`` table is an Apple Advanced Typography (AAT) table.
+
 .. automodule:: fontTools.ttLib.tables._t_r_a_k
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_v_h_e_a.rst

@@ -1,8 +1,9 @@
-``vhea``: Vertical Header Table
+``vhea``: Vertical Header table
 -------------------------------
 
+The ``vhea`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._v_h_e_a
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/_v_m_t_x.rst

@@ -1,8 +1,9 @@
-``vmtx``: Vertical Metrics Table
+``vmtx``: Vertical Metrics table
 --------------------------------
 
+The ``vmtx`` table is an OpenType table.
+
 .. automodule:: fontTools.ttLib.tables._v_m_t_x
-   :inherited-members:
    :members:
    :undoc-members:
 

Doc/source/ttLib/tables/grUtils.rst

@@ -0,0 +1,17 @@
+############################
+Graphite table helper module
+############################
+
+.. rubric:: Overview:
+   :heading-level: 2
+
+The :mod:`grUtils` module is a helper for :mod:`fontTools.ttLib` that
+provides lower-level support for Graphite table converters.
+
+.. rubric:: Module members:
+   :heading-level: 2
+
+.. automodule:: fontTools.ttLib.tables.grUtils
+   :inherited-members:
+   :members:
+   :undoc-members:

Doc/source/ttLib/tables/table_api.rst

@@ -0,0 +1,83 @@
+##########################
+Base table classes and API
+##########################
+
+.. contents:: On this page:
+    :local:
+
+.. rubric:: Overview:
+   :heading-level: 2
+
+The modules documented on this page are the base classes on which the
+:mod:`fontTools.ttLib` table converters are built. The
+:class:`.DefaultTable` is the most general; :class:`.asciiTable` is a
+simpler option for storing text-based data. For OpenType and TrueType
+fonts, the :class:`.otBase.BaseTTXConverter` leverages the model used
+by the majority of existing OpenType/TrueType converters.
+
+
+Contributing your own table convertors
+--------------------------------------
+
+To add support for a new font table that fontTools does not currently implement,
+you must subclass from :py:mod:`fontTools.ttLib.tables.DefaultTable.DefaultTable`.
+It provides some default behavior, as well as a constructor method (``__init__``)
+that you don't need to override.
+
+Your converter should minimally provide two methods::
+
+
+    class table_F_O_O_(DefaultTable.DefaultTable): # converter for table 'FOO '
+
+        def decompile(self, data, ttFont):
+            # 'data' is the raw table data. Unpack it into a
+            # Python data structure.
+            # 'ttFont' is a ttLib.TTfile instance, enabling you to
+            # refer to other tables. Do ***not*** keep a reference to
+            # it: it will cause a circular reference (ttFont saves
+            # a reference to us), and that means we'll be leaking
+            # memory. If you need to use it in other methods, just
+            # pass it around as a method argument.
+
+        def compile(self, ttFont):
+            # Return the raw data, as converted from the Python
+            # data structure.
+            # Again, 'ttFont' is there so you can access other tables.
+            # Same warning applies.
+
+
+If you want to support TTX import/export as well, you need to provide two
+additional methods::
+
+
+   def toXML(self, writer, ttFont):
+      # XXX
+
+   def fromXML(self, (name, attrs, content), ttFont):
+      # XXX
+
+      
+
+fontTools.ttLib.tables.DefaultTable
+-----------------------------------
+
+.. automodule:: fontTools.ttLib.tables.DefaultTable
+   :members:
+   :undoc-members:
+
+
+fontTools.ttLib.tables.asciiTable
+---------------------------------
+
+.. automodule:: fontTools.ttLib.tables.asciiTable
+   :members:
+   :undoc-members:
+
+
+fontTools.ttLib.tables.otBase
+-----------------------------
+
+.. automodule:: fontTools.ttLib.tables.otBase
+   :members:
+   :undoc-members:
+

Doc/source/ttLib/tables/ttProgram.rst

@@ -0,0 +1,16 @@
+###################################################
+ttProgram: TrueType bytecode assembler/disassembler
+###################################################
+
+.. rubric:: Overview:
+   :heading-level: 2
+
+The :mod:`fontTools.ttLib.ttProgram` module is a helper for
+:mod:`fontTools.ttLib`.
+
+.. automodule:: fontTools.ttLib.tables.ttProgram
+   :members:
+   :undoc-members:
+    
+    .. rubric:: Module members:
+       :heading-level: 2

Lib/fontTools/ttLib/tables/B_A_S_E_.py

@@ -2,4 +2,13 @@ from .otBase import BaseTTXConverter
 
 
 class table_B_A_S_E_(BaseTTXConverter):
+    """Baseline table
+
+    The ``BASE`` table contains information needed to align glyphs in
+    different scripts, from different fonts, or at different sizes
+    within the same line of text.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/base
+    """
+
     pass

Lib/fontTools/ttLib/tables/C_B_D_T_.py

@@ -21,6 +21,16 @@ import struct
 
 
 class table_C_B_D_T_(E_B_D_T_.table_E_B_D_T_):
+    """Color Bitmap Data table
+
+    The ``CBDT`` table contains color bitmap data for glyphs. It must
+    be used in concert with the ``CBLC`` table.
+
+    It is backwards-compatible with the monochrome/grayscale ``EBDT`` table.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/cbdt
+    """
+
     # Change the data locator table being referenced.
     locatorName = "CBLC"
 

Lib/fontTools/ttLib/tables/C_B_L_C_.py

@@ -6,4 +6,14 @@ from . import E_B_L_C_
 
 
 class table_C_B_L_C_(E_B_L_C_.table_E_B_L_C_):
+    """Color Bitmap Location table
+
+    The ``CBLC`` table contains the locations of color bitmaps for glyphs. It must
+    be used in concert with the ``CBDT`` table.
+
+    It is backwards-compatible with the monochrome/grayscale ``EBLC`` table.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/cblc
+    """
+
     dependencies = ["CBDT"]

Lib/fontTools/ttLib/tables/C_F_F_.py

@@ -4,6 +4,21 @@ from . import DefaultTable
 
 
 class table_C_F_F_(DefaultTable.DefaultTable):
+    """Compact Font Format table (version 1)
+
+    The ``CFF`` table embeds a CFF-formatted font. The CFF font format
+    predates OpenType and could be used as a standalone font file, but the
+    ``CFF`` table is also used to package CFF fonts into an OpenType
+    container.
+
+    .. note::
+       ``CFF`` has been succeeded by ``CFF2``, which eliminates much of
+       the redundancy incurred by embedding CFF version 1 in an OpenType
+       font.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/cff
+    """
+
     def __init__(self, tag=None):
         DefaultTable.DefaultTable.__init__(self, tag)
         self.cff = cffLib.CFFFontSet()

Lib/fontTools/ttLib/tables/C_F_F__2.py

@@ -3,6 +3,19 @@ from fontTools.ttLib.tables.C_F_F_ import table_C_F_F_
 
 
 class table_C_F_F__2(table_C_F_F_):
+    """Compact Font Format version 2 table
+
+    The ``CFF2`` table contains glyph data for a CFF2-flavored OpenType
+    font.
+
+    .. note::
+       ``CFF2`` is the successor to ``CFF``, and eliminates much of
+       the redundancy incurred by embedding CFF version 1 in an OpenType
+       font.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/cff2
+    """
+
     def decompile(self, data, otFont):
         self.cff.decompile(BytesIO(data), otFont, isCFF2=True)
         assert len(self.cff) == 1, "can't deal with multi-font CFF tables."

Lib/fontTools/ttLib/tables/C_O_L_R_.py

@@ -7,11 +7,19 @@ from . import DefaultTable
 
 
 class table_C_O_L_R_(DefaultTable.DefaultTable):
-    """This table is structured so that you can treat it like a dictionary keyed by glyph name.
+    """Color table
+
+    The ``COLR`` table defines color presentation of outline glyphs. It must
+    be used in concert with the ``CPAL`` table, which contains the color
+    descriptors used.
+
+    This table is structured so that you can treat it like a dictionary keyed by glyph name.
 
     ``ttFont['COLR'][<glyphName>]`` will return the color layers for any glyph.
 
     ``ttFont['COLR'][<glyphName>] = <value>`` will set the color layers for any glyph.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/colr
     """
 
     @staticmethod

Lib/fontTools/ttLib/tables/C_P_A_L_.py

@@ -11,6 +11,15 @@ import sys
 
 
 class table_C_P_A_L_(DefaultTable.DefaultTable):
+    """Color Palette table
+
+    The ``CPAL`` table contains a set of one or more color palettes. The color
+    records in each palette can be referenced by the ``COLR`` table to specify
+    the colors used in a color glyph.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/cpal
+    """
+
     NO_NAME_ID = 0xFFFF
     DEFAULT_PALETTE_TYPE = 0
 

Lib/fontTools/ttLib/tables/D_S_I_G_.py

@@ -39,6 +39,13 @@ DSIG_SignatureBlockFormat = """
 
 
 class table_D_S_I_G_(DefaultTable.DefaultTable):
+    """Digital Signature table
+
+    The ``DSIG`` table contains cryptographic signatures for the font.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/dsig
+    """
+
     def decompile(self, data, ttFont):
         dummy, newData = sstruct.unpack2(DSIG_HeaderFormat, data, self)
         assert self.ulVersion == 1, "DSIG ulVersion must be 1"

Lib/fontTools/ttLib/tables/E_B_D_T_.py

@@ -38,6 +38,14 @@ ebdtComponentFormat = """
 
 
 class table_E_B_D_T_(DefaultTable.DefaultTable):
+    """Embedded Bitmap Data table
+
+    The ``EBDT`` table contains monochrome or grayscale bitmap data for
+    glyphs. It must be used in concert with the ``EBLC`` table.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/ebdt
+    """
+
     # Keep a reference to the name of the data locator table.
     locatorName = "EBLC"
 

Lib/fontTools/ttLib/tables/E_B_L_C_.py

@@ -66,6 +66,14 @@ codeOffsetPairSize = struct.calcsize(codeOffsetPairFormat)
 
 
 class table_E_B_L_C_(DefaultTable.DefaultTable):
+    """Embedded Bitmap Location table
+
+    The ``EBLC`` table contains the locations of monochrome or grayscale
+    bitmaps for glyphs. It must be used in concert with the ``EBDT`` table.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/eblc
+    """
+
     dependencies = ["EBDT"]
 
     # This method can be overridden in subclasses to support new formats

Lib/fontTools/ttLib/tables/F_F_T_M_.py

@@ -13,6 +13,16 @@ FFTMFormat = """
 
 
 class table_F_F_T_M_(DefaultTable.DefaultTable):
+    """FontForge Time Stamp table
+
+    The ``FFTM`` table is used by the free-software font editor
+    FontForge to record timestamps for the creation and modification
+    of font source (.sfd) files and a timestamp for FontForge's
+    own source code.
+
+    See also https://fontforge.org/docs/techref/non-standard.html
+    """
+
     def decompile(self, data, ttFont):
         dummy, rest = sstruct.unpack2(FFTMFormat, data, self)
 

Lib/fontTools/ttLib/tables/F__e_a_t.py

@@ -12,12 +12,17 @@ Feat_hdr_format = """
 
 
 class table_F__e_a_t(DefaultTable.DefaultTable):
-    """The ``Feat`` table is used exclusively by the Graphite shaping engine
+    """Feature table
+
+    The ``Feat`` table is used exclusively by the Graphite shaping engine
     to store features and possible settings specified in GDL. Graphite features
     determine what rules are applied to transform a glyph stream.
 
     Not to be confused with ``feat``, or the OpenType Layout tables
-    ``GSUB``/``GPOS``."""
+    ``GSUB``/``GPOS``.
+
+    See also https://graphite.sil.org/graphite_techAbout#graphite-font-tables
+    """
 
     def __init__(self, tag=None):
         DefaultTable.DefaultTable.__init__(self, tag)

Lib/fontTools/ttLib/tables/G_D_E_F_.py

@@ -2,4 +2,12 @@ from .otBase import BaseTTXConverter
 
 
 class table_G_D_E_F_(BaseTTXConverter):
+    """Glyph Definition table
+
+    The ``GDEF`` table stores various glyph properties that are used
+    by OpenType Layout.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/gdef
+    """
+
     pass

Lib/fontTools/ttLib/tables/G_M_A_P_.py

@@ -81,6 +81,13 @@ class GMAPRecord(object):
 
 
 class table_G_M_A_P_(DefaultTable.DefaultTable):
+    """Glyphlets GMAP table
+
+    The ``GMAP`` table is used by Adobe's SING Glyphlets.
+
+    See also https://web.archive.org/web/20080627183635/http://www.adobe.com/devnet/opentype/gdk/topic.html
+    """
+
     dependencies = []
 
     def decompile(self, data, ttFont):

Lib/fontTools/ttLib/tables/G_P_K_G_.py

@@ -16,6 +16,13 @@ GPKGFormat = """
 
 
 class table_G_P_K_G_(DefaultTable.DefaultTable):
+    """Glyphlets GPKG table
+
+    The ``GPKG`` table is used by Adobe's SING Glyphlets.
+
+    See also https://web.archive.org/web/20080627183635/http://www.adobe.com/devnet/opentype/gdk/topic.html
+    """
+
     def decompile(self, data, ttFont):
         dummy, newData = sstruct.unpack2(GPKGFormat, data, self)
 

Lib/fontTools/ttLib/tables/G_P_O_S_.py

@@ -2,4 +2,13 @@ from .otBase import BaseTTXConverter
 
 
 class table_G_P_O_S_(BaseTTXConverter):
+    """Glyph Positioning table
+
+    The ``GPOS`` table stores advanced glyph-positioning data
+    used in OpenType Layout features, such as mark attachment,
+    cursive attachment, kerning, and other position adjustments.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/gpos
+    """
+
     pass

Lib/fontTools/ttLib/tables/G_S_U_B_.py

@@ -2,4 +2,12 @@ from .otBase import BaseTTXConverter
 
 
 class table_G_S_U_B_(BaseTTXConverter):
+    """Glyph Substitution table
+
+    The ``GSUB`` table contains glyph-substitution rules used in
+    OpenType Layout.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/gsub
+    """
+
     pass

Lib/fontTools/ttLib/tables/G__l_a_t.py

@@ -62,8 +62,9 @@ class _Dict(dict):
 
 
 class table_G__l_a_t(DefaultTable.DefaultTable):
-    """
+    """Graphite Glyph Attributes table
-    Support Graphite Glat tables
+
+    See also https://graphite.sil.org/graphite_techAbout#graphite-font-tables
     """
 
     def __init__(self, tag=None):

Lib/fontTools/ttLib/tables/G__l_o_c.py

@@ -15,8 +15,9 @@ Gloc_header = """
 
 
 class table_G__l_o_c(DefaultTable.DefaultTable):
-    """
+    """Graphite Index to Glyph Atttributes table
-    Support Graphite Gloc tables
+
+    See also https://graphite.sil.org/graphite_techAbout#graphite-font-tables
     """
 
     dependencies = ["Glat"]

Lib/fontTools/ttLib/tables/H_V_A_R_.py

@@ -2,4 +2,12 @@ from .otBase import BaseTTXConverter
 
 
 class table_H_V_A_R_(BaseTTXConverter):
+    """Horizontal Metrics Variations table
+
+    The ``HVAR`` table contains variations in horizontal glyph metrics
+    in variable fonts.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/hvar
+    """
+
     pass

Lib/fontTools/ttLib/tables/J_S_T_F_.py

@@ -2,4 +2,12 @@ from .otBase import BaseTTXConverter
 
 
 class table_J_S_T_F_(BaseTTXConverter):
+    """Justification table
+
+    The ``JSTF`` table contains glyph substitution and positioning
+    data used to perform text justification.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/jstf
+    """
+
     pass

Lib/fontTools/ttLib/tables/L_T_S_H_.py

@@ -9,6 +9,16 @@ import array
 
 
 class table_L_T_S_H_(DefaultTable.DefaultTable):
+    """Linear Threshold table
+
+    The ``LTSH`` table contains per-glyph settings indicating the ppem sizes
+    at which the advance width metric should be scaled linearly, despite the
+    effects of any TrueType instructions that might otherwise alter the
+    advance width.
+
+    See also https://learn.microsoft.com/en-us/typography/opentype/spec/ltsh
+    """
+
     def decompile(self, data, ttFont):
         version, numGlyphs = struct.unpack(">HH", data[:4])
         data = data[4:]