aosp12/external/fonttools/Doc

fontTools Documentation

The fontTools project documentation updates continuously on Read the Docs as the project source changes.

The documentation is hosted at https://fonttools.readthedocs.io/.

Contents

• How to Build Local Documentation
• Contributing to the fontTools Documentation
• Documentation License

How to Build Local Documentation

Install Dependencies

You must have a Python 3 interpreter and the pip Python package manager installed on your system to build the fontTools documentation.

Pull the fontTools project source files, create a Python virtual environment, and then install fontTools and the documentation build dependencies by executing the following commands in the root of the fontTools source repository:

$ pip install -e . [all]
$ pip install -r Doc/docs-requirements.txt

Build Documentation

With make: execute the following command in the root of the repository:

$ make docs

Without make: execute the following command in the Doc directory:

$ sphinx-build -b html source build

Open the Doc/build/html/index.html file in your browser to view the documentation home page.

Contributing to the Documentation

We highly encourage contributions! Please follow the instructions below to improve the documentation.

Python Docstring Style

We recommend the use of Python docstrings that follow the Google Style Guide. Our documentation build approach parses appropriately formatted docstrings into formatted documentation files.

Function Documentation Example

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

Source: Google Style Guide (CC BY-SA 3.0)

Class Documentation Example

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

Source: Google Style Guide (CC BY-SA 3.0)

Build Local Documentation and Review Your Changes

Build a local set of HTML documentation files with the instructions above and review your changes.

Submit a Pull Request

Submit a Github pull request with your proposed improvements to the documentation.

Thanks for your contribution!

Documentation License

The fontTools documentation is released under a CC BY-SA 4.0 International License.