From 19f8ad5bf4f51d44cbc771d1d1ef60e60f800cbe Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Fri, 6 Dec 2024 14:04:27 +0000 Subject: [PATCH] [Docs] Update ttLib documentation --- Doc/source/ttLib/index.rst | 40 ++++++++++++++++++- Doc/source/ttLib/macUtils.rst | 7 ++-- Doc/source/ttLib/removeOverlaps.rst | 13 ++++++ Doc/source/ttLib/reorderGlyphs.rst | 13 ++++++ Doc/source/ttLib/scaleUpem.rst | 13 ++++++ Doc/source/ttLib/sfnt.rst | 7 ++-- Doc/source/ttLib/standardGlyphOrder.rst | 7 ++-- Doc/source/ttLib/tables/TupleVariation.rst | 2 + Doc/source/ttLib/ttCollection.rst | 17 +++++--- Doc/source/ttLib/ttFont.rst | 46 +++++++++++++++++++--- Doc/source/ttLib/ttGlyphSet.rst | 13 ++++++ Doc/source/ttLib/woff2.rst | 11 ++++-- 12 files changed, 162 insertions(+), 27 deletions(-) create mode 100644 Doc/source/ttLib/removeOverlaps.rst create mode 100644 Doc/source/ttLib/reorderGlyphs.rst create mode 100644 Doc/source/ttLib/scaleUpem.rst create mode 100644 Doc/source/ttLib/ttGlyphSet.rst diff --git a/Doc/source/ttLib/index.rst b/Doc/source/ttLib/index.rst index 656148e5d..b03f8f105 100644 --- a/Doc/source/ttLib/index.rst +++ b/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 diff --git a/Doc/source/ttLib/macUtils.rst b/Doc/source/ttLib/macUtils.rst index 356a911b2..81413301f 100644 --- a/Doc/source/ttLib/macUtils.rst +++ b/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: diff --git a/Doc/source/ttLib/removeOverlaps.rst b/Doc/source/ttLib/removeOverlaps.rst new file mode 100644 index 000000000..83e99922b --- /dev/null +++ b/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: diff --git a/Doc/source/ttLib/reorderGlyphs.rst b/Doc/source/ttLib/reorderGlyphs.rst new file mode 100644 index 000000000..95635588d --- /dev/null +++ b/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: diff --git a/Doc/source/ttLib/scaleUpem.rst b/Doc/source/ttLib/scaleUpem.rst new file mode 100644 index 000000000..4ac16b2d2 --- /dev/null +++ b/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: diff --git a/Doc/source/ttLib/sfnt.rst b/Doc/source/ttLib/sfnt.rst index 29566ab74..a1fa433c3 100644 --- a/Doc/source/ttLib/sfnt.rst +++ b/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: diff --git a/Doc/source/ttLib/standardGlyphOrder.rst b/Doc/source/ttLib/standardGlyphOrder.rst index ca2557bf3..6cb7b4e0d 100644 --- a/Doc/source/ttLib/standardGlyphOrder.rst +++ b/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: diff --git a/Doc/source/ttLib/tables/TupleVariation.rst b/Doc/source/ttLib/tables/TupleVariation.rst index afeff5c0c..5e267e13b 100644 --- a/Doc/source/ttLib/tables/TupleVariation.rst +++ b/Doc/source/ttLib/tables/TupleVariation.rst @@ -2,6 +2,8 @@ OpenType variations helper module ################################# +.. currentmodule:: fontTools.ttLib.tables.TupleVariation + .. rubric:: Overview: :heading-level: 2 diff --git a/Doc/source/ttLib/ttCollection.rst b/Doc/source/ttLib/ttCollection.rst index 0ca4ebd0d..b19fcdbe8 100644 --- a/Doc/source/ttLib/ttCollection.rst +++ b/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 `_ 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: \ No newline at end of file + :undoc-members: diff --git a/Doc/source/ttLib/ttFont.rst b/Doc/source/ttLib/ttFont.rst index d094b29dc..3034a6104 100644 --- a/Doc/source/ttLib/ttFont.rst +++ b/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 +`. 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 +` by providing ``.draw()`` and ``.drawPoints()`` +methods. See the :doc:`pens ` 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 diff --git a/Doc/source/ttLib/ttGlyphSet.rst b/Doc/source/ttLib/ttGlyphSet.rst new file mode 100644 index 000000000..8f06b3ea7 --- /dev/null +++ b/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: diff --git a/Doc/source/ttLib/woff2.rst b/Doc/source/ttLib/woff2.rst index 327bb5b26..b7fcb2975 100644 --- a/Doc/source/ttLib/woff2.rst +++ b/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 ` +external libraries. + .. automodule:: fontTools.ttLib.woff2 - :inherited-members: :members: :undoc-members: