Writing documentation

Getting started

General file structure

All documentation is built from the docs/. The docs/ directory contains configuration files for Sphinx and reStructuredText (ReST; .rst) files that are rendered to documentation pages.

Setting up the doc build

The documentation for FastF1 is generated from reStructuredText (ReST) using the Sphinx documentation generation tool.

To build the documentation you will need to set up FastF1 for development.

Building the docs

The documentation sources are found in the docs/ directory in the trunk. The configuration file for Sphinx is docs/conf.py. It controls which directories Sphinx parses, how the docs are built, and how the extensions are used. To build the documentation in html format run the following command from the docs/ directory:

make html

The documentation build expects the cache directory doc_cache/ to exist in the project root. You will have to create it manually the first time you build the documentation.

The generated documentation can be found in docs/_build/html and viewed in an internet browser by opening the html files. Run the following command to open the homepage of the documentation build:

make show

Writing documentation

In general, the style guidelines and formatting conventions described in https://matplotlib.org/stable/devel/documenting_mpl.html should be applied to FastF1 as well.

One notable exception is that FastF1 uses the google docstring standard instead of the numpydoc format.