Documentation

In this section, we explain the documentation technology and how it is structured.

Technology

This documentation is developed with MkDocs, a fast and simple static site generated that's geared towards building project documentation from Markdown files. MkDocs uses Python-Markdown to process Markdown files, along with PyMdown Extensions. We use the Material for MkDocs theme which provides a clean look, easy customization, and many features for technical documentation.

We use the following MkDocs plugins:

• mkdocs-macros-plugin to enable the use of variables, macros, and filters in Markdown files.
• mkdocs-git-revision-date-plugin to add a changed date to the footer based on the last time the file was changed in the Git repository.

The documentation is automatically built and published on a commit to the master branch of this repository using the GitHub actions workflow at .github/workflows/documentation.yml.

Structure

The structure of this documentation follows The documentation system where documentation is split into four categories:

• Tutorials: oriented to learning, enabling newcomers to get started through a lesson, analogous to teaching a child how to cook.
• How-to guides: oriented to a particular goal, showing how to solve a specific problem through a series of steps, analogous to a recipe in a cookery book.
• Reference: oriented to information, describing the machinery through dry description, analogous to an encyclopaedia article.
• Explanation: oriented to understanding, explaining through discursive explanation, analogous to an article on culinary social history.