Documentation¶
This section explains the documentation's technology and structure, and how you can contribute.
Technology¶
This documentation uses MkDocs, a fast and simple static site generated that's geared towards building project documentation from Markdown files. In particular, this website uses MkDocs Material, which provides a clean look, easy customization, and many features for technical documentation.
Structure¶
The structure of this documentation follows the Grand Unified Theory of Documentation 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-Tos: oriented to a particular goal, showing how to solve a specific problem through a series of steps, analogous to a recipe in a cookbook.
- Reference: oriented to information, describing the machinery through dry description, analogous to an encyclopaedia article.
- Background: oriented to understanding, explaining through discursive explanation, analogous to an article on culinary social history.
Contributing¶
Contributing to the documentation is easy. Quick changes and fixing typos can be done by clicking the button in the top-right corner of a page, and editing and saving the underlying Markdown file.
More considerable contributions can be made by cloning this repository locally, and editing the Markdown files there. The easiest way to get a live preview (automatically reloading) of your changes, is by installing Docker and executing make from the root directory. This will serve the latest changes to localhost:8000.
MkDocs Reference Extensions Reference
Created: October 17, 2024