[docs] Document feaLib (#1941)

[docs] Document feaLib

* Rearrange docs by user intention, highlighting the things you can do with each component.
* Remove reference to lexer and error modules from documentation tree, since they’re not user-facing.
* I’ve added docstrings to the parser even though we only provide access to the user-facing part of the API in the main documentation, just to clarify what some of the more obscure methods do and provide links to the spec.
* AST *is* user-facing if you’re building your own feature files in code, so all classes are documented with the user in mind.

Doc/source/feaLib/index.rst

@@ -1,17 +1,40 @@
-######
-feaLib
-######
+#########################################
+feaLib: Read/write OpenType feature files
+#########################################
 
-.. toctree::
-   :maxdepth: 1
+fontTools' ``feaLib`` allows for the creation and parsing of Adobe
+Font Development Kit for OpenType feature (``.fea``) files. The syntax
+of these files is described `here <https://adobe-type-tools.github.io/afdko/OpenTypeFeatureFileSpecification.html>`_.
 
-   ast
-   builder
-   error
-   lexer
-   parser
+The :class:`fontTools.feaLib.parser.Parser` class can be used to parse files
+into an abstract syntax tree, and from there the
+:class:`fontTools.feaLib.builder.Builder` class can add features to an existing
+font file. You can inspect the parsed syntax tree, walk the tree and do clever
+things with it, and also generate your own feature files programmatically, by
+using the classes in the :mod:`fontTools.feaLib.ast` module.
 
-.. automodule:: fontTools.feaLib
-   :inherited-members:
+Parsing
+-------
+
+.. autoclass:: fontTools.feaLib.parser.Parser
+   :members: parse
+   :member-order: bysource
+
+Building
+---------
+
+.. automodule:: fontTools.feaLib.builder
+   :members: addOpenTypeFeatures, addOpenTypeFeaturesFromString
+
+Generation/Interrogation
+------------------------
+
+.. _`glyph-containing object`:
+.. _`glyph-containing objects`:
+
+In the below, a **glyph-containing object** is an object of one of the following
+classes: :class:`GlyphName`, :class:`GlyphClass`, :class:`GlyphClassName`.
+
+.. automodule:: fontTools.feaLib.ast
+   :member-order: bysource
    :members:
-   :undoc-members: