Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

small fix to fontTools Documentation heading #3490

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

small fix to fontTools Documentation heading #3490

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7e2ca81
Improve structure and content of fontTools documentation
rrawatt Apr 26, 2024
3d1807a
Improve structure and content of fontTools documentation
rrawatt Apr 26, 2024
8542cc6
Merge branch 'fonttools:main' into main
rrawatt Apr 27, 2024
18c4dbb
fix to fonTools Documentation heading
rrawatt Apr 27, 2024
aa9eca5
made optional.rst easier to read
rrawatt Apr 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Doc/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
:align: center


---fontTools Documentation---
fontTools Documentation
=======
About
-----
Expand Down
128 changes: 49 additions & 79 deletions Doc/source/optional.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,142 +1,112 @@
:orphan:

Optional Dependencies
=====================

The fonttools PyPI distribution also supports so-called "extras", i.e. a
set of keywords that describe a group of additional dependencies, which can be
used when installing via pip, or when specifying a requirement.
For example:
The FontTools PyPI distribution supports "extras", which are groups of additional dependencies that can be installed alongside FontTools via pip to enable specific features. For example:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know that there is already a lack of total consistency in the docs regarding the capitalization of "FontTools" when it is used as the name of the project (versus, for example, referring to the modules). I see that this PR uses "FontTools" here, but uses "fontTools" in index.rst. Might as well be consistent within the PR, IMO.

Personally, I think starting with the capital F is the way to go, both because it more clearly differentiates between "project name" and "token" use cases, but also because of the project logo....

If there are other strong opinions, though, I'm happy to hear what they all are.

.. code:: sh

pip install fonttools[ufo,lxml,woff,unicode]

This command will install fonttools, as well as the optional dependencies that
are required to unlock the extra features named "ufo", etc.

.. note::

Optional dependencies are detailed by module in the list below with the ``Extra`` setting that automates ``pip`` dependency installation when this is supported.
This command installs FontTools along with the optional dependencies required for features like "ufo", "lxml", "woff", and "unicode".

.. note:: sh

Optional dependencies are listed by module below, along with the `Extra` setting that automates `pip` dependency installation when supported.

:py:mod:`fontTools.misc.etree`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
--------------------

The module exports a ElementTree-like API for reading/writing XML files, and allows to use as the backend either the built-in ``xml.etree`` module or `lxml <https://lxml.de>`__. The latter is preferred whenever present, as it is generally faster and more secure.
This module provides an ElementTree-like API for reading and writing XML files. It supports two backend options:

*Extra:* ``lxml``
- Built-in `xml.etree` module
- `lxml` preferred for improved speed and security.

*Extra:* `lxml`

:py:mod:`fontTools.ufoLib`
^^^^^^^^^^^^^^^^^^^^^^^^^^

Package for reading and writing UFO source files; it requires:
----------------

* `fs <https://pypi.org/pypi/fs>`__: (aka ``pyfilesystem2``) filesystem abstraction layer.
Package for reading and writing UFO source files. Dependencies include:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My preference would be to spell out "Unified Font Object (UFO)" here, on first usage at this entry point. It's clear if the reader already knows what UFO is, but you are always going to get people who are diving in without a lot of prior background reading, because they've got some ultra-specific problem they're trying to fix.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I should maybe add that I don't think it's necessary to always spell out UFO and other abbreviations, but this is intro material, dealing with step-one installation stuff, so I think the need is higher here....

* `enum34 <https://pypi.org/pypi/enum34>`__: backport for the built-in ``enum`` module (only required on Python < 3.4).

*Extra:* ``ufo``
- `fs <https://pypi.org/pypi/fs>`__: (aka ``pyfilesystem2``) filesystem abstraction layer
- `enum34 <https://pypi.org/pypi/enum34>`__ backport for the built-in ``enum`` module (module for Python versions < 3.4)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd cut out the second "module" there.

*Extra:* `ufo`

:py:mod:`fontTools.ttLib.woff2`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Module to compress/decompress WOFF 2.0 web fonts; it requires:
---------------------

* `brotli <https://pypi.python.org/pypi/Brotli>`__: Python bindings of the Brotli compression library.
Module for compressing and decompressing WOFF 2.0 web fonts. Requires:

*Extra:* ``woff``
- `brotli <https://pypi.python.org/pypi/Brotli>`__: Python bindings for the Brotli compression library.

*Extra:* `woff`

:py:mod:`fontTools.unicode`
^^^^^^^^^^^^^^^^^^^^^^^^^^^
-----------------

To display the Unicode character names when dumping the ``cmap`` table
with ``ttx`` we use the ``unicodedata`` module in the Standard Library.
Displays Unicode character names when working with the `cmap` table dumps,with `ttx` we use the `unicodedata` module in the Standard Library.
The version included in there varies between different Python versions.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a space missing between "," and "with". I would also prefer to move towards "FontTools uses the unicodedata [...] over "we use [...]" but that might be a bigger discussion. Certainly it's not wrong to say "FontTools" instead of "we" though. Also, I would drop the "the" before cmap; pretty minor though.

To use the latest available data, you can install:

* `unicodedata2 <https://pypi.python.org/pypi/unicodedata2>`__: ``unicodedata`` backport for Python
3.x updated to the latest Unicode version 14.0. Note this is not necessary if you use Python 3.11
as the latter already comes with an up-to-date ``unicodedata``.
To use the latest Unicode version, install:

*Extra:* ``unicode``
- `unicodedata2 <https://pypi.python.org/pypi/unicodedata2>`__: backport of `unicodedata` for Python 3.x, updated to unicode 14.0. Not necessary with Python 3.11.

*Extra:* `unicode`

:py:mod:`fontTools.varLib.interpolatable`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-------------------------------

Module for finding wrong contour/component order between different masters.
It requires one of the following packages in order to solve the so-called
"minimum weight perfect matching problem in bipartite graphs", or
the Assignment problem:
Module for resolving contour or component order between different masters. Requires following packages to solve 'minimum weight perfect matching problem in bipartite graphs':

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs a "the" before "following packages" ... or "one of the"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that, if the Assignment Problem is well-defined enough to have a name, then it'd be ideal to drop a link about it where the name is mentioned. Wikipedia maybe?

* `scipy <https://pypi.python.org/pypi/scipy>`__: the Scientific Library for Python, which internally
uses `NumPy <https://pypi.python.org/pypi/numpy>`__ arrays and hence is very fast;
* `munkres <https://pypi.python.org/pypi/munkres>`__: a pure-Python module that implements the Hungarian
or Kuhn-Munkres algorithm.

*Extra:* ``interpolatable``
- `scipy <https://pypi.python.org/pypi/scipy>`__: Scientific Library for Python, uses `NumPy <https://pypi.python.org/pypi/numpy>`__ arrays for performance;
- `munkres <https://pypi.python.org/pypi/munkres>`__: implementation of the Hungarian or Kuhn-Munkres algorithm.

*Extra:* `interpolatable`

:py:mod:`fontTools.varLib.plot`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Module for visualizing DesignSpaceDocument and resulting VariationModel.
----------------------

* `matplotlib <https://pypi.org/pypi/matplotlib>`__: 2D plotting library.
Module for visualizing DesignSpaceDocument and resulting VariationModel. Requires:

*Extra:* ``plot``
- `matplotlib <https://pypi.org/pypi/matplotlib>`__: 2D plotting library.

*Extra:* `plot`

:py:mod:`fontTools.misc.symfont`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Advanced module for symbolic font statistics analysis; it requires:
----------------------

* `sympy <https://pypi.python.org/pypi/sympy>`__: the Python library for symbolic mathematics.
Advanced module for symbolic font statistics analysis. Requires:

*Extra:* ``symfont``
- `sympy <https://pypi.python.org/pypi/sympy>`__: Python library for symbolic mathematics.

*Extra:* `symfont`

:py:mod:`fontTools.t1Lib`
^^^^^^^^^^^^^^^^^^^^^^^^^
---------------

To get the file creator and type of Macintosh PostScript Type 1 fonts
on Python 3 you need to install the following module, as the old ``MacOS``
module is no longer included in Mac Python:
Retrieves information about Macintosh PostScript Type 1 fonts on Python 3. Requires:

* `xattr <https://pypi.python.org/pypi/xattr>`__: Python wrapper for extended filesystem attributes
(macOS platform only).

*Extra:* ``type1``
- `xattr <https://pypi.python.org/pypi/xattr>`__: Python wrapper for extended filesystem attributes, macOS only.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feel free to disagree here, but I always worry about ambiguity when saying "macOS only" or the like unless it's totally spelled out. As in, are we saying that the module can only be installed on macOS? Or just that the xattrs are only found on macOS (different question how you'd be accessing those filesystems on another platform, though).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(same "only"ness question on the CocoaPen bit below, I suppose, although I think mounting HFS/HFS+ disks is still possible on Linux, so the xattrs stuff might be usable there. I'd certainly be happy to learn for sure)

*Extra:* `type1`

:py:mod:`fontTools.pens.cocoaPen`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Pen for drawing glyphs with Cocoa ``NSBezierPath``, requires:
------------------------

* `PyObjC <https://pypi.python.org/pypi/pyobjc>`__: the bridge between Python and the Objective-C
runtime (macOS platform only).
Pen for drawing glyphs with Cocoa `NSBezierPath`. Requires:

- `PyObjC <https://pypi.python.org/pypi/pyobjc>`__: Python - Objective-C bridge, macOS only.

:py:mod:`fontTools.pens.qtPen`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Pen for drawing glyphs with Qt's ``QPainterPath``, requires:
---------------------

* `PyQt5 <https://pypi.python.org/pypi/PyQt5>`__: Python bindings for the Qt cross platform UI and
application toolkit.
Pen for drawing glyphs with Qt's `QPainterPath`. Requires:

- `PyQt5 <https://pypi.python.org/pypi/PyQt5>`__: Python bindings for the Qt cross-platform UI and application toolkit.

:py:mod:`fontTools.pens.reportLabPen`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
---------------------------

Pen to drawing glyphs as PNG images, requires:
Pen for drawing glyphs as PNG images. Requires:

* `reportlab <https://pypi.python.org/pypi/reportlab>`__: Python toolkit for generating PDFs and
graphics.
- `<https://pypi.python.org/pypi/reportlab>`__: Python toolkit for generating PDFs and graphics.
Loading