[Docs] Update ttLib 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"
@@ -16,8 +22,40 @@ fonts.
    :maxdepth: 2
 
    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:

Doc/source/ttLib/ttFont.rst

@@ -1,17 +1,53 @@
-##############################################
+####################################
-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. 
+
+In addition to font-wide data, :mod:`.ttLib.ttFont` provides access to
+individual glyphs through the :class:`.TTFont` object's
+``glyphSet[]``. This 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.
+
+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.
+
+
+.. rubric:: Package contents:
+   :heading-level: 2
+ 
 
 .. 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,13 @@
+#################################################
+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`.
+
+.. automodule:: fontTools.ttLib.ttGlyphSet
+   :members:
+   :undoc-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: