Project Documentation

This page describes:

  1. Our project’s documentation style,

  2. The tools used for documentation,

  3. Read the Docs where the documentation for this project is hosted.

Style and Tools

The Sphinx docstring format is used throughout our project’s codebase to allow for the easy understanding of classes, methods and functions. This format allows for the easy generation of html documentation pages. It also checks for docstrings that have been added to the project’s pyLint configuration.

To install the packages required to work with the documentation, please ensure the projects dev dependencies are installed:

pip install pytest-flakefighters[dev]

Sphinx

This project makes use of Sphinx, to generate documentation. The documentation for the project sits within the docs/ directory inside the project root. To manually build the docs, first navigate to the docs/ directory and run:

make html

This will populate docs/build/ with static html pages containing the docs. To cleanup the compiled docs you can run:

make clean

The source reStructuredText files (.rst) files can be found within the docs/source directory, which contains the handwritten documentation pages and get compiled by the make commands.

Autodoc & AutoAPI

Autodoc is an extension to Sphinx that can import code modules and compile documentation from their docstrings.

AutoAPI is a third party Sphinx tool for recursively discovering code modules and compiling them into a logical doctree structure

The configuration for Sphinx, Autodoc and AutoAPI can all be found in /docs/source/conf.py.

ReadTheDocs

Read the Docs is a documentation hosting site that hosts, versions and builds documentation for free for open source projects.

This project makes use of a Github Webhook to trigger the build in ReadTheDocs, further reading on this can be found here.