From d80b8dbc89cb789b48a0933744521819172e8dac Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Mon, 16 Sep 2024 12:48:15 +0100 Subject: [PATCH 1/8] Docs, minor: add regularized title text to all modules. --- Doc/source/afmLib.rst | 6 +++--- Doc/source/cffLib/CFF2ToCFF.rst | 7 +++++++ Doc/source/cffLib/CFFToCFF2.rst | 7 +++++++ Doc/source/cffLib/index.rst | 19 ++++++++++++++----- Doc/source/config.rst | 2 +- Doc/source/cu2qu/index.rst | 6 +++--- Doc/source/designspaceLib/index.rst | 2 +- Doc/source/encodings/index.rst | 6 +++--- Doc/source/feaLib/index.rst | 6 +++--- Doc/source/pens/index.rst | 6 +++--- Doc/source/subset/index.rst | 6 +++--- Doc/source/svgLib/index.rst | 6 +++--- Doc/source/t1Lib.rst | 6 +++--- Doc/source/ttLib/index.rst | 6 +++--- Doc/source/ttx.rst | 6 +++--- Doc/source/varLib/index.rst | 7 +++---- Doc/source/voltLib/index.rst | 6 +++--- 17 files changed, 66 insertions(+), 44 deletions(-) create mode 100644 Doc/source/cffLib/CFF2ToCFF.rst create mode 100644 Doc/source/cffLib/CFFToCFF2.rst diff --git a/Doc/source/afmLib.rst b/Doc/source/afmLib.rst index ab9f35678..bea783d7a 100644 --- a/Doc/source/afmLib.rst +++ b/Doc/source/afmLib.rst @@ -1,6 +1,6 @@ -########################################### -afmLib: Read/write Adobe Font Metrics files -########################################### +############################################### +afmLib: Read and write Adobe Font Metrics files +############################################### .. automodule:: fontTools.afmLib diff --git a/Doc/source/cffLib/CFF2ToCFF.rst b/Doc/source/cffLib/CFF2ToCFF.rst new file mode 100644 index 000000000..04c8b1f28 --- /dev/null +++ b/Doc/source/cffLib/CFF2ToCFF.rst @@ -0,0 +1,7 @@ +############################## +CFF2ToCFF: convert CFF2 to CFF +############################## + +.. automodule:: fontTools.cffLib.CFF2ToCFF + :inherited-members: + :members: diff --git a/Doc/source/cffLib/CFFToCFF2.rst b/Doc/source/cffLib/CFFToCFF2.rst new file mode 100644 index 000000000..7ea2183d9 --- /dev/null +++ b/Doc/source/cffLib/CFFToCFF2.rst @@ -0,0 +1,7 @@ +############################## +CFFToCFF2: convert CFF to CFF2 +############################## + +.. automodule:: fontTools.cffLib.CFFToCFF2 + :inherited-members: + :members: diff --git a/Doc/source/cffLib/index.rst b/Doc/source/cffLib/index.rst index 4a40f92f4..df9d47ba6 100644 --- a/Doc/source/cffLib/index.rst +++ b/Doc/source/cffLib/index.rst @@ -1,13 +1,22 @@ -################################## -cffLib: read/write Adobe CFF fonts -################################## +###################################### +cffLib: Read and write Adobe CFF fonts +###################################### -.. automodule:: fontTools.cffLib +This package contains modules for converting between CCF and CFF2: -This package also contains two modules for manipulating CFF format glyphs: +.. toctree:: + :maxdepth: 1 + + CFFToCFF2 + CFF2ToCFF + +and modules for manipulating CFF format glyphs: .. toctree:: :maxdepth: 1 specializer width + +.. automodule:: fontTools.cffLib + diff --git a/Doc/source/config.rst b/Doc/source/config.rst index 6be575d5e..40d1a6ae6 100644 --- a/Doc/source/config.rst +++ b/Doc/source/config.rst @@ -1,5 +1,5 @@ ########################### -config: configure fontTools +config: Configure fontTools ########################### .. automodule:: fontTools.config diff --git a/Doc/source/cu2qu/index.rst b/Doc/source/cu2qu/index.rst index 41730e54b..1affa21a7 100644 --- a/Doc/source/cu2qu/index.rst +++ b/Doc/source/cu2qu/index.rst @@ -1,6 +1,6 @@ -########################################## -cu2qu: Cubic to quadratic curve conversion -########################################## +######################################## +cu2qu: Convert cubic curves to quadratic +######################################## Routines for converting cubic curves to quadratic splines, suitable for use in OpenType to TrueType outline conversion. diff --git a/Doc/source/designspaceLib/index.rst b/Doc/source/designspaceLib/index.rst index 6bf297542..13b77b640 100644 --- a/Doc/source/designspaceLib/index.rst +++ b/Doc/source/designspaceLib/index.rst @@ -4,7 +4,7 @@ designspaceLib: Read, write, and edit designspace files Implements support for reading and manipulating ``designspace`` files. Allows the users to define axes, rules, sources, variable fonts and instances, -and their STAT information. +and their ``STAT`` information. .. toctree:: :maxdepth: 1 diff --git a/Doc/source/encodings/index.rst b/Doc/source/encodings/index.rst index 32d13c70e..f35e3806e 100644 --- a/Doc/source/encodings/index.rst +++ b/Doc/source/encodings/index.rst @@ -1,6 +1,6 @@ -################################################## -encodings: Support for OpenType-specific encodings -################################################## +############################################################ +encodings: Support for OpenType-specific character encodings +############################################################ fontTools includes support for some character encodings found in legacy Mac TrueType fonts. Many of these legacy encodings have found their way into the diff --git a/Doc/source/feaLib/index.rst b/Doc/source/feaLib/index.rst index 61ac31f3b..c25532caa 100644 --- a/Doc/source/feaLib/index.rst +++ b/Doc/source/feaLib/index.rst @@ -1,6 +1,6 @@ -######################################### -feaLib: Read/write OpenType feature files -######################################### +############################################# +feaLib: Read and write OpenType feature files +############################################# fontTools' ``feaLib`` allows for the creation and parsing of Adobe Font Development Kit for OpenType feature (``.fea``) files. The syntax diff --git a/Doc/source/pens/index.rst b/Doc/source/pens/index.rst index 0f76b7238..1ecbcd1c2 100644 --- a/Doc/source/pens/index.rst +++ b/Doc/source/pens/index.rst @@ -1,6 +1,6 @@ -#### -pens -#### +########################################### +pens: Inspect and manipulate glyph outlines +########################################### .. toctree:: :maxdepth: 1 diff --git a/Doc/source/subset/index.rst b/Doc/source/subset/index.rst index f32e0d42c..1bc255b0f 100644 --- a/Doc/source/subset/index.rst +++ b/Doc/source/subset/index.rst @@ -1,6 +1,6 @@ -###### -subset -###### +######################################################## +subset: Generate subsets of fonts or optimize file sizes +######################################################## .. toctree:: :maxdepth: 1 diff --git a/Doc/source/svgLib/index.rst b/Doc/source/svgLib/index.rst index f86ff0ad4..6f1715b1d 100644 --- a/Doc/source/svgLib/index.rst +++ b/Doc/source/svgLib/index.rst @@ -1,6 +1,6 @@ -###### -svgLib -###### +############################################ +svgLib: Read and write SVG-in-OpenType fonts +############################################ .. toctree:: :maxdepth: 1 diff --git a/Doc/source/t1Lib.rst b/Doc/source/t1Lib.rst index 4436086fd..2a8c3fc3b 100644 --- a/Doc/source/t1Lib.rst +++ b/Doc/source/t1Lib.rst @@ -1,6 +1,6 @@ -##### -t1Lib -##### +############################################# +t1Lib: Read and write PostScript Type 1 fonts +############################################# .. automodule:: fontTools.t1Lib :inherited-members: diff --git a/Doc/source/ttLib/index.rst b/Doc/source/ttLib/index.rst index 7798238da..656148e5d 100644 --- a/Doc/source/ttLib/index.rst +++ b/Doc/source/ttLib/index.rst @@ -1,6 +1,6 @@ -############################################# -ttLib: Read/write OpenType and TrueType fonts -############################################# +################################################# +ttLib: Read and write OpenType and TrueType fonts +################################################# Most users of the fontTools library will be using it to generate or manipulate OpenType and TrueType fonts. (FontTools initially only supported TrueType fonts, diff --git a/Doc/source/ttx.rst b/Doc/source/ttx.rst index 9d30683b5..c05c8df05 100644 --- a/Doc/source/ttx.rst +++ b/Doc/source/ttx.rst @@ -1,6 +1,6 @@ -### -ttx -### +################################## +ttx: Convert fonts to XML and back +################################## TTX – From OpenType and TrueType to XML and Back diff --git a/Doc/source/varLib/index.rst b/Doc/source/varLib/index.rst index 1ae4a1b5e..32f428eb5 100644 --- a/Doc/source/varLib/index.rst +++ b/Doc/source/varLib/index.rst @@ -1,7 +1,6 @@ -################################## -varLib: OpenType Variation Support -################################## - +####################################### +varLib: Support for OpenType Variations +####################################### .. toctree:: :maxdepth: 2 diff --git a/Doc/source/voltLib/index.rst b/Doc/source/voltLib/index.rst index 00d067a29..a0ced85de 100644 --- a/Doc/source/voltLib/index.rst +++ b/Doc/source/voltLib/index.rst @@ -1,6 +1,6 @@ -#################################### -voltLib: Read/write MS VOLT projects -#################################### +######################################## +voltLib: Read and write MS VOLT projects +######################################## .. toctree:: :maxdepth: 2 From e1b51fb7c47234d454f1ecd686d6b4763430f271 Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Mon, 16 Sep 2024 12:49:12 +0100 Subject: [PATCH 2/8] Docs: set default highlight language to Python. --- Doc/source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/source/conf.py b/Doc/source/conf.py index 4976bd813..45603fb41 100644 --- a/Doc/source/conf.py +++ b/Doc/source/conf.py @@ -89,6 +89,9 @@ language = "en" # This patterns also effect to html_static_path and html_extra_path exclude_patterns = [] +# The programming language to be used by default in syntax highlighting. +highlight_language = "python" + # The name of the Pygments (syntax highlighting) style to use. # pygments_style = "sphinx" (the default sphinx docs style on RTD) pygments_style = "default" From c6c9ea405e266758b4e4036ed225d08c6e76be10 Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Mon, 16 Sep 2024 12:59:30 +0100 Subject: [PATCH 3/8] Docs: use by-source order for autodoc consistently. --- Doc/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/source/conf.py b/Doc/source/conf.py index 45603fb41..0f56c6e1e 100644 --- a/Doc/source/conf.py +++ b/Doc/source/conf.py @@ -44,6 +44,7 @@ autodoc_default_options = { "members": True, "inherited-members": True, "show-inheritance": True, + "member-order": "bysource", } # Add any paths that contain templates here, relative to this directory. From 3cafab8d50104aad105067b0138ce63e6bc8ec52 Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Tue, 17 Sep 2024 17:11:39 +0100 Subject: [PATCH 4/8] 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. """ From 69cecfaa1044ec424fc89c8b807f0140be50bf56 Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Tue, 17 Sep 2024 17:23:44 +0100 Subject: [PATCH 5/8] Docs: cffLib, minor updates. --- Doc/source/cffLib/CFF2ToCFF.rst | 3 +++ Doc/source/cffLib/CFFToCFF2.rst | 1 + Doc/source/cffLib/index.rst | 44 +++++++++++++++++++++---------- Doc/source/cffLib/specializer.rst | 8 ++++++ Lib/fontTools/cffLib/__init__.py | 4 +-- 5 files changed, 44 insertions(+), 16 deletions(-) diff --git a/Doc/source/cffLib/CFF2ToCFF.rst b/Doc/source/cffLib/CFF2ToCFF.rst index 04c8b1f28..28719cafe 100644 --- a/Doc/source/cffLib/CFF2ToCFF.rst +++ b/Doc/source/cffLib/CFF2ToCFF.rst @@ -5,3 +5,6 @@ CFF2ToCFF: convert CFF2 to CFF .. automodule:: fontTools.cffLib.CFF2ToCFF :inherited-members: :members: + :undoc-members: + + diff --git a/Doc/source/cffLib/CFFToCFF2.rst b/Doc/source/cffLib/CFFToCFF2.rst index 7ea2183d9..3fb0f20b3 100644 --- a/Doc/source/cffLib/CFFToCFF2.rst +++ b/Doc/source/cffLib/CFFToCFF2.rst @@ -5,3 +5,4 @@ CFFToCFF2: convert CFF to CFF2 .. automodule:: fontTools.cffLib.CFFToCFF2 :inherited-members: :members: + :undoc-members: diff --git a/Doc/source/cffLib/index.rst b/Doc/source/cffLib/index.rst index df9d47ba6..c4c39c1e7 100644 --- a/Doc/source/cffLib/index.rst +++ b/Doc/source/cffLib/index.rst @@ -2,21 +2,37 @@ cffLib: Read and write Adobe CFF fonts ###################################### -This package contains modules for converting between CCF and CFF2: +.. rubric:: Overview: + :heading-level: 3 -.. toctree:: - :maxdepth: 1 - - CFFToCFF2 - CFF2ToCFF - -and modules for manipulating CFF format glyphs: - -.. toctree:: - :maxdepth: 1 - - specializer - width .. automodule:: fontTools.cffLib + :inherited-members: + :members: + :undoc-members: + :member-order: bysource + .. rubric:: Submodules: + :heading-level: 3 + + cffLib contains submodules for converting between CCF and CFF2. + Each can be used within other Python code or run as a + command-line console script: + + .. toctree:: + :maxdepth: 1 + + CFFToCFF2 + CFF2ToCFF + + It also contains submodules for manipulating CFF-formatted glyphs: + + .. toctree:: + :maxdepth: 1 + + specializer + width + + .. rubric:: Module members: + :heading-level: 3 + diff --git a/Doc/source/cffLib/specializer.rst b/Doc/source/cffLib/specializer.rst index 016a89621..b14f56ca3 100644 --- a/Doc/source/cffLib/specializer.rst +++ b/Doc/source/cffLib/specializer.rst @@ -2,7 +2,15 @@ specializer: T2CharString operator specializer and generalizer ############################################################## +.. rubric:: Overview: + :heading-level: 3 + .. automodule:: fontTools.cffLib.specializer :inherited-members: :members: :undoc-members: + + + .. rubric:: Module members: + :heading-level: 3 + diff --git a/Lib/fontTools/cffLib/__init__.py b/Lib/fontTools/cffLib/__init__.py index c192ec77a..2f47d9006 100644 --- a/Lib/fontTools/cffLib/__init__.py +++ b/Lib/fontTools/cffLib/__init__.py @@ -1,7 +1,7 @@ """cffLib: read/write Adobe CFF fonts -OpenType fonts with PostScript outlines contain a completely independent -font file, Adobe's *Compact Font Format*. So dealing with OpenType fonts +OpenType fonts with PostScript outlines embed a completely independent +font file in Adobe's *Compact Font Format*. So dealing with OpenType fonts requires also dealing with CFF. This module allows you to read and write fonts written in the CFF format. From 909da9680bd6132a7853c382913f494526b95f8e Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Tue, 17 Sep 2024 17:24:45 +0100 Subject: [PATCH 6/8] docs: pens - add preliminary intro section. --- Doc/source/pens/index.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/Doc/source/pens/index.rst b/Doc/source/pens/index.rst index 1ecbcd1c2..0caa286b6 100644 --- a/Doc/source/pens/index.rst +++ b/Doc/source/pens/index.rst @@ -2,6 +2,26 @@ pens: Inspect and manipulate glyph outlines ########################################### +.. rubric:: Overview: + :heading-level: 3 + +The fontTools **pens** are a collection of classes that can operate +on a font glyph via the points and the contours of the glyph's outlines. + +Some pens trace through the outlines and generate graphical output, +such as a new glyph outline or a formatted image, but other +pens analyze the outlines and return information about the glyph. + +Pens that alter or produce a pen-compatile ``ttGlyph`` object can +be chained together. + +New pens can be written by subclassing the ``AbstractPen`` or, +somewhat more practically, ``BasePen`` classes. The Pen Protocol is +documented on the ``BasePen`` page. + +.. rubric:: Pens: + :heading-level: 3 + .. toctree:: :maxdepth: 1 From 499101df905298096b94e2601f4a7082fd3d8512 Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Tue, 17 Sep 2024 17:36:33 +0100 Subject: [PATCH 7/8] Docs: pens; formatting. --- Doc/source/pens/index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/source/pens/index.rst b/Doc/source/pens/index.rst index 0caa286b6..e26d6d5b2 100644 --- a/Doc/source/pens/index.rst +++ b/Doc/source/pens/index.rst @@ -12,14 +12,14 @@ Some pens trace through the outlines and generate graphical output, such as a new glyph outline or a formatted image, but other pens analyze the outlines and return information about the glyph. -Pens that alter or produce a pen-compatile ``ttGlyph`` object can +Pens that alter or produce a pen-compatible :class:`.ttGlyph` object can be chained together. -New pens can be written by subclassing the ``AbstractPen`` or, -somewhat more practically, ``BasePen`` classes. The Pen Protocol is -documented on the ``BasePen`` page. +New pens can be written by sub-classing the :class:`.AbstractPen` or, +somewhat more practically, :class:`.BasePen` classes. The Pen Protocol is +documented on the :ref:`basePen` page. -.. rubric:: Pens: +.. rubric:: Pen modules: :heading-level: 3 .. toctree:: From 1014b2ff3bf69e772f2aa185e27ba8bdafd5e5f2 Mon Sep 17 00:00:00 2001 From: Nathan Williis Date: Wed, 18 Sep 2024 14:49:50 +0100 Subject: [PATCH 8/8] Docs: reword cfflib text --- Doc/source/cffLib/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/source/cffLib/index.rst b/Doc/source/cffLib/index.rst index c4c39c1e7..19761cdff 100644 --- a/Doc/source/cffLib/index.rst +++ b/Doc/source/cffLib/index.rst @@ -16,8 +16,8 @@ cffLib: Read and write Adobe CFF fonts :heading-level: 3 cffLib contains submodules for converting between CCF and CFF2. - Each can be used within other Python code or run as a - command-line console script: + Each can be used within other Python scripts or run as a + subcommand of the ``fonttools`` command-line tool: .. toctree:: :maxdepth: 1