Documentation Contributor Guide
Contributions to the Font Bakery documentation are welcomed! Please read and follow the instructions below to improve our documentation.
Please note that the required dependencies are different for documentation development and source code development. Please see the Source Code Contributor Guide if you are attempting to modify the Python source code!
Create a Font Bakery Development Environment
You must have a Python 3 interpreter and the
pip Python package
manager installed on your system to participate in Font Bakery
Clone the Font Bakery Source Repository
Pull the source repository with the following command:
$ git clone https://github.com/googlefonts/fontbakery.git
and navigate to the root of the repository with:
$ cd fontbakery
Create a Python Virtual Environment
Execute the following command in the root of the Font Bakery source repository to create a Python virtual environment for development and testing:
$ python3 -m venv fontbakery-venv
Activate Virtual Environment and Install Font Bakery
Activate the Python virtual environment with:
$ source fontbakery-venv/bin/activate
Next, install the Font Bakery source in editable mode with:
$ pip install -e ".[docs]"
Please note that this intall step differs from that in the Source Code Contributor Guide.
Make sure that you include
[docs] in the argument to install additional dependencies that are
required to build the documentation. This argument may need to be quoted on the command line as
You are now ready to modify the Font Bakery documentation files and test your changes.
When your work is complete, deactivate the virtual environment with the following command:
Documentation Style Guide
We follow the Google Python Style Guide docstring format. Documentation with appropriately formatted Python source file docstrings are automatically parsed into formatted documentation files that are displayed on Read The Docs. Please read the Style Guide and follow this format for documentation that you contribute to the Font Bakery project.
Build Local Documentation
Navigate to the
docs directory of the Font Bakery repository and use one of the two following commands:
make is installed on your system, use:
$ make html
make is not installed on your system, use:
$ sphinx-build -b html source _build
Review Local Documentation
The compiled files are found on the path
docs/_build/html. Open the
index.html file in your browser
to view your edits and confirm that they render as expected.
Propose Documentation Changes
All proposals for documentation edits, including submissions by project members, require a review process. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests to submit your changes for review.
The Font Bakery source code test suite is executed by the Travis CI testing service when you submit a pull request to the repository. Please verify that all tests pass with your pull request. Pull requests cannot be merged if any test fails as a result of your project documentation edits.
The Travis CI build logs can be viewed at https://travis-ci.org/googlefonts/fontbakery.
The Font Bakery documentation is licensed under the CC BY-SA 4.0 International License.