From 9f833fe5188d38c3078235930d2b62d88f3ef162 Mon Sep 17 00:00:00 2001
From: Nathan Williis <n8willis@gmail.com>
Date: Sat, 7 Dec 2024 17:00:01 +0000
Subject: [PATCH] Beef up TTFont and glyphSet explanations.

---
 Doc/source/ttLib/index.rst      |  4 ++--
 Doc/source/ttLib/ttFont.rst     | 42 ++++++++++++++++-----------------
 Doc/source/ttLib/ttGlyphSet.rst |  5 ++++
 3 files changed, 28 insertions(+), 23 deletions(-)

diff --git a/Doc/source/ttLib/index.rst b/Doc/source/ttLib/index.rst
index b03f8f105..0f5e3946a 100644
--- a/Doc/source/ttLib/index.rst
+++ b/Doc/source/ttLib/index.rst
@@ -16,10 +16,10 @@ 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
 
diff --git a/Doc/source/ttLib/ttFont.rst b/Doc/source/ttLib/ttFont.rst
index c3a41ba78..7c7a60da6 100644
--- a/Doc/source/ttLib/ttFont.rst
+++ b/Doc/source/ttLib/ttFont.rst
@@ -20,21 +20,21 @@ 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
+``.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.
 
-
-ttGlyphs
---------
-
 Informally, some fontTools code or documentation will make reference to
-the individual glyphs in a ``glyphSet`` as a "ttGlyph" or the
+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
+"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
@@ -43,23 +43,23 @@ 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``
+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
+    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
@@ -78,8 +78,8 @@ methods. See the :doc:`pens </pens/index>` package documenation
 for more.
 
 
-.. rubric:: Package contents:
-   :heading-level: 2
+Package contents
+----------------
  
 
 .. autoclass:: fontTools.ttLib.ttFont.TTFont
diff --git a/Doc/source/ttLib/ttGlyphSet.rst b/Doc/source/ttLib/ttGlyphSet.rst
index 8f06b3ea7..2bbfc7331 100644
--- a/Doc/source/ttLib/ttGlyphSet.rst
+++ b/Doc/source/ttLib/ttGlyphSet.rst
@@ -8,6 +8,11 @@ ttGlyphSet: GlyphSets returned by a TTFont object
 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: