otlLib documentation (#2009)

Document otlLib

Includes other minor changes:

* When a markFilterSet parameter is passed to a builder, LOOKUP_FLAG_USE_MARK_FILTERING_SET will be added to the lookup's flags.
* The unused arguments valueformat1 and valueformat2 were removed from ClassPairPosSubtableBuilder.

Doc/source/otlLib/builder.rst

@@ -1,8 +0,0 @@
-#######
-builder
-#######
-
-.. automodule:: fontTools.otlLib.builder
-   :inherited-members:
-   :members:
-   :undoc-members:

Doc/source/otlLib/index.rst

@@ -1,13 +1,74 @@
-######
+#################################################
-otlLib
+otlLib: Routines for working with OpenType Layout
-######
+#################################################
 
-.. toctree::
+The ``fontTools.otlLib`` library provides routines to help you create the
-   :maxdepth: 2
+subtables and other data structures you need when you are editing a font's
+``GSUB`` and ``GPOS`` tables: substitution and positioning rules, anchors,
+lookups, coverage tables and so on.
 
-   builder
+------------------------------------------
+High-level OpenType Layout Lookup Builders
+------------------------------------------
 
-.. automodule:: fontTools.otlLib
+.. automodule:: fontTools.otlLib.builder
-   :inherited-members:
+   :members: AlternateSubstBuilder, ChainContextPosBuilder, ChainContextSubstBuilder, LigatureSubstBuilder, MultipleSubstBuilder, CursivePosBuilder, MarkBasePosBuilder, MarkLigPosBuilder, MarkMarkPosBuilder, ReverseChainSingleSubstBuilder, SingleSubstBuilder, ClassPairPosSubtableBuilder, PairPosBuilder, SinglePosBuilder
-   :members:
+   :member-order: bysource
-   :undoc-members:
+
+--------------------------------------
+Common OpenType Layout Data Structures
+--------------------------------------
+
+.. automodule:: fontTools.otlLib.builder
+   :members: buildCoverage, buildLookup
+
+------------------------------------
+Low-level GSUB Table Lookup Builders
+------------------------------------
+
+These functions deal with the "simple" lookup types. See above for classes to
+help build more complex lookups (contextual and chaining lookups).
+
+.. automodule:: fontTools.otlLib.builder
+   :members: buildSingleSubstSubtable, buildMultipleSubstSubtable, buildAlternateSubstSubtable, buildLigatureSubstSubtable
+
+--------------------------
+GPOS Shared Table Builders
+--------------------------
+
+The functions help build the `GPOS shared tables <https://docs.microsoft.com/en-us/typography/opentype/spec/gpos#shared-tables-value-record-anchor-table-and-mark-array-table>`_
+as defined in the OpenType spec: value records, anchors, mark arrays and
+mark record tables.
+
+.. automodule:: fontTools.otlLib.builder
+   :members: buildValue, buildAnchor, buildMarkArray, buildDevice, buildBaseArray, buildComponentRecord, buildMarkArray, buildValue
+   :member-order: bysource
+
+------------------------------------
+Low-level GPOS Table Lookup Builders
+------------------------------------
+
+These functions deal with the "simple" lookup types. See above for classes to
+help build more complex lookups (contextual and chaining lookups).
+
+.. automodule:: fontTools.otlLib.builder
+   :members: buildCursivePosSubtable, buildLigatureArray, buildMarkBasePos, buildMarkBasePosSubtable, buildMarkLigPos, buildMarkLigPosSubtable, buildPairPosClassesSubtable, buildPairPosGlyphs, buildPairPosGlyphsSubtable, buildSinglePos, buildSinglePosSubtable
+   :member-order: bysource
+
+----------------------------
+GDEF Table Subtable Builders
+----------------------------
+
+These functions build subtables for elements of the ``GDEF`` table.
+
+.. automodule:: fontTools.otlLib.builder
+   :members: buildAttachList, buildLigCaretList, buildMarkGlyphSetsDef
+   :member-order: bysource
+
+------------------
+STAT Table Builder
+------------------
+
+.. automodule:: fontTools.otlLib.builder
+   :members: buildStatTable
+   :member-order: bysource

README.rst

@@ -201,15 +201,15 @@ In alphabetical order:
 
 Olivier Berten, Samyak Bhuta, Erik van Blokland, Petr van Blokland,
 Jelle Bosma, Sascha Brawer, Tom Byrer, Frédéric Coiffier, Vincent
-Connare, David Corbett, Dave Crossland, Simon Daniels, Peter Dekkers,
+Connare, David Corbett, Simon Cozens, Dave Crossland, Simon Daniels,
-Behdad Esfahbod, Behnam Esfahbod, Hannes Famira, Sam Fishman, Matt
+Peter Dekkers, Behdad Esfahbod, Behnam Esfahbod, Hannes Famira, Sam
-Fontaine, Yannis Haralambous, Greg Hitchcock, Jeremie Hornus, Khaled
+Fishman, Matt Fontaine, Yannis Haralambous, Greg Hitchcock, Jeremie
-Hosny, John Hudson, Denis Moyogo Jacquerye, Jack Jansen, Tom Kacvinsky,
+Hornus, Khaled Hosny, John Hudson, Denis Moyogo Jacquerye, Jack Jansen,
-Jens Kutilek, Antoine Leca, Werner Lemberg, Tal Leming, Peter Lofting,
+Tom Kacvinsky, Jens Kutilek, Antoine Leca, Werner Lemberg, Tal Leming,
-Cosimo Lupo, Masaya Nakamura, Dave Opstad, Laurence Penney, Roozbeh
+Peter Lofting, Cosimo Lupo, Masaya Nakamura, Dave Opstad, Laurence
-Pournader, Garret Rieger, Read Roberts, Guido van Rossum, Just van
+Penney, Roozbeh Pournader, Garret Rieger, Read Roberts, Guido van
-Rossum, Andreas Seidel, Georg Seifert, Chris Simpkins, Miguel Sousa,
+Rossum, Just van Rossum, Andreas Seidel, Georg Seifert, Chris Simpkins,
-Adam Twardoch, Adrien Tétar, Vitaly Volkov, Paul Wise.
+Miguel Sousa, Adam Twardoch, Adrien Tétar, Vitaly Volkov, Paul Wise.
 
 Copyrights
 ~~~~~~~~~~

Tests/otlLib/builder_test.py

@@ -495,14 +495,6 @@ class BuilderTest(object):
             ),
         ) as excinfo:
             builder.buildLookup([s], builder.LOOKUP_FLAG_USE_MARK_FILTERING_SET, None)
-        with pytest.raises(
-            AssertionError,
-            match=(
-                "if markFilterSet is not None, flags must set "
-                "LOOKUP_FLAG_USE_MARK_FILTERING_SET; flags=0x0004"
-            ),
-        ) as excinfo:
-            builder.buildLookup([s], builder.LOOKUP_FLAG_IGNORE_LIGATURES, 777)
 
     def test_buildLookup_conflictingSubtableTypes(self):
         s1 = builder.buildSingleSubstSubtable({"one": "two"})