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 project root directory:

python setup.py build_sphinx

The documentation build expects the cache directory doc_cache/ to exist. You will have to create it the first time.

The generated documentation can be found in docs/_build/html and viewed in an internet browser by opening the html files.

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 noteable exception is that FastF1 uses the google docstring standard instead of the numpydoc format.