[docs] Document fontTools.merge (#1949)

[docs] Document fontTools.merge

Doc/source/merge.rst

@@ -1,8 +1,10 @@
-#####
-merge
-#####
+####################################
+merge: Merge multiple fonts into one
+####################################
 
-.. automodule:: fontTools.merge
+``fontTools.merge`` provides both a library and a command line interface
+(``fonttools merge``) for merging multiple fonts together.
+
+.. autoclass:: fontTools.merge.Merger
    :inherited-members:
    :members:
-   :undoc-members:

Lib/fontTools/merge.py

@@ -948,6 +948,34 @@ def __delitem__(self, k):
 		del self.d[id(k)]
 
 class Merger(object):
+	"""Font merger.
+
+	This class merges multiple files into a single OpenType font, taking into
+	account complexities such as OpenType layout (``GSUB``/``GPOS``) tables and
+	cross-font metrics (e.g. ``hhea.ascent`` is set to the maximum value across
+	all the fonts).
+
+	If multiple glyphs map to the same Unicode value, and the glyphs are considered
+	sufficiently different (that is, they differ in any of paths, widths, or
+	height), then subsequent glyphs are renamed and a lookup in the ``locl``
+	feature will be created to disambiguate them. For example, if the arguments
+	are an Arabic font and a Latin font and both contain a set of parentheses,
+	the Latin glyphs will be renamed to ``parenleft#1`` and ``parenright#1``,
+	and a lookup will be inserted into the to ``locl`` feature (creating it if
+	necessary) under the ``latn`` script to substitute ``parenleft`` with
+	``parenleft#1`` etc.
+
+	Restrictions:
+
+	- All fonts must currently have TrueType outlines (``glyf`` table).
+		Merging fonts with CFF outlines is not supported.
+	- All fonts must have the same units per em.
+	- If duplicate glyph disambiguation takes place as described above then the
+		fonts must have a ``GSUB`` table.
+
+	Attributes:
+		options: Currently unused.
+	"""
 
 	def __init__(self, options=None):
 
@@ -957,7 +985,15 @@ def __init__(self, options=None):
 		self.options = options
 
 	def merge(self, fontfiles):
+		"""Merges fonts together.
 
+		Args:
+			fontfiles: A list of file names to be merged
+
+		Returns:
+			A :class:`fontTools.ttLib.TTFont` object. Call the ``save`` method on
+			this to write it out to an OTF file.
+		"""
 		mega = ttLib.TTFont()
 
 		#