• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# fontTools Documentation
2
3The fontTools project documentation updates continuously on Read the Docs as the project source changes.
4
5The documentation is hosted at https://fonttools.readthedocs.io/.
6
7## Contents
8
9- [How to Build Local Documentation](#how-to-build-local-documentation)
10- [Contributing to the fontTools Documentation](#contributing-to-the-documentation)
11- [Documentation License](#documentation-license)
12
13## How to Build Local Documentation
14
15### Install Dependencies
16
17You must have a Python 3 interpreter and the `pip` Python package manager installed on your system to build the fontTools documentation.
18
19Pull 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:
20
21```
22$ pip install -e . [all]
23$ pip install -r Doc/docs-requirements.txt
24```
25
26### Build Documentation
27
28**With `make`**: execute the following command in the root of the repository:
29
30```
31$ make docs
32```
33
34**Without `make`**: execute the following command in the **`Doc` directory**:
35
36```
37$ sphinx-build -b html source build
38```
39
40Open the `Doc/build/html/index.html` file in your browser to view the documentation home page.
41
42## Contributing to the Documentation
43
44We highly encourage contributions!  Please follow the instructions below to improve the documentation.
45
46### Python Docstring Style
47
48We recommend the use of Python docstrings that follow [the Google Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#381-docstrings).  Our documentation build approach parses appropriately formatted docstrings into formatted documentation files.
49
50#### Function Documentation Example
51
52```python
53def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
54    """Fetches rows from a Bigtable.
55
56    Retrieves rows pertaining to the given keys from the Table instance
57    represented by big_table.  Silly things may happen if
58    other_silly_variable is not None.
59
60    Args:
61        big_table: An open Bigtable Table instance.
62        keys: A sequence of strings representing the key of each table row
63            to fetch.
64        other_silly_variable: Another optional variable, that has a much
65            longer name than the other args, and which does nothing.
66
67    Returns:
68        A dict mapping keys to the corresponding table row data
69        fetched. Each row is represented as a tuple of strings. For
70        example:
71
72        {'Serak': ('Rigel VII', 'Preparer'),
73         'Zim': ('Irk', 'Invader'),
74         'Lrrr': ('Omicron Persei 8', 'Emperor')}
75
76        If a key from the keys argument is missing from the dictionary,
77        then that row was not found in the table.
78
79    Raises:
80        IOError: An error occurred accessing the bigtable.Table object.
81    """
82```
83*Source: [Google Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md) (CC BY-SA 3.0)*
84
85#### Class Documentation Example
86
87```python
88class SampleClass(object):
89    """Summary of class here.
90
91    Longer class information....
92    Longer class information....
93
94    Attributes:
95        likes_spam: A boolean indicating if we like SPAM or not.
96        eggs: An integer count of the eggs we have laid.
97    """
98
99    def __init__(self, likes_spam=False):
100        """Inits SampleClass with blah."""
101        self.likes_spam = likes_spam
102        self.eggs = 0
103
104    def public_method(self):
105        """Performs operation blah."""
106```
107*Source: [Google Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md) (CC BY-SA 3.0)*
108
109### Build Local Documentation and Review Your Changes
110
111Build a local set of HTML documentation files with the instructions above and review your changes.
112
113### Submit a Pull Request
114
115Submit a Github pull request with your proposed improvements to the documentation.
116
117Thanks for your contribution!
118
119## Documentation License
120
121The fontTools documentation is released under a [CC BY-SA 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/).
122