From ebb2b9cd9484bbbf12811d54ed690122411629f1 Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Wed, 4 Dec 2024 16:04:51 +0000 Subject: [PATCH] Docs, tables. Add pages for various helper and ancillary modules. --- Doc/source/ttLib/tables/Bitmap_related.rst | 36 +++++++++ Doc/source/ttLib/tables/OpenType_related.rst | 46 +++++++++++ Doc/source/ttLib/tables/TupleVariation.rst | 16 ++++ Doc/source/ttLib/tables/grUtils.rst | 17 ++++ Doc/source/ttLib/tables/table_api.rst | 83 ++++++++++++++++++++ Doc/source/ttLib/tables/ttProgram.rst | 16 ++++ 6 files changed, 214 insertions(+) create mode 100644 Doc/source/ttLib/tables/Bitmap_related.rst create mode 100644 Doc/source/ttLib/tables/OpenType_related.rst create mode 100644 Doc/source/ttLib/tables/TupleVariation.rst create mode 100644 Doc/source/ttLib/tables/grUtils.rst create mode 100644 Doc/source/ttLib/tables/table_api.rst create mode 100644 Doc/source/ttLib/tables/ttProgram.rst diff --git a/Doc/source/ttLib/tables/Bitmap_related.rst b/Doc/source/ttLib/tables/Bitmap_related.rst new file mode 100644 index 000000000..1372d1950 --- /dev/null +++ b/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 :mod:`fontTools.ttLib.ttCollection` module is a helper for +:mod:`fontTools.ttLib` that implements 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: diff --git a/Doc/source/ttLib/tables/OpenType_related.rst b/Doc/source/ttLib/tables/OpenType_related.rst new file mode 100644 index 000000000..608d1f0d0 --- /dev/null +++ b/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: diff --git a/Doc/source/ttLib/tables/TupleVariation.rst b/Doc/source/ttLib/tables/TupleVariation.rst new file mode 100644 index 000000000..afeff5c0c --- /dev/null +++ b/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: diff --git a/Doc/source/ttLib/tables/grUtils.rst b/Doc/source/ttLib/tables/grUtils.rst new file mode 100644 index 000000000..d2ad899c4 --- /dev/null +++ b/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: diff --git a/Doc/source/ttLib/tables/table_api.rst b/Doc/source/ttLib/tables/table_api.rst new file mode 100644 index 000000000..3fa8647cb --- /dev/null +++ b/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: + diff --git a/Doc/source/ttLib/tables/ttProgram.rst b/Doc/source/ttLib/tables/ttProgram.rst new file mode 100644 index 000000000..091e22374 --- /dev/null +++ b/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