From 3cafab8d50104aad105067b0138ce63e6bc8ec52 Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Tue, 17 Sep 2024 17:11:39 +0100 Subject: [PATCH] Docs: reconfigure ufoLib documentation. --- Doc/source/ufoLib/converters.rst | 7 ++-- Doc/source/ufoLib/errors.rst | 7 ++-- Doc/source/ufoLib/filenames.rst | 7 ++-- Doc/source/ufoLib/glifLib.rst | 7 ++-- Doc/source/ufoLib/index.rst | 57 +++++++++++++++++-------- Doc/source/ufoLib/kerning.rst | 7 ++-- Doc/source/ufoLib/plistlib.rst | 17 ++++---- Doc/source/ufoLib/pointpen.rst | 17 ++++---- Doc/source/ufoLib/utils.rst | 7 ++-- Doc/source/ufoLib/validators.rst | 7 ++-- Lib/fontTools/ufoLib/__init__.py | 71 ++++++++++++++++++-------------- Lib/fontTools/ufoLib/plistlib.py | 2 +- Lib/fontTools/ufoLib/pointPen.py | 2 +- 13 files changed, 122 insertions(+), 93 deletions(-) diff --git a/Doc/source/ufoLib/converters.rst b/Doc/source/ufoLib/converters.rst index 2b37e56ac..0202d4335 100644 --- a/Doc/source/ufoLib/converters.rst +++ b/Doc/source/ufoLib/converters.rst @@ -1,7 +1,6 @@ - -########## -converters -########## +####################################################### +converters: Conversion functions for kerning and groups +####################################################### .. automodule:: fontTools.ufoLib.converters :inherited-members: diff --git a/Doc/source/ufoLib/errors.rst b/Doc/source/ufoLib/errors.rst index ba079abd8..179e968ee 100644 --- a/Doc/source/ufoLib/errors.rst +++ b/Doc/source/ufoLib/errors.rst @@ -1,7 +1,6 @@ - -###### -errors -###### +################################################### +errors: Exceptions for handling UFO-specific errors +################################################### .. automodule:: fontTools.ufoLib.errors :inherited-members: diff --git a/Doc/source/ufoLib/filenames.rst b/Doc/source/ufoLib/filenames.rst index 33a3c1b78..d3eef0496 100644 --- a/Doc/source/ufoLib/filenames.rst +++ b/Doc/source/ufoLib/filenames.rst @@ -1,7 +1,6 @@ - -######### -filenames -######### +########################################################################## +filenames: Functions to convert between file names and user-facing strings +########################################################################## .. automodule:: fontTools.ufoLib.filenames :inherited-members: diff --git a/Doc/source/ufoLib/glifLib.rst b/Doc/source/ufoLib/glifLib.rst index 15bde5abe..9213260bc 100644 --- a/Doc/source/ufoLib/glifLib.rst +++ b/Doc/source/ufoLib/glifLib.rst @@ -1,7 +1,6 @@ - -####### -glifLib -####### +####################################### +glifLib: Read and write UFO .glif files +####################################### .. automodule:: fontTools.ufoLib.glifLib :inherited-members: diff --git a/Doc/source/ufoLib/index.rst b/Doc/source/ufoLib/index.rst index 514c5c9f7..a865fd2f6 100644 --- a/Doc/source/ufoLib/index.rst +++ b/Doc/source/ufoLib/index.rst @@ -1,22 +1,45 @@ +################################################ +ufoLib: Read and write Unified Font Object files +################################################ -###### -ufoLib -###### - -.. toctree:: - :maxdepth: 1 - - converters - errors - filenames - glifLib - kerning - plistlib - pointpen - utils - validators +.. rubric:: Overview: + :heading-level: 3 .. automodule:: fontTools.ufoLib :inherited-members: - :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 diff --git a/Doc/source/ufoLib/kerning.rst b/Doc/source/ufoLib/kerning.rst index 4d9d0c150..b8f1c38c5 100644 --- a/Doc/source/ufoLib/kerning.rst +++ b/Doc/source/ufoLib/kerning.rst @@ -1,7 +1,6 @@ - -####### -kerning -####### +########################################### +kerning: Support for accessing kerning data +########################################### .. automodule:: fontTools.ufoLib.kerning :inherited-members: diff --git a/Doc/source/ufoLib/plistlib.rst b/Doc/source/ufoLib/plistlib.rst index d639947c3..6ae1a0ce1 100644 --- a/Doc/source/ufoLib/plistlib.rst +++ b/Doc/source/ufoLib/plistlib.rst @@ -1,9 +1,10 @@ +##################################################################### +plistlib: Support for reading and writing .plist files *[deprecated]* +##################################################################### -######## -plistlib -######## - -.. automodule:: fontTools.ufoLib.plistlib - :inherited-members: - :members: - :undoc-members: +.. important:: + + .. automodule:: fontTools.ufoLib.plistlib + :inherited-members: + :members: + :undoc-members: diff --git a/Doc/source/ufoLib/pointpen.rst b/Doc/source/ufoLib/pointpen.rst index 5fb8c1cad..d71a72726 100644 --- a/Doc/source/ufoLib/pointpen.rst +++ b/Doc/source/ufoLib/pointpen.rst @@ -1,9 +1,10 @@ +###################################################################### +pointPen: A pen for accessing points in a glyph contour *[deprecated]* +###################################################################### -######## -pointPen -######## - -.. automodule:: fontTools.ufoLib.pointPen - :inherited-members: - :members: - :undoc-members: +.. important:: + + .. automodule:: fontTools.ufoLib.pointPen + :inherited-members: + :members: + :undoc-members: diff --git a/Doc/source/ufoLib/utils.rst b/Doc/source/ufoLib/utils.rst index d5ab143ec..bef782815 100644 --- a/Doc/source/ufoLib/utils.rst +++ b/Doc/source/ufoLib/utils.rst @@ -1,7 +1,6 @@ - -##### -utils -##### +##################################### +utils: Miscellaneous helper functions +##################################### .. automodule:: fontTools.ufoLib.utils :inherited-members: diff --git a/Doc/source/ufoLib/validators.rst b/Doc/source/ufoLib/validators.rst index 363d8648a..c512e873f 100644 --- a/Doc/source/ufoLib/validators.rst +++ b/Doc/source/ufoLib/validators.rst @@ -1,7 +1,6 @@ - -########## -validators -########## +##################################### +validators: Data-validation functions +##################################### .. automodule:: fontTools.ufoLib.validators :inherited-members: diff --git a/Lib/fontTools/ufoLib/__init__.py b/Lib/fontTools/ufoLib/__init__.py index aa57beede..42c06734e 100755 --- a/Lib/fontTools/ufoLib/__init__.py +++ b/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 -of the specification. +The main interfaces are the :class:`.UFOReader` and :class:`.UFOWriter` +classes, which support versions 1, 2, and 3 of the UFO specification. -Sets that list the font info attribute names for the fontinfo.plist -formats are available for external use. These are: +Set variables are available for external use that list the font +info attribute names for the `fontinfo.plist` formats. These are: -- fontInfoAttributesVersion1 -- fontInfoAttributesVersion2 -- fontInfoAttributesVersion3 +- :obj:`.fontInfoAttributesVersion1` +- :obj:`.fontInfoAttributesVersion2` +- :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 -- validateFontInfoVersion3ValueForAttribute +- :func:`.validateFontInfoVersion2ValueForAttribute` +- :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 -- convertFontInfoValueForAttributeFromVersion2ToVersion1 -- convertFontInfoValueForAttributeFromVersion2ToVersion3 -- convertFontInfoValueForAttributeFromVersion3ToVersion2 +- :func:`.convertFontInfoValueForAttributeFromVersion1ToVersion2` +- :func:`.convertFontInfoValueForAttributeFromVersion2ToVersion1` +- :func:`.convertFontInfoValueForAttributeFromVersion2ToVersion3` +- :func:`.convertFontInfoValueForAttributeFromVersion3ToVersion2` """ import os @@ -201,8 +201,12 @@ class _UFOBaseIO: class UFOReader(_UFOBaseIO): - """ - Read the various components of the .ufo. + """Read the various components of a .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 the .ufo. + """Write the various components of a .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 - of integers (major, minor), or as a single integer for the major digit only (minor - is implied as 0). By default the latest formatVersion will be used; currently it's - 3.0, which is equivalent to formatVersion=(3, 0). - - An UnsupportedUFOFormat exception is raised if the requested UFO formatVersion is - not supported. + Raises: + UnsupportedUFOFormat: An exception indicating that the requested UFO + formatVersion is not supported. """ def __init__( diff --git a/Lib/fontTools/ufoLib/plistlib.py b/Lib/fontTools/ufoLib/plistlib.py index 38bb266b2..0242e9d26 100644 --- a/Lib/fontTools/ufoLib/plistlib.py +++ b/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. """ diff --git a/Lib/fontTools/ufoLib/pointPen.py b/Lib/fontTools/ufoLib/pointPen.py index baef9a583..4a8126cd6 100644 --- a/Lib/fontTools/ufoLib/pointPen.py +++ b/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. """