Docs: reconfigure ufoLib documentation.

Doc/source/ufoLib/converters.rst

@@ -1,7 +1,6 @@
-
+#######################################################
-##########
+converters: Conversion functions for kerning and groups
-converters
+#######################################################
-##########
 
 .. automodule:: fontTools.ufoLib.converters
    :inherited-members:

Doc/source/ufoLib/errors.rst

@@ -1,7 +1,6 @@
-
+###################################################
-######
+errors: Exceptions for handling UFO-specific errors
-errors
+###################################################
-######
 
 .. automodule:: fontTools.ufoLib.errors
    :inherited-members:

Doc/source/ufoLib/filenames.rst

@@ -1,7 +1,6 @@
-
+##########################################################################
-#########
+filenames: Functions to convert between file names and user-facing strings
-filenames
+##########################################################################
-#########
 
 .. automodule:: fontTools.ufoLib.filenames
    :inherited-members:

Doc/source/ufoLib/glifLib.rst

@@ -1,7 +1,6 @@
-
+#######################################
-#######
+glifLib: Read and write UFO .glif files
-glifLib
+#######################################
-#######
 
 .. automodule:: fontTools.ufoLib.glifLib
    :inherited-members:

Doc/source/ufoLib/index.rst

@@ -1,22 +1,45 @@
+################################################
+ufoLib: Read and write Unified Font Object files
+################################################
 
-######
+.. rubric:: Overview:
-ufoLib
+   :heading-level: 3
-######
-
-.. toctree::
-   :maxdepth: 1
-
-   converters
-   errors
-   filenames
-   glifLib
-   kerning
-   plistlib
-   pointpen
-   utils
-   validators
 
 .. automodule:: fontTools.ufoLib
    :inherited-members:
    :members: 
    :undoc-members:
+   :member-order: bysource
+
+    .. rubric:: Submodules:
+       :heading-level: 3
+
+    ufoLib provides the following submodules:
+    
+     .. toctree::
+        :maxdepth: 1
+	:titlesonly:
+     
+        converters
+        errors
+        filenames
+        glifLib
+        kerning
+        utils
+        validators
+    	   
+    Two deprecated submodules are also currently included:
+    
+     .. toctree::
+        :maxdepth: 1
+    		  
+        plistlib
+        pointpen
+
+    .. rubric:: Module members:
+       :heading-level: 3
+    		  
+.. autodata:: fontInfoAttributesVersion1
+.. autodata:: fontInfoAttributesVersion2
+.. autodata:: fontInfoAttributesVersion3
+.. autodata:: deprecatedFontInfoAttributesVersion2

Doc/source/ufoLib/kerning.rst

@@ -1,7 +1,6 @@
-
+###########################################
-#######
+kerning: Support for accessing kerning data
-kerning
+###########################################
-#######
 
 .. automodule:: fontTools.ufoLib.kerning
    :inherited-members:

Doc/source/ufoLib/plistlib.rst

@@ -1,9 +1,10 @@
+#####################################################################
+plistlib: Support for reading and writing .plist files *[deprecated]*
+#####################################################################
 
-########
+.. important::
-plistlib
-########
    
-.. automodule:: fontTools.ufoLib.plistlib
+    .. automodule:: fontTools.ufoLib.plistlib
-   :inherited-members:
+       :inherited-members:
-   :members:
+       :members:
-   :undoc-members:
+       :undoc-members:

Doc/source/ufoLib/pointpen.rst

@@ -1,9 +1,10 @@
+######################################################################
+pointPen: A pen for accessing points in a glyph contour *[deprecated]*
+######################################################################
 
-########
+.. important::
-pointPen
-########
    
-.. automodule:: fontTools.ufoLib.pointPen
+    .. automodule:: fontTools.ufoLib.pointPen
-   :inherited-members:
+       :inherited-members:
-   :members:
+       :members:
-   :undoc-members:
+       :undoc-members:

Doc/source/ufoLib/utils.rst

@@ -1,7 +1,6 @@
-
+#####################################
-#####
+utils: Miscellaneous helper functions
-utils
+#####################################
-#####
 
 .. automodule:: fontTools.ufoLib.utils
    :inherited-members:

Doc/source/ufoLib/validators.rst

@@ -1,7 +1,6 @@
-
+#####################################
-##########
+validators: Data-validation functions
-validators
+#####################################
-##########
 
 .. automodule:: fontTools.ufoLib.validators
    :inherited-members:

Lib/fontTools/ufoLib/__init__.py

@@ -1,35 +1,35 @@
 """
 A library for importing .ufo files and their descendants.
-Refer to http://unifiedfontobject.com for the UFO specification.
+Refer to http://unifiedfontobject.org for the UFO specification.
 
-The UFOReader and UFOWriter classes support versions 1, 2 and 3
+The main interfaces are the :class:`.UFOReader` and :class:`.UFOWriter`
-of the specification.
+classes, which support versions 1, 2, and 3 of the UFO specification.
 
-Sets that list the font info attribute names for the fontinfo.plist
+Set variables are available for external use that list the font
-formats are available for external use. These are:
+info attribute names for the `fontinfo.plist` formats. These are:
 
-- fontInfoAttributesVersion1
+- :obj:`.fontInfoAttributesVersion1`
-- fontInfoAttributesVersion2
+- :obj:`.fontInfoAttributesVersion2`
-- fontInfoAttributesVersion3
+- :obj:`.fontInfoAttributesVersion3`
 
-A set listing the fontinfo.plist attributes that were deprecated
+A set listing the `fontinfo.plist` attributes that were deprecated
 in version 2 is available for external use:
 
-- deprecatedFontInfoAttributesVersion2
+- :obj:`.deprecatedFontInfoAttributesVersion2`
 
-Functions that do basic validation on values for fontinfo.plist
+Functions that do basic validation on values for `fontinfo.plist`
 are available for external use. These are
 
-- validateFontInfoVersion2ValueForAttribute
+- :func:`.validateFontInfoVersion2ValueForAttribute`
-- validateFontInfoVersion3ValueForAttribute
+- :func:`.validateFontInfoVersion3ValueForAttribute`
 
 Value conversion functions are available for converting
-fontinfo.plist values between the possible format versions.
+`fontinfo.plist` values between the possible format versions.
 
-- convertFontInfoValueForAttributeFromVersion1ToVersion2
+- :func:`.convertFontInfoValueForAttributeFromVersion1ToVersion2`
-- convertFontInfoValueForAttributeFromVersion2ToVersion1
+- :func:`.convertFontInfoValueForAttributeFromVersion2ToVersion1`
-- convertFontInfoValueForAttributeFromVersion2ToVersion3
+- :func:`.convertFontInfoValueForAttributeFromVersion2ToVersion3`
-- convertFontInfoValueForAttributeFromVersion3ToVersion2
+- :func:`.convertFontInfoValueForAttributeFromVersion3ToVersion2`
 """
 
 import os
@@ -201,8 +201,12 @@ class _UFOBaseIO:
 
 
 class UFOReader(_UFOBaseIO):
-    """
+    """Read the various components of a .ufo.
-    Read the various components of the .ufo.
+
+    Attributes:
+        path: An `os.PathLike` object pointing to the .ufo.
+        validate: A boolean indicating if the data read should be
+          validated. Defaults to `True`.
 
     By default read data is validated. Set ``validate`` to
     ``False`` to not validate the data.
@@ -884,20 +888,27 @@ class UFOReader(_UFOBaseIO):
 
 
 class UFOWriter(UFOReader):
-    """
+    """Write the various components of a .ufo.
-    Write the various components of the .ufo.
+
+    Attributes:
+        path: An `os.PathLike` object pointing to the .ufo.
+        formatVersion: the UFO format version as a tuple of integers (major, minor),
+            or as a single integer for the major digit only (minor is implied to be 0).
+            By default, the latest formatVersion will be used; currently it is 3.0,
+            which is equivalent to formatVersion=(3, 0).
+        fileCreator: The creator of the .ufo file. Defaults to
+            `com.github.fonttools.ufoLib`.
+        structure: The internal structure of the .ufo file: either `ZIP` or `PACKAGE`.
+        validate: A boolean indicating if the data read should be validated. Defaults
+            to `True`.
 
     By default, the written data will be validated before writing. Set ``validate`` to
     ``False`` if you do not want to validate the data. Validation can also be overriden
-    on a per method level if desired.
+    on a per-method level if desired.
 
-    The ``formatVersion`` argument allows to specify the UFO format version as a tuple
+    Raises:
-    of integers (major, minor), or as a single integer for the major digit only (minor
+        UnsupportedUFOFormat: An exception indicating that the requested UFO
-    is implied as 0). By default the latest formatVersion will be used; currently it's
+            formatVersion is not supported.
-    3.0, which is equivalent to formatVersion=(3, 0).
-
-    An UnsupportedUFOFormat exception is raised if the requested UFO formatVersion is
-    not supported.
     """
 
     def __init__(

Lib/fontTools/ufoLib/plistlib.py

@@ -1,5 +1,5 @@
 """DEPRECATED - This module is kept here only as a backward compatibility shim
-for the old ufoLib.plistlib module, which was moved to fontTools.misc.plistlib.
+for the old `ufoLib.plistlib` module, which was moved to :class:`fontTools.misc.plistlib`.
 Please use the latter instead.
 """
 

Lib/fontTools/ufoLib/pointPen.py

@@ -1,5 +1,5 @@
 """DEPRECATED - This module is kept here only as a backward compatibility shim
-for the old ufoLib.pointPen module, which was moved to fontTools.pens.pointPen.
+for the old `ufoLib.pointPen` module, which was moved to :class:`fontTools.pens.pointPen`.
 Please use the latter instead.
 """